From 3d24636e925f89841aac4482c8cc372a2b9d96a6 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Oct 2021 12:47:55 -0600 Subject: pxe: Move API comments to the header files 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 Reviewed-by: Artem Lapkin Tested-by: Artem Lapkin Reviewed-by: Ramon Fried --- cmd/pxe_utils.h | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 3 deletions(-) (limited to 'cmd/pxe_utils.h') 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 */ -- cgit v1.2.3 From fd3fa5c3941d4de0736d066f77d0158cf933e207 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Oct 2021 12:47:56 -0600 Subject: pxe: Use a context pointer At present the PXE functions pass around a pointer to command-table entry which is very strange. It is only needed in a few places and it is odd to pass around a data structure from another module in this way. For bootmethod we will need to provide some context information when reading files. Create a PXE context struct to hold the command-table-entry pointer and pass that around instead. We can then add more things to the context as needed. Signed-off-by: Simon Glass Reviewed-by: Artem Lapkin Tested-by: Artem Lapkin Reviewed-by: Ramon Fried --- cmd/pxe_utils.h | 43 +++++++++++++++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 10 deletions(-) (limited to 'cmd/pxe_utils.h') diff --git a/cmd/pxe_utils.h b/cmd/pxe_utils.h index 441beefa2bc..cd0d3371765 100644 --- a/cmd/pxe_utils.h +++ b/cmd/pxe_utils.h @@ -79,6 +79,23 @@ extern bool is_pxe; extern int (*do_getfile)(struct cmd_tbl *cmdtp, const char *file_path, char *file_addr); + +/** + * struct pxe_context - context information for PXE parsing + * + * @cmdtp: Pointer to command table to use when calling other commands + */ +struct pxe_context { + struct cmd_tbl *cmdtp; +}; + +/** + * destroy_pxe_menu() - Destroy an allocated pxe structure + * + * Free the memory used by a pxe_menu and its labels + * + * @cfg: Config to destroy, previous returned from parse_pxefile() + */ void destroy_pxe_menu(struct pxe_menu *cfg); /** @@ -88,12 +105,12 @@ void destroy_pxe_menu(struct pxe_menu *cfg); * '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 + * @ctx: PXE context * @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, +int get_pxe_file(struct pxe_context *ctx, const char *file_path, ulong file_addr); /** @@ -103,12 +120,12 @@ int get_pxe_file(struct cmd_tbl *cmdtp, const char *file_path, * 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 + * @ctx: PXE context * @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, +int get_pxelinux_path(struct pxe_context *ctx, const char *file, ulong pxefile_addr_r); /** @@ -123,25 +140,23 @@ int get_pxelinux_path(struct cmd_tbl *cmdtp, const char *file, * 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 + * @ctx: PXE context * @cfg: PXE menu */ -void handle_pxe_menu(struct cmd_tbl *cmdtp, struct pxe_menu *cfg); +void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg); /** * 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 - * + * @ctx: PXE context (provided by the caller) * 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); +struct pxe_menu *parse_pxefile(struct pxe_context *ctx, ulong menucfg); /** * format_mac_pxe() - Convert a MAC address to PXE format @@ -159,4 +174,12 @@ struct pxe_menu *parse_pxefile(struct cmd_tbl *cmdtp, ulong menucfg); */ int format_mac_pxe(char *outbuf, size_t outbuf_len); +/** + * pxe_setup_ctx() - Setup a new PXE context + * + * @ctx: Context to set up + * @cmdtp: Command table entry which started this action + */ +void pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp); + #endif /* __PXE_UTILS_H */ -- cgit v1.2.3 From b1ead6b9087f1f96cb117d72e3e5cf0d5fb708f5 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Oct 2021 12:47:57 -0600 Subject: pxe: Move do_getfile() into the context Rather than having a global variable, pass the function as part of the context. Signed-off-by: Simon Glass Reviewed-by: Artem Lapkin Tested-by: Artem Lapkin Reviewed-by: Ramon Fried --- cmd/pxe_utils.h | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) (limited to 'cmd/pxe_utils.h') diff --git a/cmd/pxe_utils.h b/cmd/pxe_utils.h index cd0d3371765..ca2696f48b0 100644 --- a/cmd/pxe_utils.h +++ b/cmd/pxe_utils.h @@ -77,16 +77,28 @@ struct pxe_menu { extern bool is_pxe; -extern int (*do_getfile)(struct cmd_tbl *cmdtp, const char *file_path, - char *file_addr); +struct pxe_context; +typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path, + char *file_addr); /** * struct pxe_context - context information for PXE parsing * * @cmdtp: Pointer to command table to use when calling other commands + * @getfile: Function called by PXE to read a file */ struct pxe_context { struct cmd_tbl *cmdtp; + /** + * getfile() - read a file + * + * @ctx: PXE context + * @file_path: Path to the file + * @file_addr: String containing the hex address to put the file in + * memory + * Return 0 if OK, -ve on error + */ + pxe_getfile_func getfile; }; /** @@ -179,7 +191,9 @@ int format_mac_pxe(char *outbuf, size_t outbuf_len); * * @ctx: Context to set up * @cmdtp: Command table entry which started this action + * @getfile: Function to call to read a file */ -void pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp); +void pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp, + pxe_getfile_func getfile); #endif /* __PXE_UTILS_H */ -- cgit v1.2.3 From 4ad5d51edb6525402b371cc8f8a3bee1b6a42414 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Oct 2021 12:47:58 -0600 Subject: pxe: Add a userdata field to the context Allow the caller to provide some info which is passed back to the readfile() method. Signed-off-by: Simon Glass Reviewed-by: Artem Lapkin Tested-by: Artem Lapkin Reviewed-by: Ramon Fried --- cmd/pxe_utils.h | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'cmd/pxe_utils.h') diff --git a/cmd/pxe_utils.h b/cmd/pxe_utils.h index ca2696f48b0..921455f694e 100644 --- a/cmd/pxe_utils.h +++ b/cmd/pxe_utils.h @@ -86,6 +86,7 @@ typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path, * * @cmdtp: Pointer to command table to use when calling other commands * @getfile: Function called by PXE to read a file + * @userdata: Data the caller requires for @getfile */ struct pxe_context { struct cmd_tbl *cmdtp; @@ -99,6 +100,8 @@ struct pxe_context { * Return 0 if OK, -ve on error */ pxe_getfile_func getfile; + + void *userdata; }; /** @@ -192,8 +195,9 @@ int format_mac_pxe(char *outbuf, size_t outbuf_len); * @ctx: Context to set up * @cmdtp: Command table entry which started this action * @getfile: Function to call to read a file + * @userdata: Data the caller requires for @getfile - stored in ctx->userdata */ void pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp, - pxe_getfile_func getfile); + pxe_getfile_func getfile, void *userdata); #endif /* __PXE_UTILS_H */ -- cgit v1.2.3 From 8018b9af57b5cd0cfddf48a8d12f04dba8b77a65 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Oct 2021 12:47:59 -0600 Subject: pxe: Tidy up the is_pxe global Move this into the context to avoid a global variable. Also rename it since the current name does not explain what it actually affects. Signed-off-by: Simon Glass Reviewed-by: Artem Lapkin Tested-by: Artem Lapkin Reviewed-by: Ramon Fried --- cmd/pxe_utils.h | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'cmd/pxe_utils.h') diff --git a/cmd/pxe_utils.h b/cmd/pxe_utils.h index 921455f694e..6681442ea55 100644 --- a/cmd/pxe_utils.h +++ b/cmd/pxe_utils.h @@ -75,8 +75,6 @@ struct pxe_menu { struct list_head labels; }; -extern bool is_pxe; - struct pxe_context; typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path, char *file_addr); @@ -87,6 +85,7 @@ typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path, * @cmdtp: Pointer to command table to use when calling other commands * @getfile: Function called by PXE to read a file * @userdata: Data the caller requires for @getfile + * @allow_abs_path: true to allow absolute paths */ struct pxe_context { struct cmd_tbl *cmdtp; @@ -102,6 +101,7 @@ struct pxe_context { pxe_getfile_func getfile; void *userdata; + bool allow_abs_path; }; /** @@ -196,8 +196,10 @@ int format_mac_pxe(char *outbuf, size_t outbuf_len); * @cmdtp: Command table entry which started this action * @getfile: Function to call to read a file * @userdata: Data the caller requires for @getfile - stored in ctx->userdata + * @allow_abs_path: true to allow absolute paths */ void pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp, - pxe_getfile_func getfile, void *userdata); + pxe_getfile_func getfile, void *userdata, + bool allow_abs_path); #endif /* __PXE_UTILS_H */ -- cgit v1.2.3 From 262cfb5b15420a1aea465745a821e684b3dfa153 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Oct 2021 12:48:00 -0600 Subject: pxe: Move pxe_utils files Move the header file into the main include/ directory so we can use it from the bootmethod code. Move the C file into boot/ since it relates to booting. Signed-off-by: Simon Glass Reviewed-by: Artem Lapkin Tested-by: Artem Lapkin Reviewed-by: Ramon Fried --- cmd/pxe_utils.h | 205 -------------------------------------------------------- 1 file changed, 205 deletions(-) delete mode 100644 cmd/pxe_utils.h (limited to 'cmd/pxe_utils.h') diff --git a/cmd/pxe_utils.h b/cmd/pxe_utils.h deleted file mode 100644 index 6681442ea55..00000000000 --- a/cmd/pxe_utils.h +++ /dev/null @@ -1,205 +0,0 @@ -/* SPDX-License-Identifier: GPL-2.0+ */ - -#ifndef __PXE_UTILS_H -#define __PXE_UTILS_H - -#include - -/* - * A note on the pxe file parser. - * - * We're parsing files that use syslinux grammar, which has a few quirks. - * String literals must be recognized based on context - there is no - * quoting or escaping support. There's also nothing to explicitly indicate - * when a label section completes. We deal with that by ending a label - * section whenever we see a line that doesn't include. - * - * As with the syslinux family, this same file format could be reused in the - * future for non pxe purposes. The only action it takes during parsing that - * would throw this off is handling of include files. It assumes we're using - * pxe, and does a tftp download of a file listed as an include file in the - * middle of the parsing operation. That could be handled by refactoring it to - * take a 'include file getter' function. - */ - -/* - * Describes a single label given in a pxe file. - * - * Create these with the 'label_create' function given below. - * - * name - the name of the menu as given on the 'menu label' line. - * kernel - the path to the kernel file to use for this label. - * append - kernel command line to use when booting this label - * initrd - path to the initrd to use for this label. - * attempted - 0 if we haven't tried to boot this label, 1 if we have. - * localboot - 1 if this label specified 'localboot', 0 otherwise. - * list - lets these form a list, which a pxe_menu struct will hold. - */ -struct pxe_label { - char num[4]; - char *name; - char *menu; - char *kernel; - char *config; - char *append; - char *initrd; - char *fdt; - char *fdtdir; - char *fdtoverlays; - int ipappend; - int attempted; - int localboot; - int localboot_val; - struct list_head list; -}; - -/* - * Describes a pxe menu as given via pxe files. - * - * title - the name of the menu as given by a 'menu title' line. - * default_label - the name of the default label, if any. - * bmp - the bmp file name which is displayed in background - * timeout - time in tenths of a second to wait for a user key-press before - * booting the default label. - * prompt - if 0, don't prompt for a choice unless the timeout period is - * interrupted. If 1, always prompt for a choice regardless of - * timeout. - * labels - a list of labels defined for the menu. - */ -struct pxe_menu { - char *title; - char *default_label; - char *bmp; - int timeout; - int prompt; - struct list_head labels; -}; - -struct pxe_context; -typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path, - char *file_addr); - -/** - * struct pxe_context - context information for PXE parsing - * - * @cmdtp: Pointer to command table to use when calling other commands - * @getfile: Function called by PXE to read a file - * @userdata: Data the caller requires for @getfile - * @allow_abs_path: true to allow absolute paths - */ -struct pxe_context { - struct cmd_tbl *cmdtp; - /** - * getfile() - read a file - * - * @ctx: PXE context - * @file_path: Path to the file - * @file_addr: String containing the hex address to put the file in - * memory - * Return 0 if OK, -ve on error - */ - pxe_getfile_func getfile; - - void *userdata; - bool allow_abs_path; -}; - -/** - * destroy_pxe_menu() - Destroy an allocated pxe structure - * - * Free the memory used by a pxe_menu and its labels - * - * @cfg: Config to destroy, previous returned from parse_pxefile() - */ -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. - * - * @ctx: PXE context - * @file_path: Path to file - * @file_addr: Address to place file - * Returns 1 on success, or < 0 for error - */ -int get_pxe_file(struct pxe_context *ctx, const char *file_path, - 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(). - * - * @ctx: PXE context - * @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 pxe_context *ctx, const char *file, - 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. - * - * @ctx: PXE context - * @cfg: PXE menu - */ -void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg); - -/** - * parse_pxefile() - Parsing a pxe file - * - * This is only used for the top-level file. - * - * @ctx: PXE context (provided by the caller) - * 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 pxe_context *ctx, 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); - -/** - * pxe_setup_ctx() - Setup a new PXE context - * - * @ctx: Context to set up - * @cmdtp: Command table entry which started this action - * @getfile: Function to call to read a file - * @userdata: Data the caller requires for @getfile - stored in ctx->userdata - * @allow_abs_path: true to allow absolute paths - */ -void pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp, - pxe_getfile_func getfile, void *userdata, - bool allow_abs_path); - -#endif /* __PXE_UTILS_H */ -- cgit v1.2.3