blob: f516bf8dea4baa604400d06bc62a79f083003b55 [file] [log] [blame]
Simon Glass9d260252022-04-24 23:31:05 -06001/* SPDX-License-Identifier: GPL-2.0+ */
2/*
3 * Copyright 2021 Google LLC
4 * Written by Simon Glass <sjg@chromium.org>
5 */
6
7#ifndef __bootflow_h
8#define __bootflow_h
9
Simon Glass43e89a32023-01-17 10:48:11 -070010#include <bootdev.h>
Simon Glasse64c2952023-01-06 08:52:42 -060011#include <dm/ofnode_decl.h>
Simon Glass9d260252022-04-24 23:31:05 -060012#include <linux/list.h>
13
Simon Glass02d929b2023-01-06 08:52:40 -060014struct bootstd_priv;
15struct expo;
16
Simon Glassa950f282023-01-17 10:48:17 -070017enum {
18 BOOTFLOW_MAX_USED_DEVS = 16,
19};
20
Simon Glass9d260252022-04-24 23:31:05 -060021/**
22 * enum bootflow_state_t - states that a particular bootflow can be in
23 *
24 * Only bootflows in state BOOTFLOWST_READY can be used to boot.
25 *
26 * See bootflow_state[] for the names for each of these
27 */
28enum bootflow_state_t {
29 BOOTFLOWST_BASE, /**< Nothing known yet */
30 BOOTFLOWST_MEDIA, /**< Media exists */
31 BOOTFLOWST_PART, /**< Partition exists */
32 BOOTFLOWST_FS, /**< Filesystem exists */
33 BOOTFLOWST_FILE, /**< Bootflow file exists */
34 BOOTFLOWST_READY, /**< Bootflow file loaded */
35
36 BOOTFLOWST_COUNT
37};
38
39/**
40 * struct bootflow - information about a bootflow
41 *
42 * This is connected into two separate linked lists:
43 *
44 * bm_sibling - links all bootflows in the same bootdev
45 * glob_sibling - links all bootflows in all bootdevs
46 *
47 * @bm_node: Points to siblings in the same bootdev
48 * @glob_node: Points to siblings in the global list (all bootdev)
49 * @dev: Bootdevice device which produced this bootflow
50 * @blk: Block device which contains this bootflow, NULL if this is a network
Simon Glassa58e7bb2023-01-17 10:47:59 -070051 * device or sandbox 'host' device
Simon Glass9d260252022-04-24 23:31:05 -060052 * @part: Partition number (0 for whole device)
53 * @fs_type: Filesystem type (FS_TYPE...) if this is fixed by the media, else 0.
54 * For example, the sandbox host-filesystem bootdev sets this to
55 * FS_TYPE_SANDBOX
56 * @method: Bootmethod device used to perform the boot and read files
57 * @name: Name of bootflow (allocated)
58 * @state: Current state (enum bootflow_state_t)
59 * @subdir: Subdirectory to fetch files from (with trailing /), or NULL if none
60 * @fname: Filename of bootflow file (allocated)
Simon Glass24d8e1b2023-01-06 08:52:34 -060061 * @logo: Logo to display for this bootflow (BMP format)
62 * @logo_size: Size of the logo in bytes
Simon Glass9d260252022-04-24 23:31:05 -060063 * @buf: Bootflow file contents (allocated)
64 * @size: Size of bootflow file in bytes
65 * @err: Error number received (0 if OK)
Simon Glass2175e762023-01-06 08:52:33 -060066 * @os_name: Name of the OS / distro being booted, or NULL if not known
67 * (allocated)
Simon Glass7638c852023-01-17 10:47:56 -070068 * @fdt_fname: Filename of FDT file
69 * @fdt_size: Size of FDT file
70 * @fdt_addr: Address of loaded fdt
Simon Glass9d260252022-04-24 23:31:05 -060071 */
72struct bootflow {
73 struct list_head bm_node;
74 struct list_head glob_node;
75 struct udevice *dev;
76 struct udevice *blk;
77 int part;
78 int fs_type;
79 struct udevice *method;
80 char *name;
81 enum bootflow_state_t state;
82 char *subdir;
83 char *fname;
Simon Glass24d8e1b2023-01-06 08:52:34 -060084 void *logo;
85 uint logo_size;
Simon Glass9d260252022-04-24 23:31:05 -060086 char *buf;
87 int size;
88 int err;
Simon Glass2175e762023-01-06 08:52:33 -060089 char *os_name;
Simon Glass7638c852023-01-17 10:47:56 -070090 char *fdt_fname;
91 int fdt_size;
92 ulong fdt_addr;
Simon Glass9d260252022-04-24 23:31:05 -060093};
94
95/**
96 * enum bootflow_flags_t - flags for the bootflow iterator
97 *
98 * @BOOTFLOWF_FIXED: Only used fixed/internal media
Simon Glassd73420e2023-01-17 10:48:06 -070099 * @BOOTFLOWF_SHOW: Show each bootdev before scanning it; show each hunter
100 * before using it
Simon Glass9d260252022-04-24 23:31:05 -0600101 * @BOOTFLOWF_ALL: Return bootflows with errors as well
Simon Glassd73420e2023-01-17 10:48:06 -0700102 * @BOOTFLOWF_HUNT: Hunt for new bootdevs using the bootdrv hunters
103 *
104 * Internal flags:
105 * @BOOTFLOWF_SINGLE_DEV: (internal) Just scan one bootdev
106 * @BOOTFLOWF_SKIP_GLOBAL: (internal) Don't scan global bootmeths
Simon Glass66e3dce2023-01-17 10:48:09 -0700107 * @BOOTFLOWF_SINGLE_UCLASS: (internal) Keep scanning through all devices in
108 * this uclass (used with things like "mmc")
109 * @BOOTFLOWF_SINGLE_MEDIA: (internal) Scan one media device in the uclass (used
110 * with things like "mmc1")
Simon Glass9d260252022-04-24 23:31:05 -0600111 */
112enum bootflow_flags_t {
113 BOOTFLOWF_FIXED = 1 << 0,
114 BOOTFLOWF_SHOW = 1 << 1,
115 BOOTFLOWF_ALL = 1 << 2,
Simon Glassd73420e2023-01-17 10:48:06 -0700116 BOOTFLOWF_HUNT = 1 << 3,
117
118 /*
119 * flags used internally by standard boot - do not set these when
120 * calling bootflow_scan_bootdev() etc.
121 */
122 BOOTFLOWF_SINGLE_DEV = 1 << 16,
123 BOOTFLOWF_SKIP_GLOBAL = 1 << 17,
Simon Glass66e3dce2023-01-17 10:48:09 -0700124 BOOTFLOWF_SINGLE_UCLASS = 1 << 18,
125 BOOTFLOWF_SINGLE_MEDIA = 1 << 19,
Simon Glass9d260252022-04-24 23:31:05 -0600126};
127
128/**
Simon Glassd9f48572023-01-17 10:48:05 -0700129 * enum bootflow_meth_flags_t - flags controlling which bootmeths are used
130 *
131 * Used during iteration, e.g. by bootdev_find_by_label(), to determine which
132 * bootmeths are used for the current bootdev. The flags reset when the bootdev
133 * changes
134 *
135 * @BOOTFLOW_METHF_DHCP_ONLY: Only use dhcp (scripts and EFI)
136 * @BOOTFLOW_METHF_PXE_ONLY: Only use pxe (PXE boot)
Simon Glass66e3dce2023-01-17 10:48:09 -0700137 * @BOOTFLOW_METHF_SINGLE_DEV: Scan only a single bootdev (used for labels like
138 * "3"). This is used if a sequence number is provided instead of a label
139 * @BOOTFLOW_METHF_SINGLE_UCLASS: Scan all bootdevs in this one uclass (used
140 * with things like "mmc"). If this is not set, then the bootdev has an integer
141 * value in the label (like "mmc2")
Simon Glassd9f48572023-01-17 10:48:05 -0700142 */
143enum bootflow_meth_flags_t {
144 BOOTFLOW_METHF_DHCP_ONLY = 1 << 0,
145 BOOTFLOW_METHF_PXE_ONLY = 1 << 1,
Simon Glass66e3dce2023-01-17 10:48:09 -0700146 BOOTFLOW_METHF_SINGLE_DEV = 1 << 2,
147 BOOTFLOW_METHF_SINGLE_UCLASS = 1 << 3,
Simon Glassd9f48572023-01-17 10:48:05 -0700148};
149
150/**
Simon Glass9d260252022-04-24 23:31:05 -0600151 * struct bootflow_iter - state for iterating through bootflows
152 *
153 * This starts at with the first bootdev/partition/bootmeth and can be used to
154 * iterate through all of them.
155 *
156 * Iteration starts with the bootdev. The first partition (0, i.e. whole device)
157 * is scanned first. For partition 0, it iterates through all the available
158 * bootmeths to see which one(s) can provide a bootflow. Then it moves to
159 * parition 1 (if there is one) and the process continues. Once all partitions
160 * are examined, it moves to the next bootdev.
161 *
162 * Initially @max_part is 0, meaning that only the whole device (@part=0) can be
163 * used. During scanning, if a partition table is found, then @max_part is
164 * updated to a larger value, no less than the number of available partitions.
165 * This ensures that iteration works through all partitions on the bootdev.
166 *
Simon Glass2b80bc12022-07-30 15:52:25 -0600167 * @flags: Flags to use (see enum bootflow_flags_t). If BOOTFLOWF_GLOBAL_FIRST is
168 * enabled then the global bootmeths are being scanned, otherwise we have
169 * moved onto the bootdevs
Simon Glass47aedc22023-01-17 10:48:14 -0700170 * @dev: Current bootdev, NULL if none. This is only ever updated in
171 * bootflow_iter_set_dev()
Simon Glass9d260252022-04-24 23:31:05 -0600172 * @part: Current partition number (0 for whole device)
173 * @method: Current bootmeth
174 * @max_part: Maximum hardware partition number in @dev, 0 if there is no
175 * partition table
Simon Glassf0e358f2023-01-17 10:47:42 -0700176 * @first_bootable: First bootable partition, or 0 if none
Simon Glass9d260252022-04-24 23:31:05 -0600177 * @err: Error obtained from checking the last iteration. This is used to skip
178 * forward (e.g. to skip the current partition because it is not valid)
179 * -ESHUTDOWN: try next bootdev
Simon Glassa950f282023-01-17 10:48:17 -0700180 * @num_devs: Number of bootdevs in @dev_used
181 * @max_devs: Maximum number of entries in @dev_used
182 * @dev_used: List of bootdevs used during iteration
Simon Glasse4b69482023-01-17 10:48:10 -0700183 * @labels: List of labels to scan for bootdevs
184 * @cur_label: Current label being processed
Simon Glass9d260252022-04-24 23:31:05 -0600185 * @num_methods: Number of bootmeth devices in @method_order
186 * @cur_method: Current method number, an index into @method_order
Simon Glass2b80bc12022-07-30 15:52:25 -0600187 * @first_glob_method: First global method, if any, else -1
Simon Glass43e89a32023-01-17 10:48:11 -0700188 * @cur_prio: Current priority being scanned
Simon Glass2b80bc12022-07-30 15:52:25 -0600189 * @method_order: List of bootmeth devices to use, in order. The normal methods
190 * appear first, then the global ones, if any
191 * @doing_global: true if we are iterating through the global bootmeths (which
192 * happens before the normal ones)
Simon Glass25365872023-01-17 10:47:58 -0700193 * @method_flags: flags controlling which methods should be used for this @dev
194 * (enum bootflow_meth_flags_t)
Simon Glass9d260252022-04-24 23:31:05 -0600195 */
196struct bootflow_iter {
197 int flags;
198 struct udevice *dev;
199 int part;
200 struct udevice *method;
201 int max_part;
Simon Glassf0e358f2023-01-17 10:47:42 -0700202 int first_bootable;
Simon Glass9d260252022-04-24 23:31:05 -0600203 int err;
204 int num_devs;
Simon Glassa950f282023-01-17 10:48:17 -0700205 int max_devs;
206 struct udevice *dev_used[BOOTFLOW_MAX_USED_DEVS];
Simon Glasse4b69482023-01-17 10:48:10 -0700207 const char *const *labels;
208 int cur_label;
Simon Glass9d260252022-04-24 23:31:05 -0600209 int num_methods;
210 int cur_method;
Simon Glass2b80bc12022-07-30 15:52:25 -0600211 int first_glob_method;
Simon Glass43e89a32023-01-17 10:48:11 -0700212 enum bootdev_prio_t cur_prio;
Simon Glass9d260252022-04-24 23:31:05 -0600213 struct udevice **method_order;
Simon Glass2b80bc12022-07-30 15:52:25 -0600214 bool doing_global;
Simon Glass25365872023-01-17 10:47:58 -0700215 int method_flags;
Simon Glass9d260252022-04-24 23:31:05 -0600216};
217
218/**
Simon Glassb190deb2022-10-20 18:22:51 -0600219 * bootflow_init() - Set up a bootflow struct
220 *
221 * The bootflow is zeroed and set to state BOOTFLOWST_BASE
222 *
223 * @bflow: Struct to set up
224 * @bootdev: Bootdev to use
225 * @meth: Bootmeth to use
226 */
227void bootflow_init(struct bootflow *bflow, struct udevice *bootdev,
228 struct udevice *meth);
229
230/**
Simon Glass9d260252022-04-24 23:31:05 -0600231 * bootflow_iter_init() - Reset a bootflow iterator
232 *
233 * This sets everything to the starting point, ready for use.
234 *
235 * @iter: Place to store private info (inited by this call)
236 * @flags: Flags to use (see enum bootflow_flags_t)
237 */
238void bootflow_iter_init(struct bootflow_iter *iter, int flags);
239
240/**
241 * bootflow_iter_uninit() - Free memory used by an interator
242 *
243 * @iter: Iterator to free
244 */
245void bootflow_iter_uninit(struct bootflow_iter *iter);
246
247/**
Simon Glassa8f5be12022-04-24 23:31:09 -0600248 * bootflow_iter_drop_bootmeth() - Remove a bootmeth from an iterator
249 *
250 * Update the iterator so that the bootmeth will not be used again while this
251 * iterator is in use
252 *
253 * @iter: Iterator to update
254 * @bmeth: Boot method to remove
255 */
256int bootflow_iter_drop_bootmeth(struct bootflow_iter *iter,
257 const struct udevice *bmeth);
258
259/**
Simon Glass4b7cb052023-01-17 10:48:16 -0700260 * bootflow_scan_first() - find the first bootflow for a device or label
Simon Glass9d260252022-04-24 23:31:05 -0600261 *
262 * If @flags includes BOOTFLOWF_ALL then bootflows with errors are returned too
263 *
264 * @dev: Boot device to scan, NULL to work through all of them until it
Simon Glassee47d4a2022-07-30 15:52:24 -0600265 * finds one that can supply a bootflow
Simon Glass91943ff2023-01-17 10:48:15 -0700266 * @label: Label to control the scan, NULL to work through all devices
267 * until it finds one that can supply a bootflow
Simon Glass9d260252022-04-24 23:31:05 -0600268 * @iter: Place to store private info (inited by this call)
Simon Glass91943ff2023-01-17 10:48:15 -0700269 * @flags: Flags for iterator (enum bootflow_flags_t). Note that if @dev
270 * is NULL, then BOOTFLOWF_SKIP_GLOBAL is set automatically by this function
Simon Glass9d260252022-04-24 23:31:05 -0600271 * @bflow: Place to put the bootflow if found
272 * Return: 0 if found, -ENODEV if no device, other -ve on other error
273 * (iteration can continue)
274 */
Simon Glass4b7cb052023-01-17 10:48:16 -0700275int bootflow_scan_first(struct udevice *dev, const char *label,
276 struct bootflow_iter *iter, int flags,
Simon Glass9d260252022-04-24 23:31:05 -0600277 struct bootflow *bflow);
278
279/**
280 * bootflow_scan_next() - find the next bootflow
281 *
282 * This works through the available bootdev devices until it finds one that
283 * can supply a bootflow. It then returns that bootflow
284 *
285 * @iter: Private info (as set up by bootflow_scan_first())
286 * @bflow: Place to put the bootflow if found
287 * Return: 0 if found, -ENODEV if no device, -ESHUTDOWN if no more bootflows,
288 * other -ve on other error (iteration can continue)
289 */
290int bootflow_scan_next(struct bootflow_iter *iter, struct bootflow *bflow);
291
292/**
293 * bootflow_first_glob() - Get the first bootflow from the global list
294 *
295 * Returns the first bootflow in the global list, no matter what bootflow it is
296 * attached to
297 *
298 * @bflowp: Returns a pointer to the bootflow
299 * Return: 0 if found, -ENOENT if there are no bootflows
300 */
301int bootflow_first_glob(struct bootflow **bflowp);
302
303/**
304 * bootflow_next_glob() - Get the next bootflow from the global list
305 *
306 * Returns the next bootflow in the global list, no matter what bootflow it is
307 * attached to
308 *
309 * @bflowp: On entry, the last bootflow returned , e.g. from
310 * bootflow_first_glob()
311 * Return: 0 if found, -ENOENT if there are no more bootflows
312 */
313int bootflow_next_glob(struct bootflow **bflowp);
314
315/**
316 * bootflow_free() - Free memory used by a bootflow
317 *
318 * This frees fields within @bflow, but not the @bflow pointer itself
319 */
320void bootflow_free(struct bootflow *bflow);
321
322/**
323 * bootflow_boot() - boot a bootflow
324 *
325 * @bflow: Bootflow to boot
326 * Return: -EPROTO if bootflow has not been loaded, -ENOSYS if the bootflow
327 * type is not supported, -EFAULT if the boot returned without an error
328 * when we are expecting it to boot, -ENOTSUPP if trying method resulted in
329 * finding out that is not actually supported for this boot and should not
330 * be tried again unless something changes
331 */
332int bootflow_boot(struct bootflow *bflow);
333
334/**
335 * bootflow_run_boot() - Try to boot a bootflow
336 *
337 * @iter: Current iteration (or NULL if none). Used to disable a bootmeth if the
338 * boot returns -ENOTSUPP
339 * @bflow: Bootflow to boot
340 * Return: result of trying to boot
341 */
342int bootflow_run_boot(struct bootflow_iter *iter, struct bootflow *bflow);
343
344/**
345 * bootflow_state_get_name() - Get the name of a bootflow state
346 *
347 * @state: State to check
348 * Return: name, or "?" if invalid
349 */
350const char *bootflow_state_get_name(enum bootflow_state_t state);
351
Simon Glassa8f5be12022-04-24 23:31:09 -0600352/**
353 * bootflow_remove() - Remove a bootflow and free its memory
354 *
355 * This updates the linked lists containing the bootflow then frees it.
356 *
357 * @bflow: Bootflow to remove
358 */
359void bootflow_remove(struct bootflow *bflow);
360
361/**
Simon Glass865328c2023-01-17 10:47:54 -0700362 * bootflow_iter_check_blk() - Check that a bootflow uses a block device
Simon Glassa8f5be12022-04-24 23:31:09 -0600363 *
364 * This checks the bootdev in the bootflow to make sure it uses a block device
365 *
366 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. ethernet)
367 */
Simon Glass865328c2023-01-17 10:47:54 -0700368int bootflow_iter_check_blk(const struct bootflow_iter *iter);
Simon Glassa8f5be12022-04-24 23:31:09 -0600369
370/**
Simon Glass0c1f4a92023-01-17 10:48:03 -0700371 * bootflow_iter_check_sf() - Check that a bootflow uses SPI FLASH
372 *
373 * This checks the bootdev in the bootflow to make sure it uses SPI flash
374 *
375 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. ethernet)
376 */
377int bootflow_iter_check_sf(const struct bootflow_iter *iter);
378
379/**
Simon Glass865328c2023-01-17 10:47:54 -0700380 * bootflow_iter_check_net() - Check that a bootflow uses a network device
Simon Glassa8f5be12022-04-24 23:31:09 -0600381 *
382 * This checks the bootdev in the bootflow to make sure it uses a network
383 * device
384 *
385 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC)
386 */
Simon Glass865328c2023-01-17 10:47:54 -0700387int bootflow_iter_check_net(const struct bootflow_iter *iter);
Simon Glassa8f5be12022-04-24 23:31:09 -0600388
389/**
Simon Glass865328c2023-01-17 10:47:54 -0700390 * bootflow_iter_check_system() - Check that a bootflow uses the bootstd device
Simon Glassa8f5be12022-04-24 23:31:09 -0600391 *
392 * This checks the bootdev in the bootflow to make sure it uses the bootstd
393 * device
394 *
395 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC)
396 */
Simon Glass865328c2023-01-17 10:47:54 -0700397int bootflow_iter_check_system(const struct bootflow_iter *iter);
Simon Glassa8f5be12022-04-24 23:31:09 -0600398
Simon Glass02d929b2023-01-06 08:52:40 -0600399/**
400 * bootflow_menu_new() - Create a new bootflow menu
401 *
402 * @expp: Returns the expo created
403 * Returns 0 on success, -ve on error
404 */
405int bootflow_menu_new(struct expo **expp);
406
407/**
Simon Glasse64c2952023-01-06 08:52:42 -0600408 * bootflow_menu_apply_theme() - Apply a theme to a bootmenu
409 *
410 * @exp: Expo to update
411 * @node: Node containing the theme information
412 * Returns 0 on success, -ve on error
413 */
414int bootflow_menu_apply_theme(struct expo *exp, ofnode node);
415
416/**
Simon Glass02d929b2023-01-06 08:52:40 -0600417 * bootflow_menu_run() - Create and run a menu of available bootflows
418 *
419 * @std: Bootstd information
420 * @text_mode: Uses a text-based menu suitable for a serial port
421 * @bflowp: Returns chosen bootflow (set to NULL if nothing is chosen)
422 * @return 0 if an option was chosen, -EAGAIN if nothing was chosen, -ve on
423 * error
424 */
425int bootflow_menu_run(struct bootstd_priv *std, bool text_mode,
426 struct bootflow **bflowp);
427
Simon Glass9d260252022-04-24 23:31:05 -0600428#endif