1/* 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 10#include <bootdev.h> 11#include <dm/ofnode_decl.h> 12#include <linux/list.h> 13 14struct bootstd_priv; 15struct expo; 16 17enum { 18 BOOTFLOW_MAX_USED_DEVS = 16, 19}; 20 21/** 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 * enum bootflow_flags_t - flags for bootflows 41 * 42 * @BOOTFLOWF_USE_PRIOR_FDT: Indicates that an FDT was not found by the bootmeth 43 * and it is using the prior-stage FDT, which is the U-Boot control FDT. 44 * This is only possible with the EFI bootmeth (distro-efi) and only when 45 * CONFIG_OF_HAS_PRIOR_STAGE is enabled 46 * @BOOTFLOWF_STATIC_BUF: Indicates that @bflow->buf is statically set, rather 47 * than being allocated by malloc(). 48 * @BOOTFLOWF_USE_BUILTIN_FDT : Indicates that current bootflow uses built-in FDT 49 */ 50enum bootflow_flags_t { 51 BOOTFLOWF_USE_PRIOR_FDT = 1 << 0, 52 BOOTFLOWF_STATIC_BUF = 1 << 1, 53 BOOTFLOWF_USE_BUILTIN_FDT = 1 << 2, 54}; 55 56/** 57 * struct bootflow - information about a bootflow 58 * 59 * This is connected into two separate linked lists: 60 * 61 * bm_sibling - links all bootflows in the same bootdev 62 * glob_sibling - links all bootflows in all bootdevs 63 * 64 * @bm_node: Points to siblings in the same bootdev 65 * @glob_node: Points to siblings in the global list (all bootdev) 66 * @dev: Bootdev device which produced this bootflow 67 * @blk: Block device which contains this bootflow, NULL if this is a network 68 * device or sandbox 'host' device 69 * @part: Partition number (0 for whole device) 70 * @fs_type: Filesystem type (FS_TYPE...) if this is fixed by the media, else 0. 71 * For example, the sandbox host-filesystem bootdev sets this to 72 * FS_TYPE_SANDBOX 73 * @method: Bootmethod device used to perform the boot and read files 74 * @name: Name of bootflow (allocated) 75 * @state: Current state (enum bootflow_state_t) 76 * @subdir: Subdirectory to fetch files from (with trailing /), or NULL if none 77 * @fname: Filename of bootflow file (allocated) 78 * @logo: Logo to display for this bootflow (BMP format) 79 * @logo_size: Size of the logo in bytes 80 * @buf: Bootflow file contents (allocated unless @flags & BOOTFLOWF_STATIC_BUF) 81 * @size: Size of bootflow file in bytes 82 * @err: Error number received (0 if OK) 83 * @os_name: Name of the OS / distro being booted, or NULL if not known 84 * (allocated) 85 * @fdt_fname: Filename of FDT file 86 * @fdt_size: Size of FDT file 87 * @fdt_addr: Address of loaded fdt 88 * @flags: Flags for the bootflow (see enum bootflow_flags_t) 89 * @cmdline: OS command line, or NULL if not known (allocated) 90 * @x86_setup: Pointer to x86 setup block inside @buf, NULL if not present 91 * @bootmeth_priv: Private data for the bootmeth 92 */ 93struct bootflow { 94 struct list_head bm_node; 95 struct list_head glob_node; 96 struct udevice *dev; 97 struct udevice *blk; 98 int part; 99 int fs_type; 100 struct udevice *method; 101 char *name; 102 enum bootflow_state_t state; 103 char *subdir; 104 char *fname; 105 void *logo; 106 uint logo_size; 107 char *buf; 108 int size; 109 int err; 110 char *os_name; 111 char *fdt_fname; 112 int fdt_size; 113 ulong fdt_addr; 114 int flags; 115 char *cmdline; 116 void *x86_setup; 117 void *bootmeth_priv; 118}; 119 120/** 121 * enum bootflow_iter_flags_t - flags for the bootflow iterator 122 * 123 * @BOOTFLOWIF_FIXED: Only used fixed/internal media 124 * @BOOTFLOWIF_SHOW: Show each bootdev before scanning it; show each hunter 125 * before using it 126 * @BOOTFLOWIF_ALL: Return bootflows with errors as well 127 * @BOOTFLOWIF_HUNT: Hunt for new bootdevs using the bootdrv hunters 128 * 129 * Internal flags: 130 * @BOOTFLOWIF_SINGLE_DEV: (internal) Just scan one bootdev 131 * @BOOTFLOWIF_SKIP_GLOBAL: (internal) Don't scan global bootmeths 132 * @BOOTFLOWIF_SINGLE_UCLASS: (internal) Keep scanning through all devices in 133 * this uclass (used with things like "mmc") 134 * @BOOTFLOWIF_SINGLE_MEDIA: (internal) Scan one media device in the uclass (used 135 * with things like "mmc1") 136 * @BOOTFLOWIF_SINGLE_PARTITION: (internal) Scan one partition in media device 137 * (used with things like "mmc1:3") 138 */ 139enum bootflow_iter_flags_t { 140 BOOTFLOWIF_FIXED = 1 << 0, 141 BOOTFLOWIF_SHOW = 1 << 1, 142 BOOTFLOWIF_ALL = 1 << 2, 143 BOOTFLOWIF_HUNT = 1 << 3, 144 145 /* 146 * flags used internally by standard boot - do not set these when 147 * calling bootflow_scan_bootdev() etc. 148 */ 149 BOOTFLOWIF_SINGLE_DEV = 1 << 16, 150 BOOTFLOWIF_SKIP_GLOBAL = 1 << 17, 151 BOOTFLOWIF_SINGLE_UCLASS = 1 << 18, 152 BOOTFLOWIF_SINGLE_MEDIA = 1 << 19, 153 BOOTFLOWIF_SINGLE_PARTITION = 1 << 20, 154}; 155 156/** 157 * enum bootflow_meth_flags_t - flags controlling which bootmeths are used 158 * 159 * Used during iteration, e.g. by bootdev_find_by_label(), to determine which 160 * bootmeths are used for the current bootdev. The flags reset when the bootdev 161 * changes 162 * 163 * @BOOTFLOW_METHF_DHCP_ONLY: Only use dhcp (scripts and EFI) 164 * @BOOTFLOW_METHF_PXE_ONLY: Only use pxe (PXE boot) 165 * @BOOTFLOW_METHF_SINGLE_DEV: Scan only a single bootdev (used for labels like 166 * "3"). This is used if a sequence number is provided instead of a label 167 * @BOOTFLOW_METHF_SINGLE_UCLASS: Scan all bootdevs in this one uclass (used 168 * with things like "mmc"). If this is not set, then the bootdev has an integer 169 * value in the label (like "mmc2") 170 */ 171enum bootflow_meth_flags_t { 172 BOOTFLOW_METHF_DHCP_ONLY = 1 << 0, 173 BOOTFLOW_METHF_PXE_ONLY = 1 << 1, 174 BOOTFLOW_METHF_SINGLE_DEV = 1 << 2, 175 BOOTFLOW_METHF_SINGLE_UCLASS = 1 << 3, 176}; 177 178/** 179 * struct bootflow_iter - state for iterating through bootflows 180 * 181 * This starts at with the first bootdev/partition/bootmeth and can be used to 182 * iterate through all of them. 183 * 184 * Iteration starts with the bootdev. The first partition (0, i.e. whole device) 185 * is scanned first. For partition 0, it iterates through all the available 186 * bootmeths to see which one(s) can provide a bootflow. Then it moves to 187 * parition 1 (if there is one) and the process continues. Once all partitions 188 * are examined, it moves to the next bootdev. 189 * 190 * Initially @max_part is 0, meaning that only the whole device (@part=0) can be 191 * used. During scanning, if a partition table is found, then @max_part is 192 * updated to a larger value, no less than the number of available partitions. 193 * This ensures that iteration works through all partitions on the bootdev. 194 * 195 * @flags: Flags to use (see enum bootflow_iter_flags_t). If 196 * BOOTFLOWIF_GLOBAL_FIRST is enabled then the global bootmeths are being 197 * scanned, otherwise we have moved onto the bootdevs 198 * @dev: Current bootdev, NULL if none. This is only ever updated in 199 * bootflow_iter_set_dev() 200 * @part: Current partition number (0 for whole device) 201 * @method: Current bootmeth 202 * @max_part: Maximum hardware partition number in @dev, 0 if there is no 203 * partition table 204 * @first_bootable: First bootable partition, or 0 if none 205 * @err: Error obtained from checking the last iteration. This is used to skip 206 * forward (e.g. to skip the current partition because it is not valid) 207 * -ESHUTDOWN: try next bootdev 208 * @num_devs: Number of bootdevs in @dev_used 209 * @max_devs: Maximum number of entries in @dev_used 210 * @dev_used: List of bootdevs used during iteration 211 * @labels: List of labels to scan for bootdevs 212 * @cur_label: Current label being processed 213 * @num_methods: Number of bootmeth devices in @method_order 214 * @cur_method: Current method number, an index into @method_order 215 * @first_glob_method: First global method, if any, else -1 216 * @cur_prio: Current priority being scanned 217 * @method_order: List of bootmeth devices to use, in order. The normal methods 218 * appear first, then the global ones, if any 219 * @doing_global: true if we are iterating through the global bootmeths (which 220 * happens before the normal ones) 221 * @method_flags: flags controlling which methods should be used for this @dev 222 * (enum bootflow_meth_flags_t) 223 */ 224struct bootflow_iter { 225 int flags; 226 struct udevice *dev; 227 int part; 228 struct udevice *method; 229 int max_part; 230 int first_bootable; 231 int err; 232 int num_devs; 233 int max_devs; 234 struct udevice *dev_used[BOOTFLOW_MAX_USED_DEVS]; 235 const char *const *labels; 236 int cur_label; 237 int num_methods; 238 int cur_method; 239 int first_glob_method; 240 enum bootdev_prio_t cur_prio; 241 struct udevice **method_order; 242 bool doing_global; 243 int method_flags; 244}; 245 246/** 247 * bootflow_init() - Set up a bootflow struct 248 * 249 * The bootflow is zeroed and set to state BOOTFLOWST_BASE 250 * 251 * @bflow: Struct to set up 252 * @bootdev: Bootdev to use 253 * @meth: Bootmeth to use 254 */ 255void bootflow_init(struct bootflow *bflow, struct udevice *bootdev, 256 struct udevice *meth); 257 258/** 259 * bootflow_iter_init() - Reset a bootflow iterator 260 * 261 * This sets everything to the starting point, ready for use. 262 * 263 * @iter: Place to store private info (inited by this call) 264 * @flags: Flags to use (see enum bootflow_iter_flags_t) 265 */ 266void bootflow_iter_init(struct bootflow_iter *iter, int flags); 267 268/** 269 * bootflow_iter_uninit() - Free memory used by an interator 270 * 271 * @iter: Iterator to free 272 */ 273void bootflow_iter_uninit(struct bootflow_iter *iter); 274 275/** 276 * bootflow_iter_drop_bootmeth() - Remove a bootmeth from an iterator 277 * 278 * Update the iterator so that the bootmeth will not be used again while this 279 * iterator is in use 280 * 281 * @iter: Iterator to update 282 * @bmeth: Boot method to remove 283 */ 284int bootflow_iter_drop_bootmeth(struct bootflow_iter *iter, 285 const struct udevice *bmeth); 286 287/** 288 * bootflow_scan_first() - find the first bootflow for a device or label 289 * 290 * If @flags includes BOOTFLOWIF_ALL then bootflows with errors are returned too 291 * 292 * @dev: Boot device to scan, NULL to work through all of them until it 293 * finds one that can supply a bootflow 294 * @label: Label to control the scan, NULL to work through all devices 295 * until it finds one that can supply a bootflow 296 * @iter: Place to store private info (inited by this call) 297 * @flags: Flags for iterator (enum bootflow_iter_flags_t). Note that if 298 * @dev is NULL, then BOOTFLOWIF_SKIP_GLOBAL is set automatically by this 299 * function 300 * @bflow: Place to put the bootflow if found 301 * Return: 0 if found, -ENODEV if no device, other -ve on other error 302 * (iteration can continue) 303 */ 304int bootflow_scan_first(struct udevice *dev, const char *label, 305 struct bootflow_iter *iter, int flags, 306 struct bootflow *bflow); 307 308/** 309 * bootflow_scan_next() - find the next bootflow 310 * 311 * This works through the available bootdev devices until it finds one that 312 * can supply a bootflow. It then returns that bootflow 313 * 314 * @iter: Private info (as set up by bootflow_scan_first()) 315 * @bflow: Place to put the bootflow if found 316 * Return: 0 if found, -ENODEV if no device, -ESHUTDOWN if no more bootflows, 317 * other -ve on other error (iteration can continue) 318 */ 319int bootflow_scan_next(struct bootflow_iter *iter, struct bootflow *bflow); 320 321/** 322 * bootflow_first_glob() - Get the first bootflow from the global list 323 * 324 * Returns the first bootflow in the global list, no matter what bootflow it is 325 * attached to 326 * 327 * @bflowp: Returns a pointer to the bootflow 328 * Return: 0 if found, -ENOENT if there are no bootflows 329 */ 330int bootflow_first_glob(struct bootflow **bflowp); 331 332/** 333 * bootflow_next_glob() - Get the next bootflow from the global list 334 * 335 * Returns the next bootflow in the global list, no matter what bootflow it is 336 * attached to 337 * 338 * @bflowp: On entry, the last bootflow returned , e.g. from 339 * bootflow_first_glob() 340 * Return: 0 if found, -ENOENT if there are no more bootflows 341 */ 342int bootflow_next_glob(struct bootflow **bflowp); 343 344/** 345 * bootflow_free() - Free memory used by a bootflow 346 * 347 * This frees fields within @bflow, but not the @bflow pointer itself 348 */ 349void bootflow_free(struct bootflow *bflow); 350 351/** 352 * bootflow_boot() - boot a bootflow 353 * 354 * @bflow: Bootflow to boot 355 * Return: -EPROTO if bootflow has not been loaded, -ENOSYS if the bootflow 356 * type is not supported, -EFAULT if the boot returned without an error 357 * when we are expecting it to boot, -ENOTSUPP if trying method resulted in 358 * finding out that is not actually supported for this boot and should not 359 * be tried again unless something changes 360 */ 361int bootflow_boot(struct bootflow *bflow); 362 363/** 364 * bootflow_read_all() - Read all bootflow files 365 * 366 * Some bootmeths delay reading of large files until booting is requested. This 367 * causes those files to be read. 368 * 369 * @bflow: Bootflow to read 370 * Return: result of trying to read 371 */ 372int bootflow_read_all(struct bootflow *bflow); 373 374/** 375 * bootflow_run_boot() - Try to boot a bootflow 376 * 377 * @iter: Current iteration (or NULL if none). Used to disable a bootmeth if the 378 * boot returns -ENOTSUPP 379 * @bflow: Bootflow to boot 380 * Return: result of trying to boot 381 */ 382int bootflow_run_boot(struct bootflow_iter *iter, struct bootflow *bflow); 383 384/** 385 * bootflow_state_get_name() - Get the name of a bootflow state 386 * 387 * @state: State to check 388 * Return: name, or "?" if invalid 389 */ 390const char *bootflow_state_get_name(enum bootflow_state_t state); 391 392/** 393 * bootflow_remove() - Remove a bootflow and free its memory 394 * 395 * This updates the linked lists containing the bootflow then frees it. 396 * 397 * @bflow: Bootflow to remove 398 */ 399void bootflow_remove(struct bootflow *bflow); 400 401/** 402 * bootflow_iter_check_blk() - Check that a bootflow uses a block device 403 * 404 * This checks the bootdev in the bootflow to make sure it uses a block device 405 * 406 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. ethernet) 407 */ 408int bootflow_iter_check_blk(const struct bootflow_iter *iter); 409 410/** 411 * bootflow_iter_check_sf() - Check that a bootflow uses SPI FLASH 412 * 413 * This checks the bootdev in the bootflow to make sure it uses SPI flash 414 * 415 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. ethernet) 416 */ 417int bootflow_iter_check_sf(const struct bootflow_iter *iter); 418 419/** 420 * bootflow_iter_check_net() - Check that a bootflow uses a network device 421 * 422 * This checks the bootdev in the bootflow to make sure it uses a network 423 * device 424 * 425 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC) 426 */ 427int bootflow_iter_check_net(const struct bootflow_iter *iter); 428 429/** 430 * bootflow_iter_check_system() - Check that a bootflow uses the bootstd device 431 * 432 * This checks the bootdev in the bootflow to make sure it uses the bootstd 433 * device 434 * 435 * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC) 436 */ 437int bootflow_iter_check_system(const struct bootflow_iter *iter); 438 439/** 440 * bootflow_menu_new() - Create a new bootflow menu 441 * 442 * @expp: Returns the expo created 443 * Returns 0 on success, -ve on error 444 */ 445int bootflow_menu_new(struct expo **expp); 446 447/** 448 * bootflow_menu_apply_theme() - Apply a theme to a bootmenu 449 * 450 * @exp: Expo to update 451 * @node: Node containing the theme information 452 * Returns 0 on success, -ve on error 453 */ 454int bootflow_menu_apply_theme(struct expo *exp, ofnode node); 455 456/** 457 * bootflow_menu_run() - Create and run a menu of available bootflows 458 * 459 * @std: Bootstd information 460 * @text_mode: Uses a text-based menu suitable for a serial port 461 * @bflowp: Returns chosen bootflow (set to NULL if nothing is chosen) 462 * @return 0 if an option was chosen, -EAGAIN if nothing was chosen, -ve on 463 * error 464 */ 465int bootflow_menu_run(struct bootstd_priv *std, bool text_mode, 466 struct bootflow **bflowp); 467 468#define BOOTFLOWCL_EMPTY ((void *)1) 469 470/** 471 * cmdline_set_arg() - Update or read an argument in a cmdline string 472 * 473 * Handles updating a single arg in a cmdline string, returning it in a supplied 474 * buffer; also reading an arg from a cmdline string 475 * 476 * When updating, consecutive spaces are squashed as are spaces at the start and 477 * end. 478 * 479 * @buf: Working buffer to use (initial contents are ignored). Use NULL when 480 * reading 481 * @maxlen: Length of working buffer. Use 0 when reading 482 * @cmdline: Command line to update, in the form: 483 * 484 * fred mary= jane=123 john="has spaces" 485 * 486 * @set_arg: Argument to set or read (may or may not exist) 487 * @new_val: Value for the new argument. May not include quotes (") but may 488 * include embedded spaces, in which case it will be quoted when added to the 489 * command line. Use NULL to delete the argument from @cmdline, BOOTFLOWCL_EMPTY 490 * to set it to an empty value (no '=' sign after arg), "" to add an '=' sign 491 * but with an empty value. Use NULL when reading. 492 * @posp: Ignored when setting an argument; when getting an argument, returns 493 * the start position of its value in @cmdline, after the first quote, if any 494 * 495 * Return: 496 * For updating: 497 * length of new buffer (including \0 terminator) on success, -ENOENT if 498 * @new_val is NULL and @set_arg does not exist in @from, -EINVAL if a 499 * quoted arg-value in @from is not terminated with a quote, -EBADF if 500 * @new_val has spaces but does not start and end with quotes (or it has 501 * quotes in the middle of the string), -E2BIG if @maxlen is too small 502 * For reading: 503 * length of arg value (excluding quotes), -ENOENT if not found 504 */ 505int cmdline_set_arg(char *buf, int maxlen, const char *cmdline, 506 const char *set_arg, const char *new_val, int *posp); 507 508/** 509 * bootflow_cmdline_set_arg() - Set a single argument for a bootflow 510 * 511 * Update the allocated cmdline and set the bootargs variable 512 * 513 * @bflow: Bootflow to update 514 * @arg: Argument to update (e.g. "console") 515 * @val: Value to set (e.g. "ttyS2") or NULL to delete the argument if present, 516 * "" to set it to an empty value (e.g. "console=") and BOOTFLOWCL_EMPTY to add 517 * it without any value ("initrd") 518 * @set_env: true to set the "bootargs" environment variable too 519 * 520 * Return: 0 if OK, -ENOMEM if out of memory 521 */ 522int bootflow_cmdline_set_arg(struct bootflow *bflow, const char *arg, 523 const char *val, bool set_env); 524 525/** 526 * cmdline_get_arg() - Read an argument from a cmdline 527 * 528 * @cmdline: Command line to read, in the form: 529 * 530 * fred mary= jane=123 john="has spaces" 531 * @arg: Argument to read (may or may not exist) 532 * @posp: Returns position of argument (after any leading quote) if present 533 * Return: Length of argument value excluding quotes if found, -ENOENT if not 534 * found 535 */ 536int cmdline_get_arg(const char *cmdline, const char *arg, int *posp); 537 538/** 539 * bootflow_cmdline_get_arg() - Read an argument from a cmdline 540 * 541 * @bootflow: Bootflow to read from 542 * @arg: Argument to read (may or may not exist) 543 * @valp: Returns a pointer to the argument (after any leading quote) if present 544 * Return: Length of argument value excluding quotes if found, -ENOENT if not 545 * found 546 */ 547int bootflow_cmdline_get_arg(struct bootflow *bflow, const char *arg, 548 const char **val); 549 550/** 551 * bootflow_cmdline_auto() - Automatically set a value for a known argument 552 * 553 * This handles a small number of known arguments, for Linux in particular. It 554 * adds suitable kernel parameters automatically, e.g. to enable the console. 555 * 556 * @bflow: Bootflow to update 557 * @arg: Name of argument to set (e.g. "earlycon" or "console") 558 * Return: 0 if OK -ve on error 559 */ 560int bootflow_cmdline_auto(struct bootflow *bflow, const char *arg); 561 562#endif 563