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  * struct bootmeth_uc_plat - information the uclass keeps about each bootmeth
  17  *
  18  * @desc: A long description of the bootmeth
  19  */
  20 struct bootmeth_uc_plat {
  21         const char *desc;
  22 };
  23
  24 /** struct bootmeth_ops - Operations for boot methods */
  25 struct bootmeth_ops {
  26         /**
  27          * check_supported() - check if a bootmeth supports this bootflow
  28          *
  29          * This is optional. If not provided, the bootdev is assumed to be
  30          * supported
  31          *
  32          * The bootmeth can check the bootdev (e.g. to make sure it is a
  33          * network device) or the partition information. The following fields
  34          * in @iter are available:
  35          *
  36          *   name, dev, state, part
  37          *   max_part may be set if part != 0 (i.e. there is a valid partition
  38          *      table). Otherwise max_part is 0
  39          *   method is available but is the same as @dev
  40          *   the partition has not yet been read, nor has the filesystem been
  41          *   checked
  42          *
  43          * It may update only the flags in @iter
  44          *
  45          * @dev:        Bootmethod device to check against
  46          * @iter:       On entry, provides bootdev, hwpart, part
  47          * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported
  48          */
  49         int (*check)(struct udevice *dev, struct bootflow_iter *iter);
  50
  51         /**
  52          * read_bootflow() - read a bootflow for a device
  53          *
  54          * @dev:        Bootmethod device to use
  55          * @bflow:      On entry, provides dev, hwpart, part and method.
  56          *      Returns updated bootflow if found
  57          * Return: 0 if OK, -ve on error
  58          */
  59         int (*read_bootflow)(struct udevice *dev, struct bootflow *bflow);
  60
  61         /**
  62          * read_file() - read a file needed for a bootflow
  63          *
  64          * Read a file from the same place as the bootflow came from
  65          *
  66          * @dev:        Bootmethod device to use
  67          * @bflow:      Bootflow providing info on where to read from
  68          * @file_path:  Path to file (may be absolute or relative)
  69          * @addr:       Address to load file
  70          * @sizep:      On entry provides the maximum permitted size; on exit
  71          *              returns the size of the file
  72          * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other
  73          *      -ve value if something else goes wrong
  74          */
  75         int (*read_file)(struct udevice *dev, struct bootflow *bflow,
  76                          const char *file_path, ulong addr, ulong *sizep);
  77
  78         /**
  79          * boot() - boot a bootflow
  80          *
  81          * @dev:        Bootmethod device to boot
  82          * @bflow:      Bootflow to boot
  83          * Return: does not return on success, since it should boot the
  84          *      Operating Systemn. Returns -EFAULT if that fails, -ENOTSUPP if
  85          *      trying method resulted in finding out that is not actually
  86          *      supported for this boot and should not be tried again unless
  87          *      something changes, other -ve on other error
  88          */
  89         int (*boot)(struct udevice *dev, struct bootflow *bflow);
  90 };
  91
  92 #define bootmeth_get_ops(dev)  ((struct bootmeth_ops *)(dev)->driver->ops)
  93
  94 /**
  95  * bootmeth_check() - check if a bootmeth supports this bootflow
  96  *
  97  * This is optional. If not provided, the bootdev is assumed to be
  98  * supported
  99  *
 100  * The bootmeth can check the bootdev (e.g. to make sure it is a
 101  * network device) or the partition information. The following fields
 102  * in @iter are available:
 103  *
 104  *   name, dev, state, part
 105  *   max_part may be set if part != 0 (i.e. there is a valid partition
 106  *      table). Otherwise max_part is 0
 107  *   method is available but is the same as @dev
 108  *   the partition has not yet been read, nor has the filesystem been
 109  *   checked
 110  *
 111  * It may update only the flags in @iter
 112  *
 113  * @dev:        Bootmethod device to check against
 114  * @iter:       On entry, provides bootdev, hwpart, part
 115  * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported
 116  */
 117 int bootmeth_check(struct udevice *dev, struct bootflow_iter *iter);
 118
 119 /**
 120  * bootmeth_read_bootflow() - set up a bootflow for a device
 121  *
 122  * @dev:        Bootmethod device to check
 123  * @bflow:      On entry, provides dev, hwpart, part and method.
 124  *      Returns updated bootflow if found
 125  * Return: 0 if OK, -ve on error
 126  */
 127 int bootmeth_read_bootflow(struct udevice *dev, struct bootflow *bflow);
 128
 129 /**
 130  * bootmeth_read_file() - read a file needed for a bootflow
 131  *
 132  * Read a file from the same place as the bootflow came from
 133  *
 134  * @dev:        Bootmethod device to use
 135  * @bflow:      Bootflow providing info on where to read from
 136  * @file_path:  Path to file (may be absolute or relative)
 137  * @addr:       Address to load file
 138  * @sizep:      On entry provides the maximum permitted size; on exit
 139  *              returns the size of the file
 140  * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other
 141  *      -ve value if something else goes wrong
 142  */
 143 int bootmeth_read_file(struct udevice *dev, struct bootflow *bflow,
 144                        const char *file_path, ulong addr, ulong *sizep);
 145
 146 /**
 147  * bootmeth_boot() - boot a bootflow
 148  *
 149  * @dev:        Bootmethod device to boot
 150  * @bflow:      Bootflow to boot
 151  * Return: does not return on success, since it should boot the
 152  *      Operating Systemn. Returns -EFAULT if that fails, other -ve on
 153  *      other error
 154  */
 155 int bootmeth_boot(struct udevice *dev, struct bootflow *bflow);
 156
 157 /**
 158  * bootmeth_setup_iter_order() - Set up the ordering of bootmeths to scan
 159  *
 160  * This sets up the ordering information in @iter, based on the selected
 161  * ordering of the bootmethds in bootstd_priv->bootmeth_order. If there is no
 162  * ordering there, then all bootmethods are added
 163  *
 164  * @iter: Iterator to update with the order
 165  * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve
 166  *      on other error
 167  */
 168 int bootmeth_setup_iter_order(struct bootflow_iter *iter);
 169
 170 /**
 171  * bootmeth_set_order() - Set the bootmeth order
 172  *
 173  * This selects the ordering to use for bootmeths
 174  *
 175  * @order_str: String containing the ordering. This is a comma-separate list of
 176  * bootmeth-device names, e.g. "syslinux,efi". If empty then a default ordering
 177  * is used, based on the sequence number of devices (i.e. using aliases)
 178  * Return: 0 if OK, -ENODEV if an unknown bootmeth is mentioned, -ENOMEM if
 179  * out of memory, -ENOENT if there are no bootmeth devices
 180  */
 181 int bootmeth_set_order(const char *order_str);
 182
 183 /**
 184  * bootmeth_try_file() - See we can access a given file
 185  *
 186  * Check for a file with a given name. If found, the filename is allocated in
 187  * @bflow
 188  *
 189  * Sets the state to BOOTFLOWST_FILE on success. It also calls
 190  * fs_set_blk_dev_with_part() so that this does not need to be done by the
 191  * caller before reading the file.
 192  *
 193  * @bflow: Information about file to try
 194  * @desc: Block descriptor to read from
 195  * @prefix: Filename prefix to prepend to @fname (NULL for none)
 196  * @fname: Filename to read
 197  * Return: 0 if OK, -ENOMEM if not enough memory to allocate bflow->fname,
 198  * other -ve value on other error
 199  */
 200 int bootmeth_try_file(struct bootflow *bflow, struct blk_desc *desc,
 201                       const char *prefix, const char *fname);
 202
 203 /**
 204  * bootmeth_alloc_file() - Allocate and read a bootflow file
 205  *
 206  * Allocates memory for a bootflow file and reads it in. Sets the state to
 207  * BOOTFLOWST_READY on success
 208  *
 209  * Note that fs_set_blk_dev_with_part() must have been called previously.
 210  *
 211  * @bflow: Information about file to read
 212  * @size_limit: Maximum file size to permit
 213  * @align: Allocation alignment (1 for unaligned)
 214  * Return: 0 if OK, -E2BIG if file is too large, -ENOMEM if out of memory,
 215  *      other -ve on other error
 216  */
 217 int bootmeth_alloc_file(struct bootflow *bflow, uint size_limit, uint align);
 218
 219 /**
 220  * bootmeth_common_read_file() - Common handler for reading a file
 221  *
 222  * Reads a named file from the same location as the bootflow file.
 223  *
 224  * @dev: bootmeth device to read from
 225  * @bflow: Bootflow information
 226  * @file_path: Path to file
 227  * @addr: Address to load file to
 228  * @sizep: On entry, the maximum file size to accept, on exit the actual file
 229  *      size read
 230  */
 231 int bootmeth_common_read_file(struct udevice *dev, struct bootflow *bflow,
 232                               const char *file_path, ulong addr, ulong *sizep);
 233
 234 #endif