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

Tue Nov 9 09:07:29 CET 2021

On Thu, Oct 14, 2021 at 9:49 PM Simon Glass <sjg at chromium.org> wrote:
>
> 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 at chromium.org>
> ---
>
> (no changes since v1)
>
>  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.1079.g6e70778dc9-goog
>
Reviewed-by: Ramon Fried <rfried.dev at gmail.com>