summaryrefslogtreecommitdiff
path: root/include/bootflow.h
blob: 4152577afb71836fcc9877567f7804c283406cdc (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
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
/* SPDX-License-Identifier: GPL-2.0+ */
/*
 * Copyright 2021 Google LLC
 * Written by Simon Glass <sjg@chromium.org>
 */

#ifndef __bootflow_h
#define __bootflow_h

#include <bootdev.h>
#include <dm/ofnode_decl.h>
#include <linux/list.h>

struct bootstd_priv;
struct expo;

enum {
	BOOTFLOW_MAX_USED_DEVS	= 16,
};

/**
 * enum bootflow_state_t - states that a particular bootflow can be in
 *
 * Only bootflows in state BOOTFLOWST_READY can be used to boot.
 *
 * See bootflow_state[] for the names for each of these
 */
enum bootflow_state_t {
	BOOTFLOWST_BASE,	/**< Nothing known yet */
	BOOTFLOWST_MEDIA,	/**< Media exists */
	BOOTFLOWST_PART,	/**< Partition exists */
	BOOTFLOWST_FS,		/**< Filesystem exists */
	BOOTFLOWST_FILE,	/**< Bootflow file exists */
	BOOTFLOWST_READY,	/**< Bootflow file loaded */

	BOOTFLOWST_COUNT
};

/**
 * enum bootflow_flags_t - flags for bootflows
 *
 * @BOOTFLOWF_USE_PRIOR_FDT: Indicates that an FDT was not found by the bootmeth
 *	and it is using the prior-stage FDT, which is the U-Boot control FDT.
 *	This is only possible with the EFI bootmeth (distro-efi) and only when
 *	CONFIG_OF_HAS_PRIOR_STAGE is enabled
 */
enum bootflow_flags_t {
	BOOTFLOWF_USE_PRIOR_FDT	= 1 << 0,
};

/**
 * struct bootflow - information about a bootflow
 *
 * This is connected into two separate linked lists:
 *
 *   bm_sibling - links all bootflows in the same bootdev
 *   glob_sibling - links all bootflows in all bootdevs
 *
 * @bm_node: Points to siblings in the same bootdev
 * @glob_node: Points to siblings in the global list (all bootdev)
 * @dev: Bootdev device which produced this bootflow
 * @blk: Block device which contains this bootflow, NULL if this is a network
 *	device or sandbox 'host' device
 * @part: Partition number (0 for whole device)
 * @fs_type: Filesystem type (FS_TYPE...) if this is fixed by the media, else 0.
 *	For example, the sandbox host-filesystem bootdev sets this to
 *	FS_TYPE_SANDBOX
 * @method: Bootmethod device used to perform the boot and read files
 * @name: Name of bootflow (allocated)
 * @state: Current state (enum bootflow_state_t)
 * @subdir: Subdirectory to fetch files from (with trailing /), or NULL if none
 * @fname: Filename of bootflow file (allocated)
 * @logo: Logo to display for this bootflow (BMP format)
 * @logo_size: Size of the logo in bytes
 * @buf: Bootflow file contents (allocated)
 * @size: Size of bootflow file in bytes
 * @err: Error number received (0 if OK)
 * @os_name: Name of the OS / distro being booted, or NULL if not known
 *	(allocated)
 * @fdt_fname: Filename of FDT file
 * @fdt_size: Size of FDT file
 * @fdt_addr: Address of loaded fdt
 * @flags: Flags for the bootflow (see enum bootflow_flags_t)
 * @cmdline: OS command line, or NULL if not known (allocated)
 * @x86_setup: Pointer to x86 setup block inside @buf, NULL if not present
 */
struct bootflow {
	struct list_head bm_node;
	struct list_head glob_node;
	struct udevice *dev;
	struct udevice *blk;
	int part;
	int fs_type;
	struct udevice *method;
	char *name;
	enum bootflow_state_t state;
	char *subdir;
	char *fname;
	void *logo;
	uint logo_size;
	char *buf;
	int size;
	int err;
	char *os_name;
	char *fdt_fname;
	int fdt_size;
	ulong fdt_addr;
	int flags;
	char *cmdline;
	char *x86_setup;
};

/**
 * enum bootflow_iter_flags_t - flags for the bootflow iterator
 *
 * @BOOTFLOWIF_FIXED: Only used fixed/internal media
 * @BOOTFLOWIF_SHOW: Show each bootdev before scanning it; show each hunter
 * before using it
 * @BOOTFLOWIF_ALL: Return bootflows with errors as well
 * @BOOTFLOWIF_HUNT: Hunt for new bootdevs using the bootdrv hunters
 *
 * Internal flags:
 * @BOOTFLOWIF_SINGLE_DEV: (internal) Just scan one bootdev
 * @BOOTFLOWIF_SKIP_GLOBAL: (internal) Don't scan global bootmeths
 * @BOOTFLOWIF_SINGLE_UCLASS: (internal) Keep scanning through all devices in
 * this uclass (used with things like "mmc")
 * @BOOTFLOWIF_SINGLE_MEDIA: (internal) Scan one media device in the uclass (used
 * with things like "mmc1")
 */
enum bootflow_iter_flags_t {
	BOOTFLOWIF_FIXED		= 1 << 0,
	BOOTFLOWIF_SHOW			= 1 << 1,
	BOOTFLOWIF_ALL			= 1 << 2,
	BOOTFLOWIF_HUNT			= 1 << 3,

	/*
	 * flags used internally by standard boot - do not set these when
	 * calling bootflow_scan_bootdev() etc.
	 */
	BOOTFLOWIF_SINGLE_DEV		= 1 << 16,
	BOOTFLOWIF_SKIP_GLOBAL		= 1 << 17,
	BOOTFLOWIF_SINGLE_UCLASS	= 1 << 18,
	BOOTFLOWIF_SINGLE_MEDIA		= 1 << 19,
};

/**
 * enum bootflow_meth_flags_t - flags controlling which bootmeths are used
 *
 * Used during iteration, e.g. by bootdev_find_by_label(), to determine which
 * bootmeths are used for the current bootdev. The flags reset when the bootdev
 * changes
 *
 * @BOOTFLOW_METHF_DHCP_ONLY: Only use dhcp (scripts and EFI)
 * @BOOTFLOW_METHF_PXE_ONLY: Only use pxe (PXE boot)
 * @BOOTFLOW_METHF_SINGLE_DEV: Scan only a single bootdev (used for labels like
 * "3"). This is used if a sequence number is provided instead of a label
 * @BOOTFLOW_METHF_SINGLE_UCLASS: Scan all bootdevs in this one uclass (used
 * with things like "mmc"). If this is not set, then the bootdev has an integer
 * value in the label (like "mmc2")
 */
enum bootflow_meth_flags_t {
	BOOTFLOW_METHF_DHCP_ONLY	= 1 << 0,
	BOOTFLOW_METHF_PXE_ONLY		= 1 << 1,
	BOOTFLOW_METHF_SINGLE_DEV	= 1 << 2,
	BOOTFLOW_METHF_SINGLE_UCLASS	= 1 << 3,
};

/**
 * struct bootflow_iter - state for iterating through bootflows
 *
 * This starts at with the first bootdev/partition/bootmeth and can be used to
 * iterate through all of them.
 *
 * Iteration starts with the bootdev. The first partition (0, i.e. whole device)
 * is scanned first. For partition 0, it iterates through all the available
 * bootmeths to see which one(s) can provide a bootflow. Then it moves to
 * parition 1 (if there is one) and the process continues. Once all partitions
 * are examined, it moves to the next bootdev.
 *
 * Initially @max_part is 0, meaning that only the whole device (@part=0) can be
 * used. During scanning, if a partition table is found, then @max_part is
 * updated to a larger value, no less than the number of available partitions.
 * This ensures that iteration works through all partitions on the bootdev.
 *
 * @flags: Flags to use (see enum bootflow_iter_flags_t). If
 *	BOOTFLOWIF_GLOBAL_FIRST is enabled then the global bootmeths are being
 *	scanned, otherwise we have moved onto the bootdevs
 * @dev: Current bootdev, NULL if none. This is only ever updated in
 * bootflow_iter_set_dev()
 * @part: Current partition number (0 for whole device)
 * @method: Current bootmeth
 * @max_part: Maximum hardware partition number in @dev, 0 if there is no
 *	partition table
 * @first_bootable: First bootable partition, or 0 if none
 * @err: Error obtained from checking the last iteration. This is used to skip
 *	forward (e.g. to skip the current partition because it is not valid)
 *	-ESHUTDOWN: try next bootdev
 * @num_devs: Number of bootdevs in @dev_used
 * @max_devs: Maximum number of entries in @dev_used
 * @dev_used: List of bootdevs used during iteration
 * @labels: List of labels to scan for bootdevs
 * @cur_label: Current label being processed
 * @num_methods: Number of bootmeth devices in @method_order
 * @cur_method: Current method number, an index into @method_order
 * @first_glob_method: First global method, if any, else -1
 * @cur_prio: Current priority being scanned
 * @method_order: List of bootmeth devices to use, in order. The normal methods
 *	appear first, then the global ones, if any
 * @doing_global: true if we are iterating through the global bootmeths (which
 *	happens before the normal ones)
 * @method_flags: flags controlling which methods should be used for this @dev
 * (enum bootflow_meth_flags_t)
 */
struct bootflow_iter {
	int flags;
	struct udevice *dev;
	int part;
	struct udevice *method;
	int max_part;
	int first_bootable;
	int err;
	int num_devs;
	int max_devs;
	struct udevice *dev_used[BOOTFLOW_MAX_USED_DEVS];
	const char *const *labels;
	int cur_label;
	int num_methods;
	int cur_method;
	int first_glob_method;
	enum bootdev_prio_t cur_prio;
	struct udevice **method_order;
	bool doing_global;
	int method_flags;
};

/**
 * bootflow_init() - Set up a bootflow struct
 *
 * The bootflow is zeroed and set to state BOOTFLOWST_BASE
 *
 * @bflow: Struct to set up
 * @bootdev: Bootdev to use
 * @meth: Bootmeth to use
 */
void bootflow_init(struct bootflow *bflow, struct udevice *bootdev,
		   struct udevice *meth);

/**
 * bootflow_iter_init() - Reset a bootflow iterator
 *
 * This sets everything to the starting point, ready for use.
 *
 * @iter: Place to store private info (inited by this call)
 * @flags: Flags to use (see enum bootflow_iter_flags_t)
 */
void bootflow_iter_init(struct bootflow_iter *iter, int flags);

/**
 * bootflow_iter_uninit() - Free memory used by an interator
 *
 * @iter:	Iterator to free
 */
void bootflow_iter_uninit(struct bootflow_iter *iter);

/**
 * bootflow_iter_drop_bootmeth() - Remove a bootmeth from an iterator
 *
 * Update the iterator so that the bootmeth will not be used again while this
 * iterator is in use
 *
 * @iter: Iterator to update
 * @bmeth: Boot method to remove
 */
int bootflow_iter_drop_bootmeth(struct bootflow_iter *iter,
				const struct udevice *bmeth);

/**
 * bootflow_scan_first() - find the first bootflow for a device or label
 *
 * If @flags includes BOOTFLOWIF_ALL then bootflows with errors are returned too
 *
 * @dev:	Boot device to scan, NULL to work through all of them until it
 *	finds one that can supply a bootflow
 * @label:	Label to control the scan, NULL to work through all devices
 *	until it finds one that can supply a bootflow
 * @iter:	Place to store private info (inited by this call)
 * @flags:	Flags for iterator (enum bootflow_iter_flags_t). Note that if
 *	@dev is NULL, then BOOTFLOWIF_SKIP_GLOBAL is set automatically by this
 *	function
 * @bflow:	Place to put the bootflow if found
 * Return: 0 if found,  -ENODEV if no device, other -ve on other error
 *	(iteration can continue)
 */
int bootflow_scan_first(struct udevice *dev, const char *label,
			struct bootflow_iter *iter, int flags,
			struct bootflow *bflow);

/**
 * bootflow_scan_next() - find the next bootflow
 *
 * This works through the available bootdev devices until it finds one that
 * can supply a bootflow. It then returns that bootflow
 *
 * @iter:	Private info (as set up by bootflow_scan_first())
 * @bflow:	Place to put the bootflow if found
 * Return: 0 if found, -ENODEV if no device, -ESHUTDOWN if no more bootflows,
 *	other -ve on other error (iteration can continue)
 */
int bootflow_scan_next(struct bootflow_iter *iter, struct bootflow *bflow);

/**
 * bootflow_first_glob() - Get the first bootflow from the global list
 *
 * Returns the first bootflow in the global list, no matter what bootflow it is
 * attached to
 *
 * @bflowp: Returns a pointer to the bootflow
 * Return: 0 if found, -ENOENT if there are no bootflows
 */
int bootflow_first_glob(struct bootflow **bflowp);

/**
 * bootflow_next_glob() - Get the next bootflow from the global list
 *
 * Returns the next bootflow in the global list, no matter what bootflow it is
 * attached to
 *
 * @bflowp: On entry, the last bootflow returned , e.g. from
 *	bootflow_first_glob()
 * Return: 0 if found, -ENOENT if there are no more bootflows
 */
int bootflow_next_glob(struct bootflow **bflowp);

/**
 * bootflow_free() - Free memory used by a bootflow
 *
 * This frees fields within @bflow, but not the @bflow pointer itself
 */
void bootflow_free(struct bootflow *bflow);

/**
 * bootflow_boot() - boot a bootflow
 *
 * @bflow: Bootflow to boot
 * Return: -EPROTO if bootflow has not been loaded, -ENOSYS if the bootflow
 *	type is not supported, -EFAULT if the boot returned without an error
 *	when we are expecting it to boot, -ENOTSUPP if trying method resulted in
 *	finding out that is not actually supported for this boot and should not
 *	be tried again unless something changes
 */
int bootflow_boot(struct bootflow *bflow);

/**
 * bootflow_run_boot() - Try to boot a bootflow
 *
 * @iter: Current iteration (or NULL if none). Used to disable a bootmeth if the
 *	boot returns -ENOTSUPP
 * @bflow: Bootflow to boot
 * Return: result of trying to boot
 */
int bootflow_run_boot(struct bootflow_iter *iter, struct bootflow *bflow);

/**
 * bootflow_state_get_name() - Get the name of a bootflow state
 *
 * @state: State to check
 * Return: name, or "?" if invalid
 */
const char *bootflow_state_get_name(enum bootflow_state_t state);

/**
 * bootflow_remove() - Remove a bootflow and free its memory
 *
 * This updates the linked lists containing the bootflow then frees it.
 *
 * @bflow: Bootflow to remove
 */
void bootflow_remove(struct bootflow *bflow);

/**
 * bootflow_iter_check_blk() - Check that a bootflow uses a block device
 *
 * This checks the bootdev in the bootflow to make sure it uses a block device
 *
 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. ethernet)
 */
int bootflow_iter_check_blk(const struct bootflow_iter *iter);

/**
 * bootflow_iter_check_sf() - Check that a bootflow uses SPI FLASH
 *
 * This checks the bootdev in the bootflow to make sure it uses SPI flash
 *
 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. ethernet)
 */
int bootflow_iter_check_sf(const struct bootflow_iter *iter);

/**
 * bootflow_iter_check_net() - Check that a bootflow uses a network device
 *
 * This checks the bootdev in the bootflow to make sure it uses a network
 * device
 *
 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC)
 */
int bootflow_iter_check_net(const struct bootflow_iter *iter);

/**
 * bootflow_iter_check_system() - Check that a bootflow uses the bootstd device
 *
 * This checks the bootdev in the bootflow to make sure it uses the bootstd
 * device
 *
 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC)
 */
int bootflow_iter_check_system(const struct bootflow_iter *iter);

/**
 * bootflow_menu_new() - Create a new bootflow menu
 *
 * @expp: Returns the expo created
 * Returns 0 on success, -ve on error
 */
int bootflow_menu_new(struct expo **expp);

/**
 * bootflow_menu_apply_theme() - Apply a theme to a bootmenu
 *
 * @exp: Expo to update
 * @node: Node containing the theme information
 * Returns 0 on success, -ve on error
 */
int bootflow_menu_apply_theme(struct expo *exp, ofnode node);

/**
 * bootflow_menu_run() - Create and run a menu of available bootflows
 *
 * @std: Bootstd information
 * @text_mode: Uses a text-based menu suitable for a serial port
 * @bflowp: Returns chosen bootflow (set to NULL if nothing is chosen)
 * @return 0 if an option was chosen, -EAGAIN if nothing was chosen, -ve on
 * error
 */
int bootflow_menu_run(struct bootstd_priv *std, bool text_mode,
		      struct bootflow **bflowp);

#define BOOTFLOWCL_EMPTY	((void *)1)

/**
 * cmdline_set_arg() - Update or read an argument in a cmdline string
 *
 * Handles updating a single arg in a cmdline string, returning it in a supplied
 * buffer; also reading an arg from a cmdline string
 *
 * When updating, consecutive spaces are squashed as are spaces at the start and
 * end.
 *
 * @buf: Working buffer to use (initial contents are ignored). Use NULL when
 * reading
 * @maxlen: Length of working buffer. Use 0 when reading
 * @cmdline: Command line to update, in the form:
 *
 *	fred mary= jane=123 john="has spaces"
 *
 * @set_arg: Argument to set or read (may or may not exist)
 * @new_val: Value for the new argument. May not include quotes (") but may
 * include embedded spaces, in which case it will be quoted when added to the
 * command line. Use NULL to delete the argument from @cmdline, BOOTFLOWCL_EMPTY
 * to set it to an empty value (no '=' sign after arg), "" to add an '=' sign
 * but with an empty value. Use NULL when reading.
 * @posp: Ignored when setting an argument; when getting an argument, returns
 * the start position of its value in @cmdline, after the first quote, if any
 *
 * Return:
 * For updating:
 *	length of new buffer (including \0 terminator) on success, -ENOENT if
 *	@new_val is NULL and @set_arg does not exist in @from, -EINVAL if a
 *	quoted arg-value in @from is not terminated with a quote, -EBADF if
 *	@new_val has spaces but does not start and end with quotes (or it has
 *	quotes in the middle of the string), -E2BIG if @maxlen is too small
 * For reading:
 *	length of arg value (excluding quotes), -ENOENT if not found
 */
int cmdline_set_arg(char *buf, int maxlen, const char *cmdline,
		    const char *set_arg, const char *new_val, int *posp);

/**
 * bootflow_cmdline_set_arg() - Set a single argument for a bootflow
 *
 * Update the allocated cmdline and set the bootargs variable
 *
 * @bflow: Bootflow to update
 * @arg: Argument to update (e.g. "console")
 * @val: Value to set (e.g. "ttyS2") or NULL to delete the argument if present,
 * "" to set it to an empty value (e.g. "console=") and BOOTFLOWCL_EMPTY to add
 * it without any value ("initrd")
 * @set_env: true to set the "bootargs" environment variable too
 *
 * Return: 0 if OK, -ENOMEM if out of memory
 */
int bootflow_cmdline_set_arg(struct bootflow *bflow, const char *arg,
			     const char *val, bool set_env);

/**
 * cmdline_get_arg() - Read an argument from a cmdline
 *
 * @cmdline: Command line to read, in the form:
 *
 *	fred mary= jane=123 john="has spaces"
 * @arg: Argument to read (may or may not exist)
 * @posp: Returns position of argument (after any leading quote) if present
 * Return: Length of argument value excluding quotes if found, -ENOENT if not
 * found
 */
int cmdline_get_arg(const char *cmdline, const char *arg, int *posp);

/**
 * bootflow_cmdline_get_arg() - Read an argument from a cmdline
 *
 * @bootflow: Bootflow to read from
 * @arg: Argument to read (may or may not exist)
 * @valp: Returns a pointer to the argument (after any leading quote) if present
 * Return: Length of argument value excluding quotes if found, -ENOENT if not
 * found
 */
int bootflow_cmdline_get_arg(struct bootflow *bflow, const char *arg,
			     const char **val);

/**
 * bootflow_cmdline_auto() - Automatically set a value for a known argument
 *
 * This handles a small number of known arguments, for Linux in particular. It
 * adds suitable kernel parameters automatically, e.g. to enable the console.
 *
 * @bflow: Bootflow to update
 * @arg: Name of argument to set (e.g. "earlycon" or "console")
 * Return: 0 if OK -ve on error
 */
int bootflow_cmdline_auto(struct bootflow *bflow, const char *arg);

#endif