diff options
Diffstat (limited to 'include/pxe_utils.h')
| -rw-r--r-- | include/pxe_utils.h | 205 |
1 files changed, 205 insertions, 0 deletions
diff --git a/include/pxe_utils.h b/include/pxe_utils.h new file mode 100644 index 0000000000..6681442ea5 --- /dev/null +++ b/include/pxe_utils.h @@ -0,0 +1,205 @@ +/* SPDX-License-Identifier: GPL-2.0+ */ + +#ifndef __PXE_UTILS_H +#define __PXE_UTILS_H + +#include <linux/list.h> + +/* + * 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 */ |