include/bootmeth.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Copyright 2021 Google LLC
   4  * Written by Simon Glass <[email protected]>
   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 /**
  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  */
  22 enum 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  */
  33 struct bootmeth_uc_plat {
  34         const char *desc;
  35         int flags;
  36 };
  37
  38 /** struct bootmeth_ops - Operations for boot methods */
  39 struct 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  */
 167 int 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  */
 192 int 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  */
 202 int 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  */
 218 int 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  */
 235 int 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  */
 250 int 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  */
 261 int 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  */
 276 int 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  */
 289 int 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  */
 302 int 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  */
 321 int 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  */
 338 int 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  */
 353 int 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  */
 368 int 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  */
 381 int bootmeth_get_bootflow(struct udevice *dev, struct bootflow *bflow);
 382
 383 #endif