diff options
Diffstat (limited to 'include/bootdev.h')
| -rw-r--r-- | include/bootdev.h | 206 |
1 files changed, 187 insertions, 19 deletions
diff --git a/include/bootdev.h b/include/bootdev.h index 9fc219839fe..b92ff4d4f15 100644 --- a/include/bootdev.h +++ b/include/bootdev.h @@ -11,6 +11,7 @@ struct bootflow; struct bootflow_iter; +struct bootstd_priv; struct udevice; /** @@ -20,19 +21,87 @@ struct udevice; * * Smallest value is the highest priority. By default, bootdevs are scanned from * highest to lowest priority + * + * BOOTDEVP_0_NONE: Invalid value, do not use + * @BOOTDEVP_6_PRE_SCAN: Scan bootdevs with this priority always, before + * starting any bootflow scan + * @BOOTDEVP_2_INTERNAL_FAST: Internal devices which don't need scanning and + * generally very quick to access, e.g. less than 100ms + * @BOOTDEVP_3_INTERNAL_SLOW: Internal devices which don't need scanning but + * take a significant fraction of a second to access + * @BOOTDEVP_4_SCAN_FAST: Extenal devices which need scanning or bus + * enumeration to find, but this enumeration happens quickly, typically under + * 100ms + * @BOOTDEVP_5_SCAN_SLOW: Extenal devices which need scanning or bus + * enumeration to find. The enumeration takes significant fraction of a second + * to complete + * @BOOTDEVP_6_NET_BASE: Basic network devices which are quickly and easily + * available. Typically used for an internal Ethernet device + * @BOOTDEVP_7_NET_FALLBACK: Secondary network devices which require extra time + * to start up, or are less desirable. Typically used for secondary Ethernet + * devices. Note that USB ethernet devices are found during USB enumeration, + * so do not use this priority */ enum bootdev_prio_t { - BOOTDEVP_0_INTERNAL_FAST = 10, - BOOTDEVP_1_INTERNAL_SLOW = 20, - BOOTDEVP_2_SCAN_FAST = 30, - BOOTDEVP_3_SCAN_SLOW = 40, - BOOTDEVP_4_NET_BASE = 50, - BOOTDEVP_5_NET_FALLBACK = 60, - BOOTDEVP_6_SYSTEM = 70, + BOOTDEVP_0_NONE, + BOOTDEVP_1_PRE_SCAN, + BOOTDEVP_2_INTERNAL_FAST, + BOOTDEVP_3_INTERNAL_SLOW, + BOOTDEVP_4_SCAN_FAST, + BOOTDEVP_5_SCAN_SLOW, + BOOTDEVP_6_NET_BASE, + BOOTDEVP_7_NET_FALLBACK, BOOTDEVP_COUNT, }; +struct bootdev_hunter; + +/** + * bootdev_hunter_func - function to probe for bootdevs of a given type + * + * This should hunt around for bootdevs of the given type, binding them as it + * finds them. This may involve bus enumeration, etc. + * + * @info: Info structure describing this hunter + * @show: true to show information from the hunter + * Returns: 0 if OK, -ve on error + */ +typedef int (*bootdev_hunter_func)(struct bootdev_hunter *info, bool show); + +/** + * struct bootdev_hunter - information about how to hunt for bootdevs + * + * @prio: Scanning priority of this hunter + * @uclass: Uclass ID for the media associated with this bootdev + * @drv: bootdev driver for the things found by this hunter + * @hunt: Function to call to hunt for bootdevs of this type (NULL if none) + * + * Some bootdevs are not visible until other devices are enumerated. For + * example, USB bootdevs only appear when the USB bus is enumerated. + * + * On the other hand, we don't always want to enumerate all the buses just to + * find the first valid bootdev. Ideally we want to work through them in + * priority order, so that the fastest bootdevs are discovered first. + * + * This struct holds information about the bootdev so we can determine the probe + * order and how to hunt for bootdevs of this type + */ +struct bootdev_hunter { + enum bootdev_prio_t prio; + enum uclass_id uclass; + struct driver *drv; + bootdev_hunter_func hunt; +}; + +/* declare a new bootdev hunter */ +#define BOOTDEV_HUNTER(__name) \ + ll_entry_declare(struct bootdev_hunter, __name, bootdev_hunter) + +/* access a bootdev hunter by name */ +#define BOOTDEV_HUNTER_GET(__name) \ + ll_entry_get(struct bootdev_hunter, __name, bootdev_hunter) + /** * struct bootdev_uc_plat - uclass information about a bootdev * @@ -50,7 +119,10 @@ struct bootdev_uc_plat { /** struct bootdev_ops - Operations for the bootdev uclass */ struct bootdev_ops { /** - * get_bootflow() - get a bootflow + * get_bootflow() - get a bootflow (optional) + * + * If this is NULL then the default implementaton is used, which is + * default_get_bootflow() * * @dev: Bootflow device to check * @iter: Provides current dev, part, method to get. Should update @@ -171,40 +243,136 @@ int bootdev_next_bootflow(struct bootflow **bflowp); * @label: Label to look up (e.g. "mmc1" or "mmc0") * @devp: Returns the bootdev device found, or NULL if none (note it does not * return the media device, but its bootdev child) + * @method_flagsp: If non-NULL, returns any flags implied by the label + * (enum bootflow_meth_flags_t), 0 if none. Unset if function fails * Return: 0 if OK, -EINVAL if the uclass is not supported by this board, - * -ENOENT if there is no device with that number + * -ENOENT if there is no device with that number */ -int bootdev_find_by_label(const char *label, struct udevice **devp); +int bootdev_find_by_label(const char *label, struct udevice **devp, + int *method_flagsp); /** * bootdev_find_by_any() - Find a bootdev by name, label or sequence * * @name: name (e.g. "mmc2.bootdev"), label ("mmc2"), or sequence ("2") to find * @devp: returns the device found, on success - * Return: 0 if OK, -ve on error + * @method_flagsp: If non-NULL, returns any flags implied by the label + * (enum bootflow_meth_flags_t), 0 if none. Unset if function fails + * Return: 0 if OK, -EINVAL if the uclass is not supported by this board, + * -ENOENT if there is no device with that number */ -int bootdev_find_by_any(const char *name, struct udevice **devp); +int bootdev_find_by_any(const char *name, struct udevice **devp, + int *method_flagsp); /** - * bootdev_setup_iter_order() - Set up the ordering of bootdevs to scan - * - * This sets up the ordering information in @iter, based on the priority of each - * bootdev and the bootdev-order property in the bootstd node + * bootdev_setup_iter() - Set up iteration through bootdevs * - * If a single device is requested, no ordering is needed + * This sets up the an interation, based on the provided device or label. If + * neither is provided, the iteration is based on the priority of each bootdev, + * the * bootdev-order property in the bootstd node (or the boot_targets env + * var). * * @iter: Iterator to update with the order + * @label: label to scan, or NULL to scan all * @devp: On entry, *devp is NULL to scan all, otherwise this is the (single) * device to scan. Returns the first device to use, which is the passed-in * @devp if it was non-NULL + * @method_flagsp: If non-NULL, returns any flags implied by the label + * (enum bootflow_meth_flags_t), 0 if none * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve * on other error */ -int bootdev_setup_iter_order(struct bootflow_iter *iter, struct udevice **devp); +int bootdev_setup_iter(struct bootflow_iter *iter, const char *label, + struct udevice **devp, int *method_flagsp); + +/** + * bootdev_list_hunters() - List the available bootdev hunters + * + * These provide a way to find new bootdevs by enumerating buses, etc. This + * function lists the available hunters + * + * @std: Pointer to bootstd private info + */ +void bootdev_list_hunters(struct bootstd_priv *std); + +/** + * bootdev_hunt() - Hunt for bootdevs matching a particular spec + * + * This runs the selected hunter (or all if @spec is NULL) to try to find new + * bootdevs. + * + * @spec: Spec to match, e.g. "mmc0", or NULL for any. If provided, this must + * match a uclass name so that the hunter can be determined. Any trailing number + * is ignored + * @show: true to show each hunter before using it + * Returns: 0 if OK, -ve on error + */ +int bootdev_hunt(const char *spec, bool show); + +/** + * bootdev_hunt_prio() - Hunt for bootdevs of a particular priority + * + * This runs all hunters which can find bootdevs of the given priority. + * + * @prio: Priority to use + * @show: true to show each hunter as it is used + * Returns: 0 if OK, -ve on error + */ +int bootdev_hunt_prio(enum bootdev_prio_t prio, bool show); + +/** + * bootdev_hunt_and_find_by_label() - Hunt for bootdevs by label + * + * Runs the hunter for the label, then tries to find the bootdev, possible + * created by the hunter + * + * @label: Label to look up (e.g. "mmc1" or "mmc0") + * @devp: Returns the bootdev device found, or NULL if none (note it does not + * return the media device, but its bootdev child) + * @method_flagsp: If non-NULL, returns any flags implied by the label + * (enum bootflow_meth_flags_t), 0 if none. Unset if function fails + * Return: 0 if OK, -EINVAL if the uclass is not supported by this board, + * -ENOENT if there is no device with that number + */ +int bootdev_hunt_and_find_by_label(const char *label, struct udevice **devp, + int *method_flagsp); + +/** + * bootdev_next_label() - Move to the next bootdev in the label sequence + * + * Looks through the remaining labels until it finds one that matches a bootdev. + * Bootdev scanners are used as needed. For example a label "mmc1" results in + * running the "mmc" bootdrv. + * + * @iter: Interation info, containing iter->cur_label + * @devp: New bootdev found, if any was found + * @method_flagsp: If non-NULL, returns any flags implied by the label + * (enum bootflow_meth_flags_t), 0 if none + * Returns 0 if OK, -ENODEV if no bootdev was found + */ +int bootdev_next_label(struct bootflow_iter *iter, struct udevice **devp, + int *method_flagsp); + +/** + * bootdev_next_prio() - Find the next bootdev in priority order + * + * This moves @devp to the next bootdev with the current priority. If there is + * none, then it moves to the next priority and scans for new bootdevs there. + * + * @iter: Interation info, containing iter->cur_prio + * @devp: On entry this is the previous bootdev that was considered. On exit + * this is the new bootdev, if any was found + * Returns 0 on success (*devp is updated), -ENODEV if there are no more + * bootdevs at any priority + */ +int bootdev_next_prio(struct bootflow_iter *iter, struct udevice **devp); #if CONFIG_IS_ENABLED(BOOTSTD) /** - * bootdev_setup_for_dev() - Bind a new bootdev device + * bootdev_setup_for_dev() - Bind a new bootdev device (deprecated) + * + * Please use bootdev_setup_sibling_blk() instead since it supports multiple + * (child) block devices for each media device. * * Creates a bootdev device as a child of @parent. This should be called from * the driver's bind() method or its uclass' post_bind() method. |