include/bootflow.h

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