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