Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
| 2 | |
| 3 | #ifndef __PXE_UTILS_H |
| 4 | #define __PXE_UTILS_H |
| 5 | |
Simon Glass | 401d1c4 | 2020-10-30 21:38:53 -0600 | [diff] [blame] | 6 | #include <linux/list.h> |
| 7 | |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 8 | /* |
| 9 | * A note on the pxe file parser. |
| 10 | * |
| 11 | * We're parsing files that use syslinux grammar, which has a few quirks. |
| 12 | * String literals must be recognized based on context - there is no |
| 13 | * quoting or escaping support. There's also nothing to explicitly indicate |
| 14 | * when a label section completes. We deal with that by ending a label |
| 15 | * section whenever we see a line that doesn't include. |
| 16 | * |
| 17 | * As with the syslinux family, this same file format could be reused in the |
| 18 | * future for non pxe purposes. The only action it takes during parsing that |
| 19 | * would throw this off is handling of include files. It assumes we're using |
| 20 | * pxe, and does a tftp download of a file listed as an include file in the |
| 21 | * middle of the parsing operation. That could be handled by refactoring it to |
| 22 | * take a 'include file getter' function. |
| 23 | */ |
| 24 | |
| 25 | /* |
| 26 | * Describes a single label given in a pxe file. |
| 27 | * |
| 28 | * Create these with the 'label_create' function given below. |
| 29 | * |
| 30 | * name - the name of the menu as given on the 'menu label' line. |
| 31 | * kernel - the path to the kernel file to use for this label. |
| 32 | * append - kernel command line to use when booting this label |
| 33 | * initrd - path to the initrd to use for this label. |
| 34 | * attempted - 0 if we haven't tried to boot this label, 1 if we have. |
| 35 | * localboot - 1 if this label specified 'localboot', 0 otherwise. |
| 36 | * list - lets these form a list, which a pxe_menu struct will hold. |
| 37 | */ |
| 38 | struct pxe_label { |
| 39 | char num[4]; |
| 40 | char *name; |
| 41 | char *menu; |
| 42 | char *kernel; |
| 43 | char *config; |
| 44 | char *append; |
| 45 | char *initrd; |
| 46 | char *fdt; |
| 47 | char *fdtdir; |
Neil Armstrong | 69076df | 2021-01-20 09:54:53 +0100 | [diff] [blame] | 48 | char *fdtoverlays; |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 49 | int ipappend; |
| 50 | int attempted; |
| 51 | int localboot; |
| 52 | int localboot_val; |
| 53 | struct list_head list; |
| 54 | }; |
| 55 | |
| 56 | /* |
| 57 | * Describes a pxe menu as given via pxe files. |
| 58 | * |
| 59 | * title - the name of the menu as given by a 'menu title' line. |
| 60 | * default_label - the name of the default label, if any. |
| 61 | * bmp - the bmp file name which is displayed in background |
| 62 | * timeout - time in tenths of a second to wait for a user key-press before |
| 63 | * booting the default label. |
| 64 | * prompt - if 0, don't prompt for a choice unless the timeout period is |
| 65 | * interrupted. If 1, always prompt for a choice regardless of |
| 66 | * timeout. |
| 67 | * labels - a list of labels defined for the menu. |
| 68 | */ |
| 69 | struct pxe_menu { |
| 70 | char *title; |
| 71 | char *default_label; |
| 72 | char *bmp; |
| 73 | int timeout; |
| 74 | int prompt; |
| 75 | struct list_head labels; |
| 76 | }; |
| 77 | |
| 78 | extern bool is_pxe; |
| 79 | |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame^] | 80 | struct pxe_context; |
| 81 | typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path, |
| 82 | char *file_addr); |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 83 | |
| 84 | /** |
| 85 | * struct pxe_context - context information for PXE parsing |
| 86 | * |
| 87 | * @cmdtp: Pointer to command table to use when calling other commands |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame^] | 88 | * @getfile: Function called by PXE to read a file |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 89 | */ |
| 90 | struct pxe_context { |
| 91 | struct cmd_tbl *cmdtp; |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame^] | 92 | /** |
| 93 | * getfile() - read a file |
| 94 | * |
| 95 | * @ctx: PXE context |
| 96 | * @file_path: Path to the file |
| 97 | * @file_addr: String containing the hex address to put the file in |
| 98 | * memory |
| 99 | * Return 0 if OK, -ve on error |
| 100 | */ |
| 101 | pxe_getfile_func getfile; |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 102 | }; |
| 103 | |
| 104 | /** |
| 105 | * destroy_pxe_menu() - Destroy an allocated pxe structure |
| 106 | * |
| 107 | * Free the memory used by a pxe_menu and its labels |
| 108 | * |
| 109 | * @cfg: Config to destroy, previous returned from parse_pxefile() |
| 110 | */ |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 111 | void destroy_pxe_menu(struct pxe_menu *cfg); |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 112 | |
| 113 | /** |
| 114 | * get_pxe_file() - Read a file |
| 115 | * |
| 116 | * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If |
| 117 | * 'bootfile' was specified in the environment, the path to bootfile will be |
| 118 | * prepended to 'file_path' and the resulting path will be used. |
| 119 | * |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 120 | * @ctx: PXE context |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 121 | * @file_path: Path to file |
| 122 | * @file_addr: Address to place file |
| 123 | * Returns 1 on success, or < 0 for error |
| 124 | */ |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 125 | int get_pxe_file(struct pxe_context *ctx, const char *file_path, |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 126 | ulong file_addr); |
| 127 | |
| 128 | /** |
| 129 | * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg |
| 130 | * |
| 131 | * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file() |
| 132 | * to do the hard work, the location of the 'pxelinux.cfg' folder is generated |
| 133 | * from the bootfile path, as described in get_pxe_file(). |
| 134 | * |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 135 | * @ctx: PXE context |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 136 | * @file: Relative path to file |
| 137 | * @pxefile_addr_r: Address to load file |
| 138 | * Returns 1 on success or < 0 on error. |
| 139 | */ |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 140 | int get_pxelinux_path(struct pxe_context *ctx, const char *file, |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 141 | ulong pxefile_addr_r); |
| 142 | |
| 143 | /** |
| 144 | * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu. |
| 145 | * |
| 146 | * Use the menu system to either get the user's choice or the default, based |
| 147 | * on config or user input. If there is no default or user's choice, |
| 148 | * attempted to boot labels in the order they were given in pxe files. |
| 149 | * If the default or user's choice fails to boot, attempt to boot other |
| 150 | * labels in the order they were given in pxe files. |
| 151 | * |
| 152 | * If this function returns, there weren't any labels that successfully |
| 153 | * booted, or the user interrupted the menu selection via ctrl+c. |
| 154 | * |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 155 | * @ctx: PXE context |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 156 | * @cfg: PXE menu |
| 157 | */ |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 158 | void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg); |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 159 | |
| 160 | /** |
| 161 | * parse_pxefile() - Parsing a pxe file |
| 162 | * |
| 163 | * This is only used for the top-level file. |
| 164 | * |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 165 | * @ctx: PXE context (provided by the caller) |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 166 | * Returns NULL if there is an error, otherwise, returns a pointer to a |
| 167 | * pxe_menu struct populated with the results of parsing the pxe file (and any |
| 168 | * files it includes). The resulting pxe_menu struct can be free()'d by using |
| 169 | * the destroy_pxe_menu() function. |
| 170 | */ |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 171 | struct pxe_menu *parse_pxefile(struct pxe_context *ctx, ulong menucfg); |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 172 | |
| 173 | /** |
| 174 | * format_mac_pxe() - Convert a MAC address to PXE format |
| 175 | * |
| 176 | * Convert an ethaddr from the environment to the format used by pxelinux |
| 177 | * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to |
| 178 | * the beginning of the ethernet address to indicate a hardware type of |
| 179 | * Ethernet. Also converts uppercase hex characters into lowercase, to match |
| 180 | * pxelinux's behavior. |
| 181 | * |
| 182 | * @outbuf: Buffer to hold the output (must hold 22 bytes) |
| 183 | * @outbuf_len: Length of buffer |
| 184 | * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the |
| 185 | * environment, or some other value < 0 on error. |
| 186 | */ |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 187 | int format_mac_pxe(char *outbuf, size_t outbuf_len); |
| 188 | |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 189 | /** |
| 190 | * pxe_setup_ctx() - Setup a new PXE context |
| 191 | * |
| 192 | * @ctx: Context to set up |
| 193 | * @cmdtp: Command table entry which started this action |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame^] | 194 | * @getfile: Function to call to read a file |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 195 | */ |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame^] | 196 | void pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp, |
| 197 | pxe_getfile_func getfile); |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 198 | |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 199 | #endif /* __PXE_UTILS_H */ |