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. |
Patrick Delaunay | a5dacef | 2022-10-28 11:01:19 +0200 | [diff] [blame] | 31 | * kernel_label - the kernel label, including FIT config if present. |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 32 | * kernel - the path to the kernel file to use for this label. |
| 33 | * append - kernel command line to use when booting this label |
| 34 | * initrd - path to the initrd to use for this label. |
| 35 | * attempted - 0 if we haven't tried to boot this label, 1 if we have. |
| 36 | * localboot - 1 if this label specified 'localboot', 0 otherwise. |
Zhang Ning | 0290146 | 2022-02-01 08:33:37 +0800 | [diff] [blame] | 37 | * kaslrseed - 1 if generate kaslrseed from hw_rng |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 38 | * list - lets these form a list, which a pxe_menu struct will hold. |
| 39 | */ |
| 40 | struct pxe_label { |
| 41 | char num[4]; |
| 42 | char *name; |
| 43 | char *menu; |
Patrick Delaunay | a5dacef | 2022-10-28 11:01:19 +0200 | [diff] [blame] | 44 | char *kernel_label; |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 45 | char *kernel; |
| 46 | char *config; |
| 47 | char *append; |
| 48 | char *initrd; |
| 49 | char *fdt; |
| 50 | char *fdtdir; |
Neil Armstrong | 69076df | 2021-01-20 09:54:53 +0100 | [diff] [blame] | 51 | char *fdtoverlays; |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 52 | int ipappend; |
| 53 | int attempted; |
| 54 | int localboot; |
| 55 | int localboot_val; |
Zhang Ning | 0290146 | 2022-02-01 08:33:37 +0800 | [diff] [blame] | 56 | int kaslrseed; |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 57 | struct list_head list; |
| 58 | }; |
| 59 | |
| 60 | /* |
| 61 | * Describes a pxe menu as given via pxe files. |
| 62 | * |
| 63 | * title - the name of the menu as given by a 'menu title' line. |
| 64 | * default_label - the name of the default label, if any. |
| 65 | * bmp - the bmp file name which is displayed in background |
| 66 | * timeout - time in tenths of a second to wait for a user key-press before |
| 67 | * booting the default label. |
| 68 | * prompt - if 0, don't prompt for a choice unless the timeout period is |
| 69 | * interrupted. If 1, always prompt for a choice regardless of |
| 70 | * timeout. |
| 71 | * labels - a list of labels defined for the menu. |
| 72 | */ |
| 73 | struct pxe_menu { |
| 74 | char *title; |
| 75 | char *default_label; |
| 76 | char *bmp; |
| 77 | int timeout; |
| 78 | int prompt; |
| 79 | struct list_head labels; |
| 80 | }; |
| 81 | |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame] | 82 | struct pxe_context; |
| 83 | typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path, |
Simon Glass | 4d79e88 | 2021-10-14 12:48:08 -0600 | [diff] [blame] | 84 | char *file_addr, ulong *filesizep); |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 85 | |
| 86 | /** |
| 87 | * struct pxe_context - context information for PXE parsing |
| 88 | * |
| 89 | * @cmdtp: Pointer to command table to use when calling other commands |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame] | 90 | * @getfile: Function called by PXE to read a file |
Simon Glass | 4ad5d51 | 2021-10-14 12:47:58 -0600 | [diff] [blame] | 91 | * @userdata: Data the caller requires for @getfile |
Simon Glass | 8018b9a | 2021-10-14 12:47:59 -0600 | [diff] [blame] | 92 | * @allow_abs_path: true to allow absolute paths |
Simon Glass | 12df842 | 2021-10-14 12:48:04 -0600 | [diff] [blame] | 93 | * @bootdir: Directory that files are loaded from ("" if no directory). This is |
| 94 | * allocated |
Simon Glass | 4d79e88 | 2021-10-14 12:48:08 -0600 | [diff] [blame] | 95 | * @pxe_file_size: Size of the PXE file |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 96 | */ |
| 97 | struct pxe_context { |
| 98 | struct cmd_tbl *cmdtp; |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame] | 99 | /** |
| 100 | * getfile() - read a file |
| 101 | * |
| 102 | * @ctx: PXE context |
| 103 | * @file_path: Path to the file |
| 104 | * @file_addr: String containing the hex address to put the file in |
| 105 | * memory |
Simon Glass | 4d79e88 | 2021-10-14 12:48:08 -0600 | [diff] [blame] | 106 | * @filesizep: Returns the file size in bytes |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame] | 107 | * Return 0 if OK, -ve on error |
| 108 | */ |
| 109 | pxe_getfile_func getfile; |
Simon Glass | 4ad5d51 | 2021-10-14 12:47:58 -0600 | [diff] [blame] | 110 | |
| 111 | void *userdata; |
Simon Glass | 8018b9a | 2021-10-14 12:47:59 -0600 | [diff] [blame] | 112 | bool allow_abs_path; |
Simon Glass | 12df842 | 2021-10-14 12:48:04 -0600 | [diff] [blame] | 113 | char *bootdir; |
Simon Glass | 4d79e88 | 2021-10-14 12:48:08 -0600 | [diff] [blame] | 114 | ulong pxe_file_size; |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 115 | }; |
| 116 | |
| 117 | /** |
| 118 | * destroy_pxe_menu() - Destroy an allocated pxe structure |
| 119 | * |
| 120 | * Free the memory used by a pxe_menu and its labels |
| 121 | * |
| 122 | * @cfg: Config to destroy, previous returned from parse_pxefile() |
| 123 | */ |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 124 | void destroy_pxe_menu(struct pxe_menu *cfg); |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 125 | |
| 126 | /** |
| 127 | * get_pxe_file() - Read a file |
| 128 | * |
| 129 | * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If |
| 130 | * 'bootfile' was specified in the environment, the path to bootfile will be |
| 131 | * prepended to 'file_path' and the resulting path will be used. |
| 132 | * |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 133 | * @ctx: PXE context |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 134 | * @file_path: Path to file |
| 135 | * @file_addr: Address to place file |
| 136 | * Returns 1 on success, or < 0 for error |
| 137 | */ |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 138 | int get_pxe_file(struct pxe_context *ctx, const char *file_path, |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 139 | ulong file_addr); |
| 140 | |
| 141 | /** |
| 142 | * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg |
| 143 | * |
| 144 | * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file() |
| 145 | * to do the hard work, the location of the 'pxelinux.cfg' folder is generated |
| 146 | * from the bootfile path, as described in get_pxe_file(). |
| 147 | * |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 148 | * @ctx: PXE context |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 149 | * @file: Relative path to file |
| 150 | * @pxefile_addr_r: Address to load file |
| 151 | * Returns 1 on success or < 0 on error. |
| 152 | */ |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 153 | int get_pxelinux_path(struct pxe_context *ctx, const char *file, |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 154 | ulong pxefile_addr_r); |
| 155 | |
| 156 | /** |
| 157 | * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu. |
| 158 | * |
| 159 | * Use the menu system to either get the user's choice or the default, based |
| 160 | * on config or user input. If there is no default or user's choice, |
| 161 | * attempted to boot labels in the order they were given in pxe files. |
| 162 | * If the default or user's choice fails to boot, attempt to boot other |
| 163 | * labels in the order they were given in pxe files. |
| 164 | * |
| 165 | * If this function returns, there weren't any labels that successfully |
| 166 | * booted, or the user interrupted the menu selection via ctrl+c. |
| 167 | * |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 168 | * @ctx: PXE context |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 169 | * @cfg: PXE menu |
| 170 | */ |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 171 | void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg); |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 172 | |
| 173 | /** |
| 174 | * parse_pxefile() - Parsing a pxe file |
| 175 | * |
| 176 | * This is only used for the top-level file. |
| 177 | * |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 178 | * @ctx: PXE context (provided by the caller) |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 179 | * Returns NULL if there is an error, otherwise, returns a pointer to a |
| 180 | * pxe_menu struct populated with the results of parsing the pxe file (and any |
| 181 | * files it includes). The resulting pxe_menu struct can be free()'d by using |
| 182 | * the destroy_pxe_menu() function. |
| 183 | */ |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 184 | struct pxe_menu *parse_pxefile(struct pxe_context *ctx, ulong menucfg); |
Simon Glass | 3d24636 | 2021-10-14 12:47:55 -0600 | [diff] [blame] | 185 | |
| 186 | /** |
| 187 | * format_mac_pxe() - Convert a MAC address to PXE format |
| 188 | * |
| 189 | * Convert an ethaddr from the environment to the format used by pxelinux |
| 190 | * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to |
| 191 | * the beginning of the ethernet address to indicate a hardware type of |
| 192 | * Ethernet. Also converts uppercase hex characters into lowercase, to match |
| 193 | * pxelinux's behavior. |
| 194 | * |
| 195 | * @outbuf: Buffer to hold the output (must hold 22 bytes) |
| 196 | * @outbuf_len: Length of buffer |
| 197 | * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the |
| 198 | * environment, or some other value < 0 on error. |
| 199 | */ |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 200 | int format_mac_pxe(char *outbuf, size_t outbuf_len); |
| 201 | |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 202 | /** |
| 203 | * pxe_setup_ctx() - Setup a new PXE context |
| 204 | * |
| 205 | * @ctx: Context to set up |
| 206 | * @cmdtp: Command table entry which started this action |
Simon Glass | b1ead6b | 2021-10-14 12:47:57 -0600 | [diff] [blame] | 207 | * @getfile: Function to call to read a file |
Simon Glass | 4ad5d51 | 2021-10-14 12:47:58 -0600 | [diff] [blame] | 208 | * @userdata: Data the caller requires for @getfile - stored in ctx->userdata |
Simon Glass | 8018b9a | 2021-10-14 12:47:59 -0600 | [diff] [blame] | 209 | * @allow_abs_path: true to allow absolute paths |
Simon Glass | 12df842 | 2021-10-14 12:48:04 -0600 | [diff] [blame] | 210 | * @bootfile: Bootfile whose directory loaded files are relative to, NULL if |
| 211 | * none |
Heinrich Schuchardt | 185f812 | 2022-01-19 18:05:50 +0100 | [diff] [blame] | 212 | * Return: 0 if OK, -ENOMEM if out of memory, -E2BIG if bootfile is larger than |
Simon Glass | 74b7a2b | 2021-10-14 12:48:05 -0600 | [diff] [blame] | 213 | * MAX_TFTP_PATH_LEN bytes |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 214 | */ |
Simon Glass | 12df842 | 2021-10-14 12:48:04 -0600 | [diff] [blame] | 215 | int pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp, |
| 216 | pxe_getfile_func getfile, void *userdata, |
| 217 | bool allow_abs_path, const char *bootfile); |
| 218 | |
| 219 | /** |
| 220 | * pxe_destroy_ctx() - Destroy a PXE context |
| 221 | * |
| 222 | * @ctx: Context to destroy |
| 223 | */ |
| 224 | void pxe_destroy_ctx(struct pxe_context *ctx); |
Simon Glass | fd3fa5c | 2021-10-14 12:47:56 -0600 | [diff] [blame] | 225 | |
Simon Glass | 9e62e7c | 2021-10-14 12:48:03 -0600 | [diff] [blame] | 226 | /** |
| 227 | * pxe_process() - Process a PXE file through to boot |
| 228 | * |
| 229 | * @ctx: PXE context created with pxe_setup_ctx() |
| 230 | * @pxefile_addr_r: Address to load file |
| 231 | * @prompt: Force a prompt for the user |
| 232 | */ |
| 233 | int pxe_process(struct pxe_context *ctx, ulong pxefile_addr_r, bool prompt); |
| 234 | |
Simon Glass | 4d79e88 | 2021-10-14 12:48:08 -0600 | [diff] [blame] | 235 | /** |
| 236 | * pxe_get_file_size() - Read the value of the 'filesize' environment variable |
| 237 | * |
| 238 | * @sizep: Place to put the value |
Heinrich Schuchardt | 185f812 | 2022-01-19 18:05:50 +0100 | [diff] [blame] | 239 | * Return: 0 if OK, -ENOENT if no such variable, -EINVAL if format is invalid |
Simon Glass | 4d79e88 | 2021-10-14 12:48:08 -0600 | [diff] [blame] | 240 | */ |
| 241 | int pxe_get_file_size(ulong *sizep); |
| 242 | |
Simon Glass | d50244e | 2021-10-14 12:48:11 -0600 | [diff] [blame] | 243 | /** |
| 244 | * pxe_get() - Get the PXE file from the server |
| 245 | * |
| 246 | * This tries various filenames to obtain a PXE file |
| 247 | * |
| 248 | * @pxefile_addr_r: Address to put file |
| 249 | * @bootdirp: Returns the boot filename, or NULL if none. This is the 'bootfile' |
| 250 | * option provided by the DHCP server. If none, returns NULL. For example, |
| 251 | * "rpi/info", which indicates that all files should be fetched from the |
| 252 | * "rpi/" subdirectory |
| 253 | * @sizep: Size of the PXE file (not bootfile) |
| 254 | */ |
| 255 | int pxe_get(ulong pxefile_addr_r, char **bootdirp, ulong *sizep); |
| 256 | |
Patrice Chotard | 2373cba | 2019-11-25 09:07:37 +0100 | [diff] [blame] | 257 | #endif /* __PXE_UTILS_H */ |