Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
| 2 | /* |
| 3 | * Copyright 2021 Google LLC |
| 4 | * Written by Simon Glass <sjg@chromium.org> |
| 5 | */ |
| 6 | |
| 7 | #ifndef __bootmeth_h |
| 8 | #define __bootmeth_h |
| 9 | |
| 10 | struct blk_desc; |
| 11 | struct bootflow; |
| 12 | struct bootflow_iter; |
| 13 | struct udevice; |
| 14 | |
| 15 | /** |
Simon Glass | 4f8633d | 2022-07-30 15:52:21 -0600 | [diff] [blame] | 16 | * enum bootmeth_flags - Flags for bootmeths |
| 17 | * |
| 18 | * @BOOTMETHF_GLOBAL: bootmeth handles bootdev selection automatically |
| 19 | */ |
| 20 | enum bootmeth_flags { |
| 21 | BOOTMETHF_GLOBAL = BIT(0), |
| 22 | }; |
| 23 | |
| 24 | /** |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 25 | * struct bootmeth_uc_plat - information the uclass keeps about each bootmeth |
| 26 | * |
| 27 | * @desc: A long description of the bootmeth |
Simon Glass | 4f8633d | 2022-07-30 15:52:21 -0600 | [diff] [blame] | 28 | * @flags: Flags for this bootmeth (enum bootmeth_flags) |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 29 | */ |
| 30 | struct bootmeth_uc_plat { |
| 31 | const char *desc; |
Simon Glass | 4f8633d | 2022-07-30 15:52:21 -0600 | [diff] [blame] | 32 | int flags; |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 33 | }; |
| 34 | |
| 35 | /** struct bootmeth_ops - Operations for boot methods */ |
| 36 | struct bootmeth_ops { |
| 37 | /** |
Simon Glass | f6d71a8 | 2022-07-30 15:52:19 -0600 | [diff] [blame] | 38 | * get_state_desc() - get detailed state information |
| 39 | * |
| 40 | * Prodecues a textual description of the state of the bootmeth. This |
| 41 | * can include newline characters if it extends to multiple lines. It |
| 42 | * must be a nul-terminated string. |
| 43 | * |
| 44 | * This may involve reading state from the system, e.g. some data in |
| 45 | * the firmware area. |
| 46 | * |
| 47 | * @dev: Bootmethod device to check |
| 48 | * @buf: Buffer to place the info in (terminator must fit) |
| 49 | * @maxsize: Size of buffer |
| 50 | * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if |
| 51 | * something else went wrong |
| 52 | */ |
| 53 | int (*get_state_desc)(struct udevice *dev, char *buf, int maxsize); |
| 54 | |
| 55 | /** |
| 56 | * check_supported() - check if a bootmeth supports this bootdev |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 57 | * |
| 58 | * This is optional. If not provided, the bootdev is assumed to be |
| 59 | * supported |
| 60 | * |
| 61 | * The bootmeth can check the bootdev (e.g. to make sure it is a |
| 62 | * network device) or the partition information. The following fields |
| 63 | * in @iter are available: |
| 64 | * |
| 65 | * name, dev, state, part |
| 66 | * max_part may be set if part != 0 (i.e. there is a valid partition |
| 67 | * table). Otherwise max_part is 0 |
| 68 | * method is available but is the same as @dev |
| 69 | * the partition has not yet been read, nor has the filesystem been |
| 70 | * checked |
| 71 | * |
| 72 | * It may update only the flags in @iter |
| 73 | * |
| 74 | * @dev: Bootmethod device to check against |
| 75 | * @iter: On entry, provides bootdev, hwpart, part |
| 76 | * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported |
| 77 | */ |
| 78 | int (*check)(struct udevice *dev, struct bootflow_iter *iter); |
| 79 | |
| 80 | /** |
| 81 | * read_bootflow() - read a bootflow for a device |
| 82 | * |
| 83 | * @dev: Bootmethod device to use |
| 84 | * @bflow: On entry, provides dev, hwpart, part and method. |
| 85 | * Returns updated bootflow if found |
| 86 | * Return: 0 if OK, -ve on error |
| 87 | */ |
| 88 | int (*read_bootflow)(struct udevice *dev, struct bootflow *bflow); |
| 89 | |
| 90 | /** |
Simon Glass | a63bda6 | 2023-01-17 10:48:01 -0700 | [diff] [blame] | 91 | * set_bootflow() - set the bootflow for a device |
| 92 | * |
| 93 | * This provides a bootflow file to the bootmeth, to see if it is valid. |
| 94 | * If it is, the bootflow is set up accordingly. |
| 95 | * |
| 96 | * @dev: Bootmethod device to use |
| 97 | * @bflow: On entry, provides bootdev. |
| 98 | * Returns updated bootflow if found |
| 99 | * @buf: Buffer containing the possible bootflow file |
| 100 | * @size: Size of file |
| 101 | * Return: 0 if OK, -ve on error |
| 102 | */ |
| 103 | int (*set_bootflow)(struct udevice *dev, struct bootflow *bflow, |
| 104 | char *buf, int size); |
| 105 | |
| 106 | /** |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 107 | * read_file() - read a file needed for a bootflow |
| 108 | * |
| 109 | * Read a file from the same place as the bootflow came from |
| 110 | * |
| 111 | * @dev: Bootmethod device to use |
| 112 | * @bflow: Bootflow providing info on where to read from |
| 113 | * @file_path: Path to file (may be absolute or relative) |
| 114 | * @addr: Address to load file |
| 115 | * @sizep: On entry provides the maximum permitted size; on exit |
| 116 | * returns the size of the file |
| 117 | * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other |
| 118 | * -ve value if something else goes wrong |
| 119 | */ |
| 120 | int (*read_file)(struct udevice *dev, struct bootflow *bflow, |
| 121 | const char *file_path, ulong addr, ulong *sizep); |
| 122 | |
| 123 | /** |
| 124 | * boot() - boot a bootflow |
| 125 | * |
| 126 | * @dev: Bootmethod device to boot |
| 127 | * @bflow: Bootflow to boot |
| 128 | * Return: does not return on success, since it should boot the |
| 129 | * Operating Systemn. Returns -EFAULT if that fails, -ENOTSUPP if |
| 130 | * trying method resulted in finding out that is not actually |
| 131 | * supported for this boot and should not be tried again unless |
| 132 | * something changes, other -ve on other error |
| 133 | */ |
| 134 | int (*boot)(struct udevice *dev, struct bootflow *bflow); |
| 135 | }; |
| 136 | |
| 137 | #define bootmeth_get_ops(dev) ((struct bootmeth_ops *)(dev)->driver->ops) |
| 138 | |
| 139 | /** |
Simon Glass | f6d71a8 | 2022-07-30 15:52:19 -0600 | [diff] [blame] | 140 | * bootmeth_get_state_desc() - get detailed state information |
| 141 | * |
| 142 | * Prodecues a textual description of the state of the bootmeth. This |
| 143 | * can include newline characters if it extends to multiple lines. It |
| 144 | * must be a nul-terminated string. |
| 145 | * |
| 146 | * This may involve reading state from the system, e.g. some data in |
| 147 | * the firmware area. |
| 148 | * |
| 149 | * @dev: Bootmethod device to check |
| 150 | * @buf: Buffer to place the info in (terminator must fit) |
| 151 | * @maxsize: Size of buffer |
| 152 | * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if |
| 153 | * something else went wrong |
| 154 | */ |
| 155 | int bootmeth_get_state_desc(struct udevice *dev, char *buf, int maxsize); |
| 156 | |
| 157 | /** |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 158 | * bootmeth_check() - check if a bootmeth supports this bootflow |
| 159 | * |
| 160 | * This is optional. If not provided, the bootdev is assumed to be |
| 161 | * supported |
| 162 | * |
| 163 | * The bootmeth can check the bootdev (e.g. to make sure it is a |
| 164 | * network device) or the partition information. The following fields |
| 165 | * in @iter are available: |
| 166 | * |
| 167 | * name, dev, state, part |
| 168 | * max_part may be set if part != 0 (i.e. there is a valid partition |
| 169 | * table). Otherwise max_part is 0 |
| 170 | * method is available but is the same as @dev |
| 171 | * the partition has not yet been read, nor has the filesystem been |
| 172 | * checked |
| 173 | * |
| 174 | * It may update only the flags in @iter |
| 175 | * |
| 176 | * @dev: Bootmethod device to check against |
| 177 | * @iter: On entry, provides bootdev, hwpart, part |
| 178 | * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported |
| 179 | */ |
| 180 | int bootmeth_check(struct udevice *dev, struct bootflow_iter *iter); |
| 181 | |
| 182 | /** |
| 183 | * bootmeth_read_bootflow() - set up a bootflow for a device |
| 184 | * |
| 185 | * @dev: Bootmethod device to check |
| 186 | * @bflow: On entry, provides dev, hwpart, part and method. |
| 187 | * Returns updated bootflow if found |
| 188 | * Return: 0 if OK, -ve on error |
| 189 | */ |
| 190 | int bootmeth_read_bootflow(struct udevice *dev, struct bootflow *bflow); |
| 191 | |
| 192 | /** |
Simon Glass | a63bda6 | 2023-01-17 10:48:01 -0700 | [diff] [blame] | 193 | * bootmeth_set_bootflow() - set the bootflow for a device |
| 194 | * |
| 195 | * This provides a bootflow file to the bootmeth, to see if it is valid. |
| 196 | * If it is, the bootflow is set up accordingly. |
| 197 | * |
| 198 | * @dev: Bootmethod device to use |
| 199 | * @bflow: On entry, provides bootdev. |
| 200 | * Returns updated bootflow if found |
| 201 | * @buf: Buffer containing the possible bootflow file (must be allocated |
| 202 | * by caller to @size + 1 bytes) |
| 203 | * @size: Size of file |
| 204 | * Return: 0 if OK, -ve on error |
| 205 | */ |
| 206 | int bootmeth_set_bootflow(struct udevice *dev, struct bootflow *bflow, |
| 207 | char *buf, int size); |
| 208 | |
| 209 | /** |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 210 | * bootmeth_read_file() - read a file needed for a bootflow |
| 211 | * |
| 212 | * Read a file from the same place as the bootflow came from |
| 213 | * |
| 214 | * @dev: Bootmethod device to use |
| 215 | * @bflow: Bootflow providing info on where to read from |
| 216 | * @file_path: Path to file (may be absolute or relative) |
| 217 | * @addr: Address to load file |
| 218 | * @sizep: On entry provides the maximum permitted size; on exit |
| 219 | * returns the size of the file |
| 220 | * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other |
| 221 | * -ve value if something else goes wrong |
| 222 | */ |
| 223 | int bootmeth_read_file(struct udevice *dev, struct bootflow *bflow, |
| 224 | const char *file_path, ulong addr, ulong *sizep); |
| 225 | |
| 226 | /** |
| 227 | * bootmeth_boot() - boot a bootflow |
| 228 | * |
| 229 | * @dev: Bootmethod device to boot |
| 230 | * @bflow: Bootflow to boot |
| 231 | * Return: does not return on success, since it should boot the |
| 232 | * Operating Systemn. Returns -EFAULT if that fails, other -ve on |
| 233 | * other error |
| 234 | */ |
| 235 | int bootmeth_boot(struct udevice *dev, struct bootflow *bflow); |
| 236 | |
| 237 | /** |
| 238 | * bootmeth_setup_iter_order() - Set up the ordering of bootmeths to scan |
| 239 | * |
| 240 | * This sets up the ordering information in @iter, based on the selected |
| 241 | * ordering of the bootmethds in bootstd_priv->bootmeth_order. If there is no |
| 242 | * ordering there, then all bootmethods are added |
| 243 | * |
| 244 | * @iter: Iterator to update with the order |
Simon Glass | cc15e14 | 2022-07-30 15:52:27 -0600 | [diff] [blame] | 245 | * @include_global: true to add the global bootmeths, in which case they appear |
| 246 | * first |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 247 | * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve |
| 248 | * on other error |
| 249 | */ |
Simon Glass | cc15e14 | 2022-07-30 15:52:27 -0600 | [diff] [blame] | 250 | int bootmeth_setup_iter_order(struct bootflow_iter *iter, bool include_global); |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 251 | |
| 252 | /** |
| 253 | * bootmeth_set_order() - Set the bootmeth order |
| 254 | * |
| 255 | * This selects the ordering to use for bootmeths |
| 256 | * |
| 257 | * @order_str: String containing the ordering. This is a comma-separate list of |
Simon Glass | b71d7f7 | 2023-05-10 16:34:46 -0600 | [diff] [blame] | 258 | * bootmeth-device names, e.g. "extlinux,efi". If empty then a default ordering |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 259 | * is used, based on the sequence number of devices (i.e. using aliases) |
| 260 | * Return: 0 if OK, -ENODEV if an unknown bootmeth is mentioned, -ENOMEM if |
| 261 | * out of memory, -ENOENT if there are no bootmeth devices |
| 262 | */ |
| 263 | int bootmeth_set_order(const char *order_str); |
| 264 | |
| 265 | /** |
Simon Glass | f41c445 | 2023-07-26 21:01:21 -0600 | [diff] [blame] | 266 | * bootmeth_setup_fs() - Set up read to read a file |
| 267 | * |
| 268 | * We must redo the setup before each filesystem operation. This function |
| 269 | * handles that, including setting the filesystem type if a block device is not |
| 270 | * being used |
| 271 | * |
| 272 | * @bflow: Information about file to try |
| 273 | * @desc: Block descriptor to read from (NULL if not a block device) |
| 274 | * Return: 0 if OK, -ve on error |
| 275 | */ |
| 276 | int bootmeth_setup_fs(struct bootflow *bflow, struct blk_desc *desc); |
| 277 | |
| 278 | /** |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 279 | * bootmeth_try_file() - See we can access a given file |
| 280 | * |
| 281 | * Check for a file with a given name. If found, the filename is allocated in |
| 282 | * @bflow |
| 283 | * |
| 284 | * Sets the state to BOOTFLOWST_FILE on success. It also calls |
| 285 | * fs_set_blk_dev_with_part() so that this does not need to be done by the |
| 286 | * caller before reading the file. |
| 287 | * |
| 288 | * @bflow: Information about file to try |
Simon Glass | 4adeeb8 | 2023-01-17 10:47:59 -0700 | [diff] [blame] | 289 | * @desc: Block descriptor to read from (NULL for sandbox host) |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 290 | * @prefix: Filename prefix to prepend to @fname (NULL for none) |
| 291 | * @fname: Filename to read |
| 292 | * Return: 0 if OK, -ENOMEM if not enough memory to allocate bflow->fname, |
| 293 | * other -ve value on other error |
| 294 | */ |
| 295 | int bootmeth_try_file(struct bootflow *bflow, struct blk_desc *desc, |
| 296 | const char *prefix, const char *fname); |
| 297 | |
| 298 | /** |
| 299 | * bootmeth_alloc_file() - Allocate and read a bootflow file |
| 300 | * |
| 301 | * Allocates memory for a bootflow file and reads it in. Sets the state to |
| 302 | * BOOTFLOWST_READY on success |
| 303 | * |
| 304 | * Note that fs_set_blk_dev_with_part() must have been called previously. |
| 305 | * |
| 306 | * @bflow: Information about file to read |
| 307 | * @size_limit: Maximum file size to permit |
| 308 | * @align: Allocation alignment (1 for unaligned) |
| 309 | * Return: 0 if OK, -E2BIG if file is too large, -ENOMEM if out of memory, |
| 310 | * other -ve on other error |
| 311 | */ |
| 312 | int bootmeth_alloc_file(struct bootflow *bflow, uint size_limit, uint align); |
| 313 | |
| 314 | /** |
Simon Glass | 612b9cc | 2023-01-06 08:52:34 -0600 | [diff] [blame] | 315 | * bootmeth_alloc_other() - Allocate and read a file for a bootflow |
| 316 | * |
| 317 | * This reads an arbitrary file in the same directory as the bootflow, |
| 318 | * allocating memory for it. The buffer is one byte larger than the file length, |
| 319 | * so that it can be nul-terminated. |
| 320 | * |
| 321 | * @bflow: Information about file to read |
| 322 | * @fname: Filename to read from (within bootflow->subdir) |
| 323 | * @bufp: Returns a pointer to the allocated buffer |
| 324 | * @sizep: Returns the size of the buffer |
| 325 | * Return: 0 if OK, -ENOMEM if out of memory, other -ve on other error |
| 326 | */ |
| 327 | int bootmeth_alloc_other(struct bootflow *bflow, const char *fname, |
| 328 | void **bufp, uint *sizep); |
| 329 | |
| 330 | /** |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 331 | * bootmeth_common_read_file() - Common handler for reading a file |
| 332 | * |
| 333 | * Reads a named file from the same location as the bootflow file. |
| 334 | * |
| 335 | * @dev: bootmeth device to read from |
| 336 | * @bflow: Bootflow information |
| 337 | * @file_path: Path to file |
| 338 | * @addr: Address to load file to |
| 339 | * @sizep: On entry, the maximum file size to accept, on exit the actual file |
| 340 | * size read |
| 341 | */ |
| 342 | int bootmeth_common_read_file(struct udevice *dev, struct bootflow *bflow, |
| 343 | const char *file_path, ulong addr, ulong *sizep); |
| 344 | |
Simon Glass | 4f8633d | 2022-07-30 15:52:21 -0600 | [diff] [blame] | 345 | /** |
| 346 | * bootmeth_get_bootflow() - Get a bootflow from a global bootmeth |
| 347 | * |
| 348 | * Check the bootmeth for a bootflow which can be used. In this case the |
| 349 | * bootmeth handles all bootdev selection, etc. |
| 350 | * |
| 351 | * @dev: bootmeth device to read from |
| 352 | * @bflow: Bootflow information |
| 353 | * @return 0 on success, -ve if a bootflow could not be found or had an error |
| 354 | */ |
| 355 | int bootmeth_get_bootflow(struct udevice *dev, struct bootflow *bflow); |
| 356 | |
Simon Glass | 4b508b8 | 2022-04-24 23:31:08 -0600 | [diff] [blame] | 357 | #endif |