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_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.
57 struct list_head list;
61 * Describes a pxe menu as given via pxe files.
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
71 * labels - a list of labels defined for the menu.
79 struct list_head labels;
83 typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path,
84 char *file_addr, ulong *filesizep);
87 * struct pxe_context - context information for PXE parsing
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
95 * @pxe_file_size: Size of the PXE file
96 * @use_ipv6: TRUE : use IPv6 addressing, FALSE : use IPv4 addressing
99 struct cmd_tbl *cmdtp;
101 * getfile() - read a file
104 * @file_path: Path to the file
105 * @file_addr: String containing the hex address to put the file in
107 * @filesizep: Returns the file size in bytes
108 * Return 0 if OK, -ve on error
110 pxe_getfile_func getfile;
120 * destroy_pxe_menu() - Destroy an allocated pxe structure
122 * Free the memory used by a pxe_menu and its labels
124 * @cfg: Config to destroy, previous returned from parse_pxefile()
126 void destroy_pxe_menu(struct pxe_menu *cfg);
129 * get_pxe_file() - Read a file
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.
136 * @file_path: Path to file
137 * @file_addr: Address to place file
138 * Returns 1 on success, or < 0 for error
140 int get_pxe_file(struct pxe_context *ctx, const char *file_path,
144 * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg
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().
151 * @file: Relative path to file
152 * @pxefile_addr_r: Address to load file
153 * Returns 1 on success or < 0 on error.
155 int get_pxelinux_path(struct pxe_context *ctx, const char *file,
156 ulong pxefile_addr_r);
159 * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu.
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.
167 * If this function returns, there weren't any labels that successfully
168 * booted, or the user interrupted the menu selection via ctrl+c.
173 void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg);
176 * parse_pxefile() - Parsing a pxe file
178 * This is only used for the top-level file.
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.
186 struct pxe_menu *parse_pxefile(struct pxe_context *ctx, ulong menucfg);
189 * format_mac_pxe() - Convert a MAC address to PXE format
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.
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.
202 int format_mac_pxe(char *outbuf, size_t outbuf_len);
205 * pxe_setup_ctx() - Setup a new PXE context
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
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
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);
224 * pxe_destroy_ctx() - Destroy a PXE context
226 * @ctx: Context to destroy
228 void pxe_destroy_ctx(struct pxe_context *ctx);
231 * pxe_process() - Process a PXE file through to boot
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
237 int pxe_process(struct pxe_context *ctx, ulong pxefile_addr_r, bool prompt);
240 * pxe_get_file_size() - Read the value of the 'filesize' environment variable
242 * @sizep: Place to put the value
243 * Return: 0 if OK, -ENOENT if no such variable, -EINVAL if format is invalid
245 int pxe_get_file_size(ulong *sizep);
248 * pxe_get() - Get the PXE file from the server
250 * This tries various filenames to obtain a PXE file
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
261 int pxe_get(ulong pxefile_addr_r, char **bootdirp, ulong *sizep, bool use_ipv6);
263 #endif /* __PXE_UTILS_H */