From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-19.5 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 06489C4338F for ; Thu, 19 Aug 2021 03:46:46 +0000 (UTC) Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 5C84C6108B for ; Thu, 19 Aug 2021 03:46:45 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 5C84C6108B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=chromium.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=lists.denx.de Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id BC23B8314D; Thu, 19 Aug 2021 05:46:29 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.b="mAD+Fd47"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 563EC8314F; Thu, 19 Aug 2021 05:46:22 +0200 (CEST) Received: from mail-oi1-x22d.google.com (mail-oi1-x22d.google.com [IPv6:2607:f8b0:4864:20::22d]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 9392282EF8 for ; Thu, 19 Aug 2021 05:46:15 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=sjg@chromium.org Received: by mail-oi1-x22d.google.com with SMTP id t35so6623035oiw.9 for ; Wed, 18 Aug 2021 20:46:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=qVBl9ucu+tcUpYOQyU98R9/zTJpx4qGaAkJVWL9uEc4=; b=mAD+Fd47rd626dKRGkYIjC4KJShALkFw2QC4Et5vwdwVO4XWrOVzQBK2umJn29YZPA m9Q3fY+U+KZgLLaC/vRXlRU4tMOtD6XQH/bFZD7FhNhmRer+cAkPIpItO8yk10hWoYyM MTNo8MjU69Ubg0JhPphEuJWwMRlLIjVVRtt5M= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=qVBl9ucu+tcUpYOQyU98R9/zTJpx4qGaAkJVWL9uEc4=; b=XtepnaUUaJJXzSebfjzUlg/6KkV38OfDBJj1hmhSkbo2x/Qnz1ZyFk82JpBhKCJmh8 KlyaIuu8WMBPo+M2n/60xWIfTHH5hrpMPI8E6a1bybYlQEtvRvMdM2B6MmLvPHUQuzmb 9CoP/cmi+6W2a8LrQn6e4nJmCr+hPjHj7jmvslgyed62LxKdDPXcCUnwr08erm79YslA ykOpH3hMeI2rxwImTqGHcONoZtElGXJLsbxqOZNC00AnFXez+djyiJawIt1yzY2/eI9u 2jcnskGtURrj/meVB3+RCo7Axp8b3JD6aFPoJ+zDlg6godu111MrSk1V/rsYPsvHkMmK n0gw== X-Gm-Message-State: AOAM533KwHmefrb/eXQeTnIwNqDrJLT/29pn/RyQn4+jIaIUHXpoPnua MnbNXZs1o5TAdtQ7inLjZ2RbgpuYHD0DaQ== X-Google-Smtp-Source: ABdhPJzfbt8mB05HW2fXdnIoFYt7/qmzLm1p+maDq/Wl3o4gyale7Xwyq0Qic6EG3mGJ7tP0n7PhQA== X-Received: by 2002:aca:34c4:: with SMTP id b187mr1116311oia.139.1629344773964; Wed, 18 Aug 2021 20:46:13 -0700 (PDT) Received: from kiwi.bld.corp.google.com (c-67-190-101-114.hsd1.co.comcast.net. [67.190.101.114]) by smtp.gmail.com with ESMTPSA id q3sm370025ooa.13.2021.08.18.20.46.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 18 Aug 2021 20:46:13 -0700 (PDT) From: Simon Glass To: U-Boot Mailing List Cc: Ilias Apalodimas , Steffen Jaeckel , Michal Simek , Tom Rini , Dennis Gilmore , Daniel Schwierzeck , Lukas Auer , Simon Glass Subject: [PATCH 02/28] pxe: Move API comments to the header files Date: Wed, 18 Aug 2021 21:45:35 -0600 Message-Id: <20210819034601.1618773-3-sjg@chromium.org> X-Mailer: git-send-email 2.33.0.rc1.237.g0d66db33f3-goog In-Reply-To: <20210819034601.1618773-1-sjg@chromium.org> References: <20210819034601.1618773-1-sjg@chromium.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.2 at phobos.denx.de X-Virus-Status: Clean Put the function comments in the header file so that the full API can we examined in one place. Expand the comments to cover parameters and return values. Signed-off-by: Simon Glass --- cmd/pxe_utils.c | 45 ----------------------------- cmd/pxe_utils.h | 77 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 74 insertions(+), 48 deletions(-) diff --git a/cmd/pxe_utils.c b/cmd/pxe_utils.c index 067c24e5ff4..d7f4017efeb 100644 --- a/cmd/pxe_utils.c +++ b/cmd/pxe_utils.c @@ -32,16 +32,6 @@ bool is_pxe; -/* - * Convert an ethaddr from the environment to the format used by pxelinux - * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to - * the beginning of the ethernet address to indicate a hardware type of - * Ethernet. Also converts uppercase hex characters into lowercase, to match - * pxelinux's behavior. - * - * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the - * environment, or some other value < 0 on error. - */ int format_mac_pxe(char *outbuf, size_t outbuf_len) { uchar ethaddr[6]; @@ -146,13 +136,6 @@ static int get_relfile(struct cmd_tbl *cmdtp, const char *file_path, return do_getfile(cmdtp, relfile, addr_buf); } -/* - * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If - * 'bootfile' was specified in the environment, the path to bootfile will be - * prepended to 'file_path' and the resulting path will be used. - * - * Returns 1 on success, or < 0 for error. - */ int get_pxe_file(struct cmd_tbl *cmdtp, const char *file_path, unsigned long file_addr) { @@ -187,13 +170,6 @@ int get_pxe_file(struct cmd_tbl *cmdtp, const char *file_path, #define PXELINUX_DIR "pxelinux.cfg/" -/* - * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file - * to do the hard work, the location of the 'pxelinux.cfg' folder is generated - * from the bootfile path, as described above. - * - * Returns 1 on success or < 0 on error. - */ int get_pxelinux_path(struct cmd_tbl *cmdtp, const char *file, unsigned long pxefile_addr_r) { @@ -1309,15 +1285,6 @@ void destroy_pxe_menu(struct pxe_menu *cfg) free(cfg); } -/* - * Entry point for parsing a pxe file. This is only used for the top level - * file. - * - * Returns NULL if there is an error, otherwise, returns a pointer to a - * pxe_menu struct populated with the results of parsing the pxe file (and any - * files it includes). The resulting pxe_menu struct can be free()'d by using - * the destroy_pxe_menu() function. - */ struct pxe_menu *parse_pxefile(struct cmd_tbl *cmdtp, unsigned long menucfg) { struct pxe_menu *cfg; @@ -1415,18 +1382,6 @@ static void boot_unattempted_labels(struct cmd_tbl *cmdtp, struct pxe_menu *cfg) } } -/* - * Boot the system as prescribed by a pxe_menu. - * - * Use the menu system to either get the user's choice or the default, based - * on config or user input. If there is no default or user's choice, - * attempted to boot labels in the order they were given in pxe files. - * If the default or user's choice fails to boot, attempt to boot other - * labels in the order they were given in pxe files. - * - * If this function returns, there weren't any labels that successfully - * booted, or the user interrupted the menu selection via ctrl+c. - */ void handle_pxe_menu(struct cmd_tbl *cmdtp, struct pxe_menu *cfg) { void *choice; diff --git a/cmd/pxe_utils.h b/cmd/pxe_utils.h index bf58e15347c..441beefa2bc 100644 --- a/cmd/pxe_utils.h +++ b/cmd/pxe_utils.h @@ -80,12 +80,83 @@ extern bool is_pxe; extern int (*do_getfile)(struct cmd_tbl *cmdtp, const char *file_path, char *file_addr); void destroy_pxe_menu(struct pxe_menu *cfg); + +/** + * get_pxe_file() - Read a file + * + * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If + * 'bootfile' was specified in the environment, the path to bootfile will be + * prepended to 'file_path' and the resulting path will be used. + * + * @cmdtp: Pointer to command-table entry for the initiating command + * @file_path: Path to file + * @file_addr: Address to place file + * Returns 1 on success, or < 0 for error + */ int get_pxe_file(struct cmd_tbl *cmdtp, const char *file_path, - unsigned long file_addr); + ulong file_addr); + +/** + * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg + * + * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file() + * to do the hard work, the location of the 'pxelinux.cfg' folder is generated + * from the bootfile path, as described in get_pxe_file(). + * + * @cmdtp: Pointer to command-table entry for the initiating command + * @file: Relative path to file + * @pxefile_addr_r: Address to load file + * Returns 1 on success or < 0 on error. + */ int get_pxelinux_path(struct cmd_tbl *cmdtp, const char *file, - unsigned long pxefile_addr_r); + ulong pxefile_addr_r); + +/** + * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu. + * + * Use the menu system to either get the user's choice or the default, based + * on config or user input. If there is no default or user's choice, + * attempted to boot labels in the order they were given in pxe files. + * If the default or user's choice fails to boot, attempt to boot other + * labels in the order they were given in pxe files. + * + * If this function returns, there weren't any labels that successfully + * booted, or the user interrupted the menu selection via ctrl+c. + * + * @cmdtp: Pointer to command-table entry for the initiating command + * @cfg: PXE menu + */ void handle_pxe_menu(struct cmd_tbl *cmdtp, struct pxe_menu *cfg); -struct pxe_menu *parse_pxefile(struct cmd_tbl *cmdtp, unsigned long menucfg); + +/** + * parse_pxefile() - Parsing a pxe file + * + * This is only used for the top-level file. + * + * @cmdtp: Pointer to command-table entry for the initiating command + * @menucfg: Address of PXE file + * + * Returns NULL if there is an error, otherwise, returns a pointer to a + * pxe_menu struct populated with the results of parsing the pxe file (and any + * files it includes). The resulting pxe_menu struct can be free()'d by using + * the destroy_pxe_menu() function. + */ +struct pxe_menu *parse_pxefile(struct cmd_tbl *cmdtp, ulong menucfg); + +/** + * format_mac_pxe() - Convert a MAC address to PXE format + * + * Convert an ethaddr from the environment to the format used by pxelinux + * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to + * the beginning of the ethernet address to indicate a hardware type of + * Ethernet. Also converts uppercase hex characters into lowercase, to match + * pxelinux's behavior. + * + * @outbuf: Buffer to hold the output (must hold 22 bytes) + * @outbuf_len: Length of buffer + * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the + * environment, or some other value < 0 on error. + */ int format_mac_pxe(char *outbuf, size_t outbuf_len); #endif /* __PXE_UTILS_H */ -- 2.33.0.rc1.237.g0d66db33f3-goog