include/bootmeth.h

   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 /**
  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 /**
  25  * struct bootmeth_uc_plat - information the uclass keeps about each bootmeth
  26  *
  27  * @desc: A long description of the bootmeth
  28  * @flags: Flags for this bootmeth (enum bootmeth_flags)
  29  */
  30 struct bootmeth_uc_plat {
  31         const char *desc;
  32         int flags;
  33 };
  34
  35 /** struct bootmeth_ops - Operations for boot methods */
  36 struct bootmeth_ops {
  37         /**
  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
  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         /**
  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         /**
 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 /**
 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 /**
 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 /**
 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 /**
 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
 245  * @include_global: true to add the global bootmeths, in which case they appear
 246  * first
 247  * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve
 248  *      on other error
 249  */
 250 int bootmeth_setup_iter_order(struct bootflow_iter *iter, bool include_global);
 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
 258  * bootmeth-device names, e.g. "extlinux,efi". If empty then a default ordering
 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 /**
 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 /**
 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
 289  * @desc: Block descriptor to read from (NULL for sandbox host)
 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 /**
 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 /**
 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
 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
 357 #endif