u-boot/include/bootflow.h
Simon Glass c279224ea6 bootstd: Add a command to read all files for a bootflow
Some bootflows (such as EFI and ChromiumOS) delay reading the kernel until
it is needed to boot. This saves time when scanning and avoids needing to
allocate memory for something that may never be used.

To permit reading of these files, add a new 'bootflow read' command.

Signed-off-by: Simon Glass <sjg@chromium.org>
2023-08-11 07:33:38 -06:00

554 lines
18 KiB
C

/* 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
* @bootmeth_priv: Private data for the bootmeth
*/
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;
void *x86_setup;
void *bootmeth_priv;
};
/**
* 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_read_all() - Read all bootflow files
*
* Some bootmeths delay reading of large files until booting is requested. This
* causes those files to be read.
*
* @bflow: Bootflow to read
* Return: result of trying to read
*/
int bootflow_read_all(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