summaryrefslogtreecommitdiff
path: root/include/pxe_utils.h
blob: 1e5e8424f53fb61c5119637434617dc423a2c8c5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
/* SPDX-License-Identifier: GPL-2.0+ */

#ifndef __PXE_UTILS_H
#define __PXE_UTILS_H

#include <linux/list.h>

/*
 * A note on the pxe file parser.
 *
 * We're parsing files that use syslinux grammar, which has a few quirks.
 * String literals must be recognized based on context - there is no
 * quoting or escaping support. There's also nothing to explicitly indicate
 * when a label section completes. We deal with that by ending a label
 * section whenever we see a line that doesn't include.
 *
 * As with the syslinux family, this same file format could be reused in the
 * future for non pxe purposes. The only action it takes during parsing that
 * would throw this off is handling of include files. It assumes we're using
 * pxe, and does a tftp download of a file listed as an include file in the
 * middle of the parsing operation. That could be handled by refactoring it to
 * take a 'include file getter' function.
 */

/*
 * Describes a single label given in a pxe file.
 *
 * Create these with the 'label_create' function given below.
 *
 * name - the name of the menu as given on the 'menu label' line.
 * kernel_label - the kernel label, including FIT config if present.
 * kernel - the path to the kernel file to use for this label.
 * append - kernel command line to use when booting this label
 * initrd - path to the initrd to use for this label.
 * attempted - 0 if we haven't tried to boot this label, 1 if we have.
 * localboot - 1 if this label specified 'localboot', 0 otherwise.
 * kaslrseed - 1 if generate kaslrseed from hw_rng
 * list - lets these form a list, which a pxe_menu struct will hold.
 */
struct pxe_label {
	char num[4];
	char *name;
	char *menu;
	char *kernel_label;
	char *kernel;
	char *config;
	char *append;
	char *initrd;
	char *fdt;
	char *fdtdir;
	char *fdtoverlays;
	int ipappend;
	int attempted;
	int localboot;
	int localboot_val;
	int kaslrseed;
	struct list_head list;
};

/*
 * Describes a pxe menu as given via pxe files.
 *
 * title - the name of the menu as given by a 'menu title' line.
 * default_label - the name of the default label, if any.
 * bmp - the bmp file name which is displayed in background
 * timeout - time in tenths of a second to wait for a user key-press before
 *           booting the default label.
 * prompt - if 0, don't prompt for a choice unless the timeout period is
 *          interrupted.  If 1, always prompt for a choice regardless of
 *          timeout.
 * labels - a list of labels defined for the menu.
 */
struct pxe_menu {
	char *title;
	char *default_label;
	char *bmp;
	int timeout;
	int prompt;
	struct list_head labels;
};

struct pxe_context;
typedef int (*pxe_getfile_func)(struct pxe_context *ctx, const char *file_path,
				char *file_addr, ulong *filesizep);

/**
 * struct pxe_context - context information for PXE parsing
 *
 * @cmdtp: Pointer to command table to use when calling other commands
 * @getfile: Function called by PXE to read a file
 * @userdata: Data the caller requires for @getfile
 * @allow_abs_path: true to allow absolute paths
 * @bootdir: Directory that files are loaded from ("" if no directory). This is
 *	allocated
 * @pxe_file_size: Size of the PXE file
 */
struct pxe_context {
	struct cmd_tbl *cmdtp;
	/**
	 * getfile() - read a file
	 *
	 * @ctx: PXE context
	 * @file_path: Path to the file
	 * @file_addr: String containing the hex address to put the file in
	 *	memory
	 * @filesizep: Returns the file size in bytes
	 * Return 0 if OK, -ve on error
	 */
	pxe_getfile_func getfile;

	void *userdata;
	bool allow_abs_path;
	char *bootdir;
	ulong pxe_file_size;
};

/**
 * destroy_pxe_menu() - Destroy an allocated pxe structure
 *
 * Free the memory used by a pxe_menu and its labels
 *
 * @cfg: Config to destroy, previous returned from parse_pxefile()
 */
void destroy_pxe_menu(struct pxe_menu *cfg);

/**
 * get_pxe_file() - Read a file
 *
 * Retrieve the file at 'file_path' to the locate given by 'file_addr'. If
 * 'bootfile' was specified in the environment, the path to bootfile will be
 * prepended to 'file_path' and the resulting path will be used.
 *
 * @ctx: PXE context
 * @file_path: Path to file
 * @file_addr: Address to place file
 * Returns 1 on success, or < 0 for error
 */
int get_pxe_file(struct pxe_context *ctx, const char *file_path,
		 ulong file_addr);

/**
 * get_pxelinux_path() - Read a file from the same place as pxelinux.cfg
 *
 * Retrieves a file in the 'pxelinux.cfg' folder. Since this uses get_pxe_file()
 * to do the hard work, the location of the 'pxelinux.cfg' folder is generated
 * from the bootfile path, as described in get_pxe_file().
 *
 * @ctx: PXE context
 * @file: Relative path to file
 * @pxefile_addr_r: Address to load file
 * Returns 1 on success or < 0 on error.
 */
int get_pxelinux_path(struct pxe_context *ctx, const char *file,
		      ulong pxefile_addr_r);

/**
 * handle_pxe_menu() - Boot the system as prescribed by a pxe_menu.
 *
 * Use the menu system to either get the user's choice or the default, based
 * on config or user input.  If there is no default or user's choice,
 * attempted to boot labels in the order they were given in pxe files.
 * If the default or user's choice fails to boot, attempt to boot other
 * labels in the order they were given in pxe files.
 *
 * If this function returns, there weren't any labels that successfully
 * booted, or the user interrupted the menu selection via ctrl+c.
 *
 * @ctx: PXE context
 * @cfg: PXE menu
 */
void handle_pxe_menu(struct pxe_context *ctx, struct pxe_menu *cfg);

/**
 * parse_pxefile() - Parsing a pxe file
 *
 * This is only used for the top-level file.
 *
 * @ctx: PXE context (provided by the caller)
 * Returns NULL if there is an error, otherwise, returns a pointer to a
 * pxe_menu struct populated with the results of parsing the pxe file (and any
 * files it includes). The resulting pxe_menu struct can be free()'d by using
 * the destroy_pxe_menu() function.
 */
struct pxe_menu *parse_pxefile(struct pxe_context *ctx, ulong menucfg);

/**
 * format_mac_pxe() - Convert a MAC address to PXE format
 *
 * Convert an ethaddr from the environment to the format used by pxelinux
 * filenames based on mac addresses. Convert's ':' to '-', and adds "01-" to
 * the beginning of the ethernet address to indicate a hardware type of
 * Ethernet. Also converts uppercase hex characters into lowercase, to match
 * pxelinux's behavior.
 *
 * @outbuf: Buffer to hold the output (must hold 22 bytes)
 * @outbuf_len: Length of buffer
 * Returns 1 for success, -ENOENT if 'ethaddr' is undefined in the
 * environment, or some other value < 0 on error.
 */
int format_mac_pxe(char *outbuf, size_t outbuf_len);

/**
 * pxe_setup_ctx() - Setup a new PXE context
 *
 * @ctx: Context to set up
 * @cmdtp: Command table entry which started this action
 * @getfile: Function to call to read a file
 * @userdata: Data the caller requires for @getfile - stored in ctx->userdata
 * @allow_abs_path: true to allow absolute paths
 * @bootfile: Bootfile whose directory loaded files are relative to, NULL if
 *	none
 * Return: 0 if OK, -ENOMEM if out of memory, -E2BIG if bootfile is larger than
 *	MAX_TFTP_PATH_LEN bytes
 */
int pxe_setup_ctx(struct pxe_context *ctx, struct cmd_tbl *cmdtp,
		  pxe_getfile_func getfile, void *userdata,
		  bool allow_abs_path, const char *bootfile);

/**
 * pxe_destroy_ctx() - Destroy a PXE context
 *
 * @ctx: Context to destroy
 */
void pxe_destroy_ctx(struct pxe_context *ctx);

/**
 * pxe_process() - Process a PXE file through to boot
 *
 * @ctx: PXE context created with pxe_setup_ctx()
 * @pxefile_addr_r: Address to load file
 * @prompt: Force a prompt for the user
 */
int pxe_process(struct pxe_context *ctx, ulong pxefile_addr_r, bool prompt);

/**
 * pxe_get_file_size() - Read the value of the 'filesize' environment variable
 *
 * @sizep: Place to put the value
 * Return: 0 if OK, -ENOENT if no such variable, -EINVAL if format is invalid
 */
int pxe_get_file_size(ulong *sizep);

/**
 * pxe_get() - Get the PXE file from the server
 *
 * This tries various filenames to obtain a PXE file
 *
 * @pxefile_addr_r: Address to put file
 * @bootdirp: Returns the boot filename, or NULL if none. This is the 'bootfile'
 *	option provided by the DHCP server. If none, returns NULL. For example,
 *	"rpi/info", which indicates that all files should be fetched from the
 *	"rpi/" subdirectory
 * @sizep: Size of the PXE file (not bootfile)
 */
int pxe_get(ulong pxefile_addr_r, char **bootdirp, ulong *sizep);

#endif /* __PXE_UTILS_H */