diff options
Diffstat (limited to 'include/bootmeth.h')
| -rw-r--r-- | include/bootmeth.h | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/include/bootmeth.h b/include/bootmeth.h new file mode 100644 index 00000000000..26de593a9a4 --- /dev/null +++ b/include/bootmeth.h @@ -0,0 +1,424 @@ +/* SPDX-License-Identifier: GPL-2.0+ */ +/* + * Copyright 2021 Google LLC + * Written by Simon Glass <sjg@chromium.org> + */ + +#ifndef __bootmeth_h +#define __bootmeth_h + +#include <bootflow.h> +#include <linux/bitops.h> + +struct blk_desc; +struct udevice; + +/** + * enum bootmeth_flags - Flags for bootmeths + * + * @BOOTMETHF_GLOBAL: bootmeth handles bootdev selection automatically + * @BOOTMETHF_ANY_PART: bootmeth is willing to check any partition, even if it + * has no filesystem + */ +enum bootmeth_flags { + BOOTMETHF_GLOBAL = BIT(0), + BOOTMETHF_ANY_PART = BIT(1), +}; + +/** + * struct bootmeth_uc_plat - information the uclass keeps about each bootmeth + * + * @desc: A long description of the bootmeth + * @flags: Flags for this bootmeth (enum bootmeth_flags) + */ +struct bootmeth_uc_plat { + const char *desc; + int flags; +}; + +/** struct bootmeth_ops - Operations for boot methods */ +struct bootmeth_ops { + /** + * get_state_desc() - get detailed state information + * + * Produces a textual description of the state of the boot method. This + * can include newline characters if it extends to multiple lines. It + * must be a nul-terminated string. + * + * This may involve reading state from the system, e.g. some data in + * the firmware area. + * + * @dev: Bootmethod device to check + * @buf: Buffer to place the info in (terminator must fit) + * @maxsize: Size of buffer + * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if + * something else went wrong + */ + int (*get_state_desc)(struct udevice *dev, char *buf, int maxsize); + + /** + * check_supported() - check if a bootmeth supports this bootdev + * + * This is optional. If not provided, the bootdev is assumed to be + * supported + * + * The bootmeth can check the bootdev (e.g. to make sure it is a + * network device) or the partition information. The following fields + * in @iter are available: + * + * name, dev, state, part + * max_part may be set if part != 0 (i.e. there is a valid partition + * table). Otherwise max_part is 0 + * method is available but is the same as @dev + * the partition has not yet been read, nor has the filesystem been + * checked + * + * It may update only the flags in @iter + * + * @dev: Bootmethod device to check against + * @iter: On entry, provides bootdev, hwpart, part + * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported + */ + int (*check)(struct udevice *dev, struct bootflow_iter *iter); + + /** + * read_bootflow() - read a bootflow for a device + * + * @dev: Bootmethod device to use + * @bflow: On entry, provides dev, hwpart, part and method. + * Returns updated bootflow if found + * Return: 0 if OK, -ve on error + */ + int (*read_bootflow)(struct udevice *dev, struct bootflow *bflow); + + /** + * set_bootflow() - set the bootflow for a device + * + * This provides a bootflow file to the bootmeth, to see if it is valid. + * If it is, the bootflow is set up accordingly. + * + * @dev: Bootmethod device to use + * @bflow: On entry, provides bootdev. + * Returns updated bootflow if found + * @buf: Buffer containing the possible bootflow file + * @size: Size of file + * Return: 0 if OK, -ve on error + */ + int (*set_bootflow)(struct udevice *dev, struct bootflow *bflow, + char *buf, int size); + + /** + * read_file() - read a file needed for a bootflow + * + * Read a file from the same place as the bootflow came from + * + * @dev: Bootmethod device to use + * @bflow: Bootflow providing info on where to read from + * @file_path: Path to file (may be absolute or relative) + * @addr: Address to load file + * @type: File type (IH_TYPE_...) + * @sizep: On entry provides the maximum permitted size; on exit + * returns the size of the file + * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other + * -ve value if something else goes wrong + */ + int (*read_file)(struct udevice *dev, struct bootflow *bflow, + const char *file_path, ulong addr, + enum bootflow_img_t type, ulong *sizep); +#if CONFIG_IS_ENABLED(BOOTSTD_FULL) + /** + * readall() - read all files for a bootflow + * + * @dev: Bootmethod device to boot + * @bflow: Bootflow to read + * Return: 0 if OK, -EIO on I/O error, other -ve on other error + */ + int (*read_all)(struct udevice *dev, struct bootflow *bflow); +#endif /* BOOTSTD_FULL */ + /** + * boot() - boot a bootflow + * + * @dev: Bootmethod device to boot + * @bflow: Bootflow to boot + * Return: does not return on success, since it should boot the + * operating system. Returns -EFAULT if that fails, -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, other -ve on other error + */ + int (*boot)(struct udevice *dev, struct bootflow *bflow); + + /** + * set_property() - set the bootmeth property + * + * This allows the setting of boot method specific properties to enable + * automated finer grain control of the boot process + * + * @name: String containing the name of the relevant boot method + * @property: String containing the name of the property to set + * @value: String containing the value to be set for the specified + * property + * Return: 0 if OK, -ENODEV if an unknown bootmeth or property is + * provided, -ENOENT if there are no bootmeth devices + */ + int (*set_property)(struct udevice *dev, const char *property, + const char *value); +}; + +#define bootmeth_get_ops(dev) ((struct bootmeth_ops *)(dev)->driver->ops) + +/** + * bootmeth_get_state_desc() - get detailed state information + * + * Produces a textual description of the state of the boot method. This + * can include newline characters if it extends to multiple lines. It + * must be a nul-terminated string. + * + * This may involve reading state from the system, e.g. some data in + * the firmware area. + * + * @dev: Bootmethod device to check + * @buf: Buffer to place the info in (terminator must fit) + * @maxsize: Size of buffer + * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if + * something else went wrong + */ +int bootmeth_get_state_desc(struct udevice *dev, char *buf, int maxsize); + +/** + * bootmeth_check() - check if a bootmeth supports this bootflow + * + * This is optional. If not provided, the bootdev is assumed to be + * supported + * + * The bootmeth can check the bootdev (e.g. to make sure it is a + * network device) or the partition information. The following fields + * in @iter are available: + * + * name, dev, state, part + * max_part may be set if part != 0 (i.e. there is a valid partition + * table). Otherwise max_part is 0 + * method is available but is the same as @dev + * the partition has not yet been read, nor has the filesystem been + * checked + * + * It may update only the flags in @iter + * + * @dev: Bootmethod device to check against + * @iter: On entry, provides bootdev, hwpart, part + * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported + */ +int bootmeth_check(struct udevice *dev, struct bootflow_iter *iter); + +/** + * bootmeth_read_bootflow() - set up a bootflow for a device + * + * @dev: Bootmethod device to check + * @bflow: On entry, provides dev, hwpart, part and method. + * Returns updated bootflow if found + * Return: 0 if OK, -ve on error + */ +int bootmeth_read_bootflow(struct udevice *dev, struct bootflow *bflow); + +/** + * bootmeth_set_bootflow() - set the bootflow for a device + * + * This provides a bootflow file to the bootmeth, to see if it is valid. + * If it is, the bootflow is set up accordingly. + * + * @dev: Bootmethod device to use + * @bflow: On entry, provides bootdev. + * Returns updated bootflow if found + * @buf: Buffer containing the possible bootflow file (must be allocated + * by caller to @size + 1 bytes) + * @size: Size of file + * Return: 0 if OK, -ve on error + */ +int bootmeth_set_bootflow(struct udevice *dev, struct bootflow *bflow, + char *buf, int size); + +/** + * bootmeth_read_file() - read a file needed for a bootflow + * + * Read a file from the same place as the bootflow came from + * + * @dev: Bootmethod device to use + * @bflow: Bootflow providing info on where to read from + * @file_path: Path to file (may be absolute or relative) + * @addr: Address to load file + * @type: File type (IH_TYPE_...) + * @sizep: On entry provides the maximum permitted size; on exit + * returns the size of the file + * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other + * -ve value if something else goes wrong + */ +int bootmeth_read_file(struct udevice *dev, struct bootflow *bflow, + const char *file_path, ulong addr, + enum bootflow_img_t type, ulong *sizep); + +/** + * bootmeth_read_all() - read all bootflow files + * + * Some bootmeths delay reading of large files until booting is requested. This + * causes those files to be read. + * + * @dev: Bootmethod device to use + * @bflow: Bootflow to read + * Return: does not return on success, since it should boot the + * operating system. Returns -EFAULT if that fails, other -ve on + * other error + */ +int bootmeth_read_all(struct udevice *dev, struct bootflow *bflow); + +/** + * bootmeth_boot() - boot a bootflow + * + * @dev: Bootmethod device to boot + * @bflow: Bootflow to boot + * Return: does not return on success, since it should boot the + * operating system. Returns -EFAULT if that fails, other -ve on + * other error + */ +int bootmeth_boot(struct udevice *dev, struct bootflow *bflow); + +/** + * bootmeth_setup_iter_order() - Set up the ordering of bootmeths to scan + * + * This sets up the ordering information in @iter, based on the selected + * ordering of the boot methods in bootstd_priv->bootmeth_order. If there is no + * ordering there, then all bootmethods are added + * + * @iter: Iterator to update with the order + * @include_global: true to add the global bootmeths, in which case they appear + * first + * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve + * on other error + */ +int bootmeth_setup_iter_order(struct bootflow_iter *iter, bool include_global); + +/** + * bootmeth_set_order() - Set the bootmeth order + * + * This selects the ordering to use for bootmeths + * + * @order_str: String containing the ordering. This is a comma-separate list of + * bootmeth-device names, e.g. "extlinux,efi". If empty then a default ordering + * is used, based on the sequence number of devices (i.e. using aliases) + * Return: 0 if OK, -ENODEV if an unknown bootmeth is mentioned, -ENOMEM if + * out of memory, -ENOENT if there are no bootmeth devices + */ +int bootmeth_set_order(const char *order_str); + +/** + * bootmeth_set_property() - Set the bootmeth property + * + * This allows the setting of boot method specific properties to enable + * automated finer grain control of the boot process + * + * @name: String containing the name of the relevant boot method + * @property: String containing the name of the property to set + * @value: String containing the value to be set for the specified property + * Return: 0 if OK, -ENODEV if an unknown bootmeth or property is provided, + * -ENOENT if there are no bootmeth devices + */ +int bootmeth_set_property(const char *name, const char *property, + const char *value); + +/** + * bootmeth_setup_fs() - Set up read to read a file + * + * We must redo the setup before each filesystem operation. This function + * handles that, including setting the filesystem type if a block device is not + * being used + * + * @bflow: Information about file to try + * @desc: Block descriptor to read from (NULL if not a block device) + * Return: 0 if OK, -ve on error + */ +int bootmeth_setup_fs(struct bootflow *bflow, struct blk_desc *desc); + +/** + * bootmeth_try_file() - See we can access a given file + * + * Check for a file with a given name. If found, the filename is allocated in + * @bflow + * + * Sets the state to BOOTFLOWST_FILE on success. It also calls + * fs_set_blk_dev_with_part() so that this does not need to be done by the + * caller before reading the file. + * + * @bflow: Information about file to try + * @desc: Block descriptor to read from (NULL for sandbox host) + * @prefix: Filename prefix to prepend to @fname (NULL for none) + * @fname: Filename to read + * Return: 0 if OK, -ENOMEM if not enough memory to allocate bflow->fname, + * other -ve value on other error + */ +int bootmeth_try_file(struct bootflow *bflow, struct blk_desc *desc, + const char *prefix, const char *fname); + +/** + * bootmeth_alloc_file() - Allocate and read a bootflow file + * + * Allocates memory for a bootflow file and reads it in. Sets the state to + * BOOTFLOWST_READY on success + * + * Note that fs_set_blk_dev_with_part() must have been called previously. + * + * @bflow: Information about file to read + * @size_limit: Maximum file size to permit + * @align: Allocation alignment (1 for unaligned) + * @type: File type (IH_TYPE_...) + * Return: 0 if OK, -E2BIG if file is too large, -ENOMEM if out of memory, + * other -ve on other error + */ +int bootmeth_alloc_file(struct bootflow *bflow, uint size_limit, uint align, + enum bootflow_img_t type); + +/** + * bootmeth_alloc_other() - Allocate and read a file for a bootflow + * + * This reads an arbitrary file in the same directory as the bootflow, + * allocating memory for it. The buffer is one byte larger than the file length, + * so that it can be nul-terminated. + * + * @bflow: Information about file to read + * @fname: Filename to read from (within bootflow->subdir) + * @type: File type (IH_TYPE_...) + * @bufp: Returns a pointer to the allocated buffer + * @sizep: Returns the size of the buffer + * Return: 0 if OK, -ENOMEM if out of memory, other -ve on other error + */ +int bootmeth_alloc_other(struct bootflow *bflow, const char *fname, + enum bootflow_img_t type, void **bufp, uint *sizep); + +/** + * bootmeth_common_read_file() - Common handler for reading a file + * + * Reads a named file from the same location as the bootflow file. + * + * @dev: bootmeth device to read from + * @bflow: Bootflow information + * @file_path: Path to file + * @addr: Address to load file to + * @type: File type (IH_TYPE_...) + * @sizep: On entry, the maximum file size to accept, on exit the actual file + * size read + */ +int bootmeth_common_read_file(struct udevice *dev, struct bootflow *bflow, + const char *file_path, ulong addr, + enum bootflow_img_t type, ulong *sizep); + +/** + * bootmeth_get_bootflow() - Get a bootflow from a global bootmeth + * + * Check the bootmeth for a bootflow which can be used. In this case the + * bootmeth handles all bootdev selection, etc. + * + * @dev: bootmeth device to read from + * @bflow: Bootflow information + * @return 0 on success, -ve if a bootflow could not be found or had an error + */ +int bootmeth_get_bootflow(struct udevice *dev, struct bootflow *bflow); + +#endif |