1 /* SPDX-License-Identifier: GPL-2.0+ */
3 * Copyright 2021 Google LLC
4 * Written by Simon Glass <sjg@chromium.org>
16 * struct bootmeth_uc_plat - information the uclass keeps about each bootmeth
18 * @desc: A long description of the bootmeth
20 struct bootmeth_uc_plat {
24 /** struct bootmeth_ops - Operations for boot methods */
27 * get_state_desc() - get detailed state information
29 * Prodecues a textual description of the state of the bootmeth. This
30 * can include newline characters if it extends to multiple lines. It
31 * must be a nul-terminated string.
33 * This may involve reading state from the system, e.g. some data in
36 * @dev: Bootmethod device to check
37 * @buf: Buffer to place the info in (terminator must fit)
38 * @maxsize: Size of buffer
39 * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if
40 * something else went wrong
42 int (*get_state_desc)(struct udevice *dev, char *buf, int maxsize);
45 * check_supported() - check if a bootmeth supports this bootdev
47 * This is optional. If not provided, the bootdev is assumed to be
50 * The bootmeth can check the bootdev (e.g. to make sure it is a
51 * network device) or the partition information. The following fields
52 * in @iter are available:
54 * name, dev, state, part
55 * max_part may be set if part != 0 (i.e. there is a valid partition
56 * table). Otherwise max_part is 0
57 * method is available but is the same as @dev
58 * the partition has not yet been read, nor has the filesystem been
61 * It may update only the flags in @iter
63 * @dev: Bootmethod device to check against
64 * @iter: On entry, provides bootdev, hwpart, part
65 * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported
67 int (*check)(struct udevice *dev, struct bootflow_iter *iter);
70 * read_bootflow() - read a bootflow for a device
72 * @dev: Bootmethod device to use
73 * @bflow: On entry, provides dev, hwpart, part and method.
74 * Returns updated bootflow if found
75 * Return: 0 if OK, -ve on error
77 int (*read_bootflow)(struct udevice *dev, struct bootflow *bflow);
80 * read_file() - read a file needed for a bootflow
82 * Read a file from the same place as the bootflow came from
84 * @dev: Bootmethod device to use
85 * @bflow: Bootflow providing info on where to read from
86 * @file_path: Path to file (may be absolute or relative)
87 * @addr: Address to load file
88 * @sizep: On entry provides the maximum permitted size; on exit
89 * returns the size of the file
90 * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other
91 * -ve value if something else goes wrong
93 int (*read_file)(struct udevice *dev, struct bootflow *bflow,
94 const char *file_path, ulong addr, ulong *sizep);
97 * boot() - boot a bootflow
99 * @dev: Bootmethod device to boot
100 * @bflow: Bootflow to boot
101 * Return: does not return on success, since it should boot the
102 * Operating Systemn. Returns -EFAULT if that fails, -ENOTSUPP if
103 * trying method resulted in finding out that is not actually
104 * supported for this boot and should not be tried again unless
105 * something changes, other -ve on other error
107 int (*boot)(struct udevice *dev, struct bootflow *bflow);
110 #define bootmeth_get_ops(dev) ((struct bootmeth_ops *)(dev)->driver->ops)
113 * bootmeth_get_state_desc() - get detailed state information
115 * Prodecues a textual description of the state of the bootmeth. This
116 * can include newline characters if it extends to multiple lines. It
117 * must be a nul-terminated string.
119 * This may involve reading state from the system, e.g. some data in
122 * @dev: Bootmethod device to check
123 * @buf: Buffer to place the info in (terminator must fit)
124 * @maxsize: Size of buffer
125 * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if
126 * something else went wrong
128 int bootmeth_get_state_desc(struct udevice *dev, char *buf, int maxsize);
131 * bootmeth_check() - check if a bootmeth supports this bootflow
133 * This is optional. If not provided, the bootdev is assumed to be
136 * The bootmeth can check the bootdev (e.g. to make sure it is a
137 * network device) or the partition information. The following fields
138 * in @iter are available:
140 * name, dev, state, part
141 * max_part may be set if part != 0 (i.e. there is a valid partition
142 * table). Otherwise max_part is 0
143 * method is available but is the same as @dev
144 * the partition has not yet been read, nor has the filesystem been
147 * It may update only the flags in @iter
149 * @dev: Bootmethod device to check against
150 * @iter: On entry, provides bootdev, hwpart, part
151 * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported
153 int bootmeth_check(struct udevice *dev, struct bootflow_iter *iter);
156 * bootmeth_read_bootflow() - set up a bootflow for a device
158 * @dev: Bootmethod device to check
159 * @bflow: On entry, provides dev, hwpart, part and method.
160 * Returns updated bootflow if found
161 * Return: 0 if OK, -ve on error
163 int bootmeth_read_bootflow(struct udevice *dev, struct bootflow *bflow);
166 * bootmeth_read_file() - read a file needed for a bootflow
168 * Read a file from the same place as the bootflow came from
170 * @dev: Bootmethod device to use
171 * @bflow: Bootflow providing info on where to read from
172 * @file_path: Path to file (may be absolute or relative)
173 * @addr: Address to load file
174 * @sizep: On entry provides the maximum permitted size; on exit
175 * returns the size of the file
176 * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other
177 * -ve value if something else goes wrong
179 int bootmeth_read_file(struct udevice *dev, struct bootflow *bflow,
180 const char *file_path, ulong addr, ulong *sizep);
183 * bootmeth_boot() - boot a bootflow
185 * @dev: Bootmethod device to boot
186 * @bflow: Bootflow to boot
187 * Return: does not return on success, since it should boot the
188 * Operating Systemn. Returns -EFAULT if that fails, other -ve on
191 int bootmeth_boot(struct udevice *dev, struct bootflow *bflow);
194 * bootmeth_setup_iter_order() - Set up the ordering of bootmeths to scan
196 * This sets up the ordering information in @iter, based on the selected
197 * ordering of the bootmethds in bootstd_priv->bootmeth_order. If there is no
198 * ordering there, then all bootmethods are added
200 * @iter: Iterator to update with the order
201 * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve
204 int bootmeth_setup_iter_order(struct bootflow_iter *iter);
207 * bootmeth_set_order() - Set the bootmeth order
209 * This selects the ordering to use for bootmeths
211 * @order_str: String containing the ordering. This is a comma-separate list of
212 * bootmeth-device names, e.g. "syslinux,efi". If empty then a default ordering
213 * is used, based on the sequence number of devices (i.e. using aliases)
214 * Return: 0 if OK, -ENODEV if an unknown bootmeth is mentioned, -ENOMEM if
215 * out of memory, -ENOENT if there are no bootmeth devices
217 int bootmeth_set_order(const char *order_str);
220 * bootmeth_try_file() - See we can access a given file
222 * Check for a file with a given name. If found, the filename is allocated in
225 * Sets the state to BOOTFLOWST_FILE on success. It also calls
226 * fs_set_blk_dev_with_part() so that this does not need to be done by the
227 * caller before reading the file.
229 * @bflow: Information about file to try
230 * @desc: Block descriptor to read from
231 * @prefix: Filename prefix to prepend to @fname (NULL for none)
232 * @fname: Filename to read
233 * Return: 0 if OK, -ENOMEM if not enough memory to allocate bflow->fname,
234 * other -ve value on other error
236 int bootmeth_try_file(struct bootflow *bflow, struct blk_desc *desc,
237 const char *prefix, const char *fname);
240 * bootmeth_alloc_file() - Allocate and read a bootflow file
242 * Allocates memory for a bootflow file and reads it in. Sets the state to
243 * BOOTFLOWST_READY on success
245 * Note that fs_set_blk_dev_with_part() must have been called previously.
247 * @bflow: Information about file to read
248 * @size_limit: Maximum file size to permit
249 * @align: Allocation alignment (1 for unaligned)
250 * Return: 0 if OK, -E2BIG if file is too large, -ENOMEM if out of memory,
251 * other -ve on other error
253 int bootmeth_alloc_file(struct bootflow *bflow, uint size_limit, uint align);
256 * bootmeth_common_read_file() - Common handler for reading a file
258 * Reads a named file from the same location as the bootflow file.
260 * @dev: bootmeth device to read from
261 * @bflow: Bootflow information
262 * @file_path: Path to file
263 * @addr: Address to load file to
264 * @sizep: On entry, the maximum file size to accept, on exit the actual file
267 int bootmeth_common_read_file(struct udevice *dev, struct bootflow *bflow,
268 const char *file_path, ulong addr, ulong *sizep);