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