blob: 1e5e8424f53fb61c5119637434617dc423a2c8c5 [file] [log] [blame]
Patrice Chotard2373cba2019-11-25 09:07:37 +01001/* SPDX-License-Identifier: GPL-2.0+ */
2
3#ifndef __PXE_UTILS_H
4#define __PXE_UTILS_H
5
Simon Glass401d1c42020-10-30 21:38:53 -06006#include <linux/list.h>
7
Patrice Chotard2373cba2019-11-25 09:07:37 +01008/*
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.
Patrick Delaunaya5dacef2022-10-28 11:01:19 +020031 * kernel_label - the kernel label, including FIT config if present.
Patrice Chotard2373cba2019-11-25 09:07:37 +010032 * 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.
Zhang Ning02901462022-02-01 08:33:37 +080037 * kaslrseed - 1 if generate kaslrseed from hw_rng
Patrice Chotard2373cba2019-11-25 09:07:37 +010038 * 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;
Patrick Delaunaya5dacef2022-10-28 11:01:19 +020044 char *kernel_label;
Patrice Chotard2373cba2019-11-25 09:07:37 +010045 char *kernel;
46 char *config;
47 char *append;
48 char *initrd;
49 char *fdt;
50 char *fdtdir;
Neil Armstrong69076df2021-01-20 09:54:53 +010051 char *fdtoverlays;
Patrice Chotard2373cba2019-11-25 09:07:37 +010052 int ipappend;
53 int attempted;
54 int localboot;
55 int localboot_val;
Zhang Ning02901462022-02-01 08:33:37 +080056 int kaslrseed;
Patrice Chotard2373cba2019-11-25 09:07:37 +010057 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
Simon Glassb1ead6b2021-10-14 12:47:57 -060082struct pxe_context;
83typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path,
Simon Glass4d79e882021-10-14 12:48:08 -060084 char *file_addr, ulong *filesizep);
Simon Glassfd3fa5c2021-10-14 12:47:56 -060085
86/**
87 * struct pxe_context - context information for PXE parsing
88 *
89 * @cmdtp: Pointer to command table to use when calling other commands
Simon Glassb1ead6b2021-10-14 12:47:57 -060090 * @getfile: Function called by PXE to read a file
Simon Glass4ad5d512021-10-14 12:47:58 -060091 * @userdata: Data the caller requires for @getfile
Simon Glass8018b9a2021-10-14 12:47:59 -060092 * @allow_abs_path: true to allow absolute paths
Simon Glass12df8422021-10-14 12:48:04 -060093 * @bootdir: Directory that files are loaded from ("" if no directory). This is
94 * allocated
Simon Glass4d79e882021-10-14 12:48:08 -060095 * @pxe_file_size: Size of the PXE file
Simon Glassfd3fa5c2021-10-14 12:47:56 -060096 */
97struct pxe_context {
98 struct cmd_tbl *cmdtp;
Simon Glassb1ead6b2021-10-14 12:47:57 -060099 /**
100 * getfile() - read a file
101 *
102 * @ctx: PXE context
103 * @file_path: Path to the file
104 * @file_addr: String containing the hex address to put the file in
105 * memory
Simon Glass4d79e882021-10-14 12:48:08 -0600106 * @filesizep: Returns the file size in bytes
Simon Glassb1ead6b2021-10-14 12:47:57 -0600107 * Return 0 if OK, -ve on error
108 */
109 pxe_getfile_func getfile;
Simon Glass4ad5d512021-10-14 12:47:58 -0600110
111 void *userdata;
Simon Glass8018b9a2021-10-14 12:47:59 -0600112 bool allow_abs_path;
Simon Glass12df8422021-10-14 12:48:04 -0600113 char *bootdir;
Simon Glass4d79e882021-10-14 12:48:08 -0600114 ulong pxe_file_size;
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600115};
116
117/**
118 * destroy_pxe_menu() - Destroy an allocated pxe structure
119 *
120 * Free the memory used by a pxe_menu and its labels
121 *
122 * @cfg: Config to destroy, previous returned from parse_pxefile()
123 */
Patrice Chotard2373cba2019-11-25 09:07:37 +0100124void destroy_pxe_menu(struct pxe_menu *cfg);
Simon Glass3d246362021-10-14 12:47:55 -0600125
126/**
127 * get_pxe_file() - Read a file
128 *
129 * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If
130 * 'bootfile' was specified in the environment, the path to bootfile will be
131 * prepended to 'file_path' and the resulting path will be used.
132 *
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600133 * @ctx: PXE context
Simon Glass3d246362021-10-14 12:47:55 -0600134 * @file_path: Path to file
135 * @file_addr: Address to place file
136 * Returns 1 on success, or < 0 for error
137 */
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600138int get_pxe_file(struct pxe_context *ctx, const char *file_path,
Simon Glass3d246362021-10-14 12:47:55 -0600139 ulong file_addr);
140
141/**
142 * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg
143 *
144 * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file()
145 * to do the hard work, the location of the 'pxelinux.cfg' folder is generated
146 * from the bootfile path, as described in get_pxe_file().
147 *
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600148 * @ctx: PXE context
Simon Glass3d246362021-10-14 12:47:55 -0600149 * @file: Relative path to file
150 * @pxefile_addr_r: Address to load file
151 * Returns 1 on success or < 0 on error.
152 */
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600153int get_pxelinux_path(struct pxe_context *ctx, const char *file,
Simon Glass3d246362021-10-14 12:47:55 -0600154 ulong pxefile_addr_r);
155
156/**
157 * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu.
158 *
159 * Use the menu system to either get the user's choice or the default, based
160 * on config or user input. If there is no default or user's choice,
161 * attempted to boot labels in the order they were given in pxe files.
162 * If the default or user's choice fails to boot, attempt to boot other
163 * labels in the order they were given in pxe files.
164 *
165 * If this function returns, there weren't any labels that successfully
166 * booted, or the user interrupted the menu selection via ctrl+c.
167 *
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600168 * @ctx: PXE context
Simon Glass3d246362021-10-14 12:47:55 -0600169 * @cfg: PXE menu
170 */
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600171void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg);
Simon Glass3d246362021-10-14 12:47:55 -0600172
173/**
174 * parse_pxefile() - Parsing a pxe file
175 *
176 * This is only used for the top-level file.
177 *
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600178 * @ctx: PXE context (provided by the caller)
Simon Glass3d246362021-10-14 12:47:55 -0600179 * Returns NULL if there is an error, otherwise, returns a pointer to a
180 * pxe_menu struct populated with the results of parsing the pxe file (and any
181 * files it includes). The resulting pxe_menu struct can be free()'d by using
182 * the destroy_pxe_menu() function.
183 */
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600184struct pxe_menu *parse_pxefile(struct pxe_context *ctx, ulong menucfg);
Simon Glass3d246362021-10-14 12:47:55 -0600185
186/**
187 * format_mac_pxe() - Convert a MAC address to PXE format
188 *
189 * Convert an ethaddr from the environment to the format used by pxelinux
190 * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to
191 * the beginning of the ethernet address to indicate a hardware type of
192 * Ethernet. Also converts uppercase hex characters into lowercase, to match
193 * pxelinux's behavior.
194 *
195 * @outbuf: Buffer to hold the output (must hold 22 bytes)
196 * @outbuf_len: Length of buffer
197 * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the
198 * environment, or some other value < 0 on error.
199 */
Patrice Chotard2373cba2019-11-25 09:07:37 +0100200int format_mac_pxe(char *outbuf, size_t outbuf_len);
201
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600202/**
203 * pxe_setup_ctx() - Setup a new PXE context
204 *
205 * @ctx: Context to set up
206 * @cmdtp: Command table entry which started this action
Simon Glassb1ead6b2021-10-14 12:47:57 -0600207 * @getfile: Function to call to read a file
Simon Glass4ad5d512021-10-14 12:47:58 -0600208 * @userdata: Data the caller requires for @getfile - stored in ctx->userdata
Simon Glass8018b9a2021-10-14 12:47:59 -0600209 * @allow_abs_path: true to allow absolute paths
Simon Glass12df8422021-10-14 12:48:04 -0600210 * @bootfile: Bootfile whose directory loaded files are relative to, NULL if
211 * none
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100212 * Return: 0 if OK, -ENOMEM if out of memory, -E2BIG if bootfile is larger than
Simon Glass74b7a2b2021-10-14 12:48:05 -0600213 * MAX_TFTP_PATH_LEN bytes
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600214 */
Simon Glass12df8422021-10-14 12:48:04 -0600215int pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp,
216 pxe_getfile_func getfile, void *userdata,
217 bool allow_abs_path, const char *bootfile);
218
219/**
220 * pxe_destroy_ctx() - Destroy a PXE context
221 *
222 * @ctx: Context to destroy
223 */
224void pxe_destroy_ctx(struct pxe_context *ctx);
Simon Glassfd3fa5c2021-10-14 12:47:56 -0600225
Simon Glass9e62e7c2021-10-14 12:48:03 -0600226/**
227 * pxe_process() - Process a PXE file through to boot
228 *
229 * @ctx: PXE context created with pxe_setup_ctx()
230 * @pxefile_addr_r: Address to load file
231 * @prompt: Force a prompt for the user
232 */
233int pxe_process(struct pxe_context *ctx, ulong pxefile_addr_r, bool prompt);
234
Simon Glass4d79e882021-10-14 12:48:08 -0600235/**
236 * pxe_get_file_size() - Read the value of the 'filesize' environment variable
237 *
238 * @sizep: Place to put the value
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100239 * Return: 0 if OK, -ENOENT if no such variable, -EINVAL if format is invalid
Simon Glass4d79e882021-10-14 12:48:08 -0600240 */
241int pxe_get_file_size(ulong *sizep);
242
Simon Glassd50244e2021-10-14 12:48:11 -0600243/**
244 * pxe_get() - Get the PXE file from the server
245 *
246 * This tries various filenames to obtain a PXE file
247 *
248 * @pxefile_addr_r: Address to put file
249 * @bootdirp: Returns the boot filename, or NULL if none. This is the 'bootfile'
250 * option provided by the DHCP server. If none, returns NULL. For example,
251 * "rpi/info", which indicates that all files should be fetched from the
252 * "rpi/" subdirectory
253 * @sizep: Size of the PXE file (not bootfile)
254 */
255int pxe_get(ulong pxefile_addr_r, char **bootdirp, ulong *sizep);
256
Patrice Chotard2373cba2019-11-25 09:07:37 +0100257#endif /* __PXE_UTILS_H */