include/pxe_utils.h

   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  */
  40 struct 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  */
  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
  82 struct pxe_context;
  83 typedef 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  */
  98 struct 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  */
 126 void 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  */
 140 int 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  */
 155 int 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  */
 173 void 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  */
 186 struct 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  */
 202 int 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  */
 219 int 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  */
 228 void 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  */
 237 int 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  */
 245 int 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  */
 261 int pxe_get(ulong pxefile_addr_r, char **bootdirp, ulong *sizep, bool use_ipv6);
 262
 263 #endif /* __PXE_UTILS_H */