1 /* SPDX-License-Identifier: GPL-2.0+ */
6 #include <linux/list.h>
9 * A note on the pxe file parser.
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.
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.
26 * Describes a single label given in a pxe file.
28 * Create these with the 'label_create' function given below.
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 * kaslrseed - 1 if generate kaslrseed from hw_rng
37 * list - lets these form a list, which a pxe_menu struct will hold.
55 struct list_head list;
59 * Describes a pxe menu as given via pxe files.
61 * title - the name of the menu as given by a 'menu title' line.
62 * default_label - the name of the default label, if any.
63 * bmp - the bmp file name which is displayed in background
64 * timeout - time in tenths of a second to wait for a user key-press before
65 * booting the default label.
66 * prompt - if 0, don't prompt for a choice unless the timeout period is
67 * interrupted. If 1, always prompt for a choice regardless of
69 * labels - a list of labels defined for the menu.
77 struct list_head labels;
81 typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path,
82 char *file_addr, ulong *filesizep);
85 * struct pxe_context - context information for PXE parsing
87 * @cmdtp: Pointer to command table to use when calling other commands
88 * @getfile: Function called by PXE to read a file
89 * @userdata: Data the caller requires for @getfile
90 * @allow_abs_path: true to allow absolute paths
91 * @bootdir: Directory that files are loaded from ("" if no directory). This is
93 * @pxe_file_size: Size of the PXE file
96 struct cmd_tbl *cmdtp;
98 * getfile() - read a file
101 * @file_path: Path to the file
102 * @file_addr: String containing the hex address to put the file in
104 * @filesizep: Returns the file size in bytes
105 * Return 0 if OK, -ve on error
107 pxe_getfile_func getfile;
116 * destroy_pxe_menu() - Destroy an allocated pxe structure
118 * Free the memory used by a pxe_menu and its labels
120 * @cfg: Config to destroy, previous returned from parse_pxefile()
122 void destroy_pxe_menu(struct pxe_menu *cfg);
125 * get_pxe_file() - Read a file
127 * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If
128 * 'bootfile' was specified in the environment, the path to bootfile will be
129 * prepended to 'file_path' and the resulting path will be used.
132 * @file_path: Path to file
133 * @file_addr: Address to place file
134 * Returns 1 on success, or < 0 for error
136 int get_pxe_file(struct pxe_context *ctx, const char *file_path,
140 * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg
142 * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file()
143 * to do the hard work, the location of the 'pxelinux.cfg' folder is generated
144 * from the bootfile path, as described in get_pxe_file().
147 * @file: Relative path to file
148 * @pxefile_addr_r: Address to load file
149 * Returns 1 on success or < 0 on error.
151 int get_pxelinux_path(struct pxe_context *ctx, const char *file,
152 ulong pxefile_addr_r);
155 * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu.
157 * Use the menu system to either get the user's choice or the default, based
158 * on config or user input. If there is no default or user's choice,
159 * attempted to boot labels in the order they were given in pxe files.
160 * If the default or user's choice fails to boot, attempt to boot other
161 * labels in the order they were given in pxe files.
163 * If this function returns, there weren't any labels that successfully
164 * booted, or the user interrupted the menu selection via ctrl+c.
169 void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg);
172 * parse_pxefile() - Parsing a pxe file
174 * This is only used for the top-level file.
176 * @ctx: PXE context (provided by the caller)
177 * Returns NULL if there is an error, otherwise, returns a pointer to a
178 * pxe_menu struct populated with the results of parsing the pxe file (and any
179 * files it includes). The resulting pxe_menu struct can be free()'d by using
180 * the destroy_pxe_menu() function.
182 struct pxe_menu *parse_pxefile(struct pxe_context *ctx, ulong menucfg);
185 * format_mac_pxe() - Convert a MAC address to PXE format
187 * Convert an ethaddr from the environment to the format used by pxelinux
188 * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to
189 * the beginning of the ethernet address to indicate a hardware type of
190 * Ethernet. Also converts uppercase hex characters into lowercase, to match
191 * pxelinux's behavior.
193 * @outbuf: Buffer to hold the output (must hold 22 bytes)
194 * @outbuf_len: Length of buffer
195 * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the
196 * environment, or some other value < 0 on error.
198 int format_mac_pxe(char *outbuf, size_t outbuf_len);
201 * pxe_setup_ctx() - Setup a new PXE context
203 * @ctx: Context to set up
204 * @cmdtp: Command table entry which started this action
205 * @getfile: Function to call to read a file
206 * @userdata: Data the caller requires for @getfile - stored in ctx->userdata
207 * @allow_abs_path: true to allow absolute paths
208 * @bootfile: Bootfile whose directory loaded files are relative to, NULL if
210 * Return: 0 if OK, -ENOMEM if out of memory, -E2BIG if bootfile is larger than
211 * MAX_TFTP_PATH_LEN bytes
213 int pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp,
214 pxe_getfile_func getfile, void *userdata,
215 bool allow_abs_path, const char *bootfile);
218 * pxe_destroy_ctx() - Destroy a PXE context
220 * @ctx: Context to destroy
222 void pxe_destroy_ctx(struct pxe_context *ctx);
225 * pxe_process() - Process a PXE file through to boot
227 * @ctx: PXE context created with pxe_setup_ctx()
228 * @pxefile_addr_r: Address to load file
229 * @prompt: Force a prompt for the user
231 int pxe_process(struct pxe_context *ctx, ulong pxefile_addr_r, bool prompt);
234 * pxe_get_file_size() - Read the value of the 'filesize' environment variable
236 * @sizep: Place to put the value
237 * Return: 0 if OK, -ENOENT if no such variable, -EINVAL if format is invalid
239 int pxe_get_file_size(ulong *sizep);
242 * pxe_get() - Get the PXE file from the server
244 * This tries various filenames to obtain a PXE file
246 * @pxefile_addr_r: Address to put file
247 * @bootdirp: Returns the boot filename, or NULL if none. This is the 'bootfile'
248 * option provided by the DHCP server. If none, returns NULL. For example,
249 * "rpi/info", which indicates that all files should be fetched from the
250 * "rpi/" subdirectory
251 * @sizep: Size of the PXE file (not bootfile)
253 int pxe_get(ulong pxefile_addr_r, char **bootdirp, ulong *sizep);
255 #endif /* __PXE_UTILS_H */