1/* SPDX-License-Identifier: GPL-2.0+ */ 2 3#ifndef __PXE_UTILS_H 4#define __PXE_UTILS_H 5 6#include <linux/list.h> 7 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_label - the kernel label, including FIT config if present. 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. 37 * kaslrseed - 1 if generate kaslrseed from hw_rng 38 * list - lets these form a list, which a pxe_menu struct will hold. 39 */ 40struct pxe_label { 41 char num[4]; 42 char *name; 43 char *menu; 44 char *kernel_label; 45 char *kernel; 46 char *config; 47 char *append; 48 char *initrd; 49 char *fdt; 50 char *fdtdir; 51 char *fdtoverlays; 52 int ipappend; 53 int attempted; 54 int localboot; 55 int localboot_val; 56 int kaslrseed; 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 */ 73struct 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 82struct pxe_context; 83typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path, 84 char *file_addr, ulong *filesizep); 85 86/** 87 * struct pxe_context - context information for PXE parsing 88 * 89 * @cmdtp: Pointer to command table to use when calling other commands 90 * @getfile: Function called by PXE to read a file 91 * @userdata: Data the caller requires for @getfile 92 * @allow_abs_path: true to allow absolute paths 93 * @bootdir: Directory that files are loaded from ("" if no directory). This is 94 * allocated 95 * @pxe_file_size: Size of the PXE file 96 * @use_ipv6: TRUE : use IPv6 addressing, FALSE : use IPv4 addressing 97 */ 98struct pxe_context { 99 struct cmd_tbl *cmdtp; 100 /** 101 * getfile() - read a file 102 * 103 * @ctx: PXE context 104 * @file_path: Path to the file 105 * @file_addr: String containing the hex address to put the file in 106 * memory 107 * @filesizep: Returns the file size in bytes 108 * Return 0 if OK, -ve on error 109 */ 110 pxe_getfile_func getfile; 111 112 void *userdata; 113 bool allow_abs_path; 114 char *bootdir; 115 ulong pxe_file_size; 116 bool use_ipv6; 117}; 118 119/** 120 * destroy_pxe_menu() - Destroy an allocated pxe structure 121 * 122 * Free the memory used by a pxe_menu and its labels 123 * 124 * @cfg: Config to destroy, previous returned from parse_pxefile() 125 */ 126void destroy_pxe_menu(struct pxe_menu *cfg); 127 128/** 129 * get_pxe_file() - Read a file 130 * 131 * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If 132 * 'bootfile' was specified in the environment, the path to bootfile will be 133 * prepended to 'file_path' and the resulting path will be used. 134 * 135 * @ctx: PXE context 136 * @file_path: Path to file 137 * @file_addr: Address to place file 138 * Returns 1 on success, or < 0 for error 139 */ 140int get_pxe_file(struct pxe_context *ctx, const char *file_path, 141 ulong file_addr); 142 143/** 144 * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg 145 * 146 * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file() 147 * to do the hard work, the location of the 'pxelinux.cfg' folder is generated 148 * from the bootfile path, as described in get_pxe_file(). 149 * 150 * @ctx: PXE context 151 * @file: Relative path to file 152 * @pxefile_addr_r: Address to load file 153 * Returns 1 on success or < 0 on error. 154 */ 155int get_pxelinux_path(struct pxe_context *ctx, const char *file, 156 ulong pxefile_addr_r); 157 158/** 159 * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu. 160 * 161 * Use the menu system to either get the user's choice or the default, based 162 * on config or user input. If there is no default or user's choice, 163 * attempted to boot labels in the order they were given in pxe files. 164 * If the default or user's choice fails to boot, attempt to boot other 165 * labels in the order they were given in pxe files. 166 * 167 * If this function returns, there weren't any labels that successfully 168 * booted, or the user interrupted the menu selection via ctrl+c. 169 * 170 * @ctx: PXE context 171 * @cfg: PXE menu 172 */ 173void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg); 174 175/** 176 * parse_pxefile() - Parsing a pxe file 177 * 178 * This is only used for the top-level file. 179 * 180 * @ctx: PXE context (provided by the caller) 181 * Returns NULL if there is an error, otherwise, returns a pointer to a 182 * pxe_menu struct populated with the results of parsing the pxe file (and any 183 * files it includes). The resulting pxe_menu struct can be free()'d by using 184 * the destroy_pxe_menu() function. 185 */ 186struct pxe_menu *parse_pxefile(struct pxe_context *ctx, ulong menucfg); 187 188/** 189 * format_mac_pxe() - Convert a MAC address to PXE format 190 * 191 * Convert an ethaddr from the environment to the format used by pxelinux 192 * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to 193 * the beginning of the ethernet address to indicate a hardware type of 194 * Ethernet. Also converts uppercase hex characters into lowercase, to match 195 * pxelinux's behavior. 196 * 197 * @outbuf: Buffer to hold the output (must hold 22 bytes) 198 * @outbuf_len: Length of buffer 199 * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the 200 * environment, or some other value < 0 on error. 201 */ 202int format_mac_pxe(char *outbuf, size_t outbuf_len); 203 204/** 205 * pxe_setup_ctx() - Setup a new PXE context 206 * 207 * @ctx: Context to set up 208 * @cmdtp: Command table entry which started this action 209 * @getfile: Function to call to read a file 210 * @userdata: Data the caller requires for @getfile - stored in ctx->userdata 211 * @allow_abs_path: true to allow absolute paths 212 * @bootfile: Bootfile whose directory loaded files are relative to, NULL if 213 * none 214 * @use_ipv6: TRUE : use IPv6 addressing 215 * FALSE : use IPv4 addressing 216 * Return: 0 if OK, -ENOMEM if out of memory, -E2BIG if bootfile is larger than 217 * MAX_TFTP_PATH_LEN bytes 218 */ 219int pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp, 220 pxe_getfile_func getfile, void *userdata, 221 bool allow_abs_path, const char *bootfile, bool use_ipv6); 222 223/** 224 * pxe_destroy_ctx() - Destroy a PXE context 225 * 226 * @ctx: Context to destroy 227 */ 228void pxe_destroy_ctx(struct pxe_context *ctx); 229 230/** 231 * pxe_process() - Process a PXE file through to boot 232 * 233 * @ctx: PXE context created with pxe_setup_ctx() 234 * @pxefile_addr_r: Address to load file 235 * @prompt: Force a prompt for the user 236 */ 237int pxe_process(struct pxe_context *ctx, ulong pxefile_addr_r, bool prompt); 238 239/** 240 * pxe_get_file_size() - Read the value of the 'filesize' environment variable 241 * 242 * @sizep: Place to put the value 243 * Return: 0 if OK, -ENOENT if no such variable, -EINVAL if format is invalid 244 */ 245int pxe_get_file_size(ulong *sizep); 246 247/** 248 * pxe_get() - Get the PXE file from the server 249 * 250 * This tries various filenames to obtain a PXE file 251 * 252 * @pxefile_addr_r: Address to put file 253 * @bootdirp: Returns the boot filename, or NULL if none. This is the 'bootfile' 254 * option provided by the DHCP server. If none, returns NULL. For example, 255 * "rpi/info", which indicates that all files should be fetched from the 256 * "rpi/" subdirectory 257 * @sizep: Size of the PXE file (not bootfile) 258 * @use_ipv6: TRUE : use IPv6 addressing 259 * FALSE : use IPv4 addressing 260 */ 261int pxe_get(ulong pxefile_addr_r, char **bootdirp, ulong *sizep, bool use_ipv6); 262 263#endif /* __PXE_UTILS_H */ 264