[PATCH 02/28] pxe: Move API comments to the header files

From: Simon Glass <sjg@chromium.org>
To: U-Boot Mailing List <u-boot@lists.denx.de>
Cc: Ilias Apalodimas <ilias.apalodimas@linaro.org>,
	Steffen Jaeckel <jaeckel-floss@eyet-services.de>,
	Michal Simek <michal.simek@xilinx.com>,
	Tom Rini <trini@konsulko.com>, Dennis Gilmore <dennis@ausil.us>,
	Daniel Schwierzeck <daniel.schwierzeck@gmail.com>,
	Lukas Auer <lukas.auer@aisec.fraunhofer.de>,
	Simon Glass <sjg@chromium.org>
Subject: [PATCH 02/28] pxe: Move API comments to the header files
Date: Wed, 18 Aug 2021 21:45:35 -0600	[thread overview]
Message-ID: <20210819034601.1618773-3-sjg@chromium.org> (raw)
In-Reply-To: <20210819034601.1618773-1-sjg@chromium.org>

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 <sjg@chromium.org>
---

 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

