jcs.org
"Das U-Boot" Source Tree
1/* SPDX-License-Identifier: GPL-2.0+ */
2/*
3 * Standard U-Boot boot framework
4 *
5 * Copyright 2021 Google LLC
6 * Written by Simon Glass <sjg@chromium.org>
7 */
8
9#ifndef __bootstd_h
10#define __bootstd_h
11
12#include <alist.h>
13#include <dm/ofnode_decl.h>
14#include <linux/list.h>
15#include <linux/types.h>
16
17struct udevice;
18
19/**
20 * struct bootstd_priv - priv data for the bootstd driver
21 *
22 * This is attached to the (only) bootstd device, so there is only one instance
23 * of this struct. It provides overall information about bootdevs and bootflows.
24 *
25 * TODO(sjg@chromium.org): Convert prefixes, bootdev_order and env_order to use
26 * alist
27 *
28 * @prefixes: NULL-terminated list of prefixes to use for bootflow filenames,
29 * e.g. "/", "/boot/"; NULL if none
30 * @bootdev_order: Order to use for bootdevs (or NULL if none), with each item
31 * being a bootdev label, e.g. "mmc2", "mmc1" (NULL terminated)
32 * @env_order: Order as specified by the boot_targets env var (or NULL if none),
33 * with each item being a bootdev label, e.g. "mmc2", "mmc1" (NULL
34 * terminated)
35 * @cur_bootdev: Currently selected bootdev (for commands)
36 * @cur_bootflow: Currently selected bootflow (for commands)
37 * @bootflows: (struct bootflow) Global list of all bootflows across all
38 * bootdevs
39 * @bootmeth_count: Number of bootmeth devices in @bootmeth_order
40 * @bootmeth_order: List of bootmeth devices to use, in order, NULL-terminated
41 * @vbe_bootmeth: Currently selected VBE bootmeth, NULL if none
42 * @theme: Node containing the theme information
43 * @hunters_used: Bitmask of used hunters, indexed by their position in the
44 * linker list. The bit is set if the hunter has been used already
45 */
46struct bootstd_priv {
47 const char **prefixes;
48 const char **bootdev_order;
49 const char **env_order;
50 struct udevice *cur_bootdev;
51 struct bootflow *cur_bootflow;
52 struct alist bootflows;
53 int bootmeth_count;
54 struct udevice **bootmeth_order;
55 struct udevice *vbe_bootmeth;
56 ofnode theme;
57 uint hunters_used;
58};
59
60/**
61 * bootstd_get_bootdev_order() - Get the boot-order list
62 *
63 * This reads the boot order, e.g. {"mmc0", "mmc2", NULL}
64 *
65 * The list is alloced by the bootstd driver so should not be freed. That is the
66 * reason for all the const stuff in the function signature
67 *
68 * @dev: bootstd device
69 * @okp: returns true if OK, false if out of memory
70 * Return: list of string pointers, terminated by NULL; or NULL if no boot
71 * order. Note that this returns NULL in the case of an empty list
72 */
73const char *const *const bootstd_get_bootdev_order(struct udevice *dev,
74 bool *okp);
75
76/**
77 * bootstd_get_prefixes() - Get the filename-prefixes list
78 *
79 * This reads the prefixes, e.g. {"/", "/boot", NULL}
80 *
81 * The list is alloced by the bootstd driver so should not be freed. That is the
82 * reason for all the const stuff in the function signature
83 *
84 * Return: list of string points, terminated by NULL; or NULL if no boot order
85 */
86const char *const *const bootstd_get_prefixes(struct udevice *dev);
87
88/**
89 * bootstd_get_priv() - Get the (single) state for the bootstd system
90 *
91 * The state holds a global list of all bootflows that have been found.
92 *
93 * Return: 0 if OK, -ve if the uclass does not exist
94 */
95int bootstd_get_priv(struct bootstd_priv **stdp);
96
97/**
98 * bootstd_try_priv() - Try to get the (single) state for the bootstd system
99 *
100 * The state holds a global list of all bootflows that have been found. This
101 * function returns the state if available, but takes care not to create the
102 * device (or uclass) if it doesn't exist.
103 *
104 * This function is safe to use in the 'unbind' path. It will always return NULL
105 * unless the bootstd device is probed and ready, e.g. bootstd_get_priv() has
106 * previously been called.
107 *
108 * TODO(sjg@chromium.org): Consider adding a bootstd pointer to global_data
109 *
110 * Return: pointer if the device exists, else NULL
111 */
112struct bootstd_priv *bootstd_try_priv(void);
113
114/**
115 * bootstd_clear_glob() - Clear the global list of bootflows
116 *
117 * This removes all bootflows globally and across all bootdevs.
118 */
119void bootstd_clear_glob(void);
120
121/**
122 * bootstd_prog_boot() - Run standard boot in a fully programmatic mode
123 *
124 * Attempts to boot without making any use of U-Boot commands
125 *
126 * Returns: -ve error value (does not return except on failure to boot)
127 */
128int bootstd_prog_boot(void);
129
130/**
131 * bootstd_add_bootflow() - Add a bootflow to the global list
132 *
133 * All fields in @bflow must be set up. Note that @bflow->dev is used to add the
134 * bootflow to that device.
135 *
136 * The bootflow is also added to the global list of all bootflows
137 *
138 * @dev: Bootdev device to add to
139 * @bflow: Bootflow to add. Note that fields within bflow must be allocated
140 * since this function takes over ownership of these. This functions makes
141 * a copy of @bflow itself (without allocating its fields again), so the
142 * caller must dispose of the memory used by the @bflow pointer itself
143 * Return: element number in the list, if OK, -ENOMEM if out of memory
144 */
145int bootstd_add_bootflow(struct bootflow *bflow);
146
147/**
148 * bootstd_clear_bootflows_for_bootdev() - Clear bootflows from a bootdev
149 *
150 * Each bootdev maintains a list of discovered bootflows. This provides a
151 * way to clear it. These bootflows are removed from the global list too.
152 *
153 * @dev: bootdev device to update
154 */
155int bootstd_clear_bootflows_for_bootdev(struct udevice *dev);
156
157#endif