include/bootflow.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 __bootflow_h
   8 #define __bootflow_h
   9
  10 #include <linux/list.h>
  11
  12 /**
  13  * enum bootflow_state_t - states that a particular bootflow can be in
  14  *
  15  * Only bootflows in state BOOTFLOWST_READY can be used to boot.
  16  *
  17  * See bootflow_state[] for the names for each of these
  18  */
  19 enum bootflow_state_t {
  20         BOOTFLOWST_BASE,        /**< Nothing known yet */
  21         BOOTFLOWST_MEDIA,       /**< Media exists */
  22         BOOTFLOWST_PART,        /**< Partition exists */
  23         BOOTFLOWST_FS,          /**< Filesystem exists */
  24         BOOTFLOWST_FILE,        /**< Bootflow file exists */
  25         BOOTFLOWST_READY,       /**< Bootflow file loaded */
  26
  27         BOOTFLOWST_COUNT
  28 };
  29
  30 /**
  31  * struct bootflow - information about a bootflow
  32  *
  33  * This is connected into two separate linked lists:
  34  *
  35  *   bm_sibling - links all bootflows in the same bootdev
  36  *   glob_sibling - links all bootflows in all bootdevs
  37  *
  38  * @bm_node: Points to siblings in the same bootdev
  39  * @glob_node: Points to siblings in the global list (all bootdev)
  40  * @dev: Bootdevice device which produced this bootflow
  41  * @blk: Block device which contains this bootflow, NULL if this is a network
  42  *      device
  43  * @part: Partition number (0 for whole device)
  44  * @fs_type: Filesystem type (FS_TYPE...) if this is fixed by the media, else 0.
  45  *      For example, the sandbox host-filesystem bootdev sets this to
  46  *      FS_TYPE_SANDBOX
  47  * @method: Bootmethod device used to perform the boot and read files
  48  * @name: Name of bootflow (allocated)
  49  * @state: Current state (enum bootflow_state_t)
  50  * @subdir: Subdirectory to fetch files from (with trailing /), or NULL if none
  51  * @fname: Filename of bootflow file (allocated)
  52  * @buf: Bootflow file contents (allocated)
  53  * @size: Size of bootflow file in bytes
  54  * @err: Error number received (0 if OK)
  55  */
  56 struct bootflow {
  57         struct list_head bm_node;
  58         struct list_head glob_node;
  59         struct udevice *dev;
  60         struct udevice *blk;
  61         int part;
  62         int fs_type;
  63         struct udevice *method;
  64         char *name;
  65         enum bootflow_state_t state;
  66         char *subdir;
  67         char *fname;
  68         char *buf;
  69         int size;
  70         int err;
  71 };
  72
  73 /**
  74  * enum bootflow_flags_t - flags for the bootflow iterator
  75  *
  76  * @BOOTFLOWF_FIXED: Only used fixed/internal media
  77  * @BOOTFLOWF_SHOW: Show each bootdev before scanning it
  78  * @BOOTFLOWF_ALL: Return bootflows with errors as well
  79  * @BOOTFLOWF_SINGLE_DEV: Just scan one bootmeth
  80  * @BOOTFLOWF_SKIP_GLOBAL: Don't scan global bootmeths
  81  */
  82 enum bootflow_flags_t {
  83         BOOTFLOWF_FIXED         = 1 << 0,
  84         BOOTFLOWF_SHOW          = 1 << 1,
  85         BOOTFLOWF_ALL           = 1 << 2,
  86         BOOTFLOWF_SINGLE_DEV    = 1 << 3,
  87         BOOTFLOWF_SKIP_GLOBAL   = 1 << 4,
  88 };
  89
  90 /**
  91  * struct bootflow_iter - state for iterating through bootflows
  92  *
  93  * This starts at with the first bootdev/partition/bootmeth and can be used to
  94  * iterate through all of them.
  95  *
  96  * Iteration starts with the bootdev. The first partition (0, i.e. whole device)
  97  * is scanned first. For partition 0, it iterates through all the available
  98  * bootmeths to see which one(s) can provide a bootflow. Then it moves to
  99  * parition 1 (if there is one) and the process continues. Once all partitions
 100  * are examined, it moves to the next bootdev.
 101  *
 102  * Initially @max_part is 0, meaning that only the whole device (@part=0) can be
 103  * used. During scanning, if a partition table is found, then @max_part is
 104  * updated to a larger value, no less than the number of available partitions.
 105  * This ensures that iteration works through all partitions on the bootdev.
 106  *
 107  * @flags: Flags to use (see enum bootflow_flags_t). If BOOTFLOWF_GLOBAL_FIRST is
 108  *      enabled then the global bootmeths are being scanned, otherwise we have
 109  *      moved onto the bootdevs
 110  * @dev: Current bootdev, NULL if none
 111  * @part: Current partition number (0 for whole device)
 112  * @method: Current bootmeth
 113  * @max_part: Maximum hardware partition number in @dev, 0 if there is no
 114  *      partition table
 115  * @err: Error obtained from checking the last iteration. This is used to skip
 116  *      forward (e.g. to skip the current partition because it is not valid)
 117  *      -ESHUTDOWN: try next bootdev
 118  * @num_devs: Number of bootdevs in @dev_order
 119  * @cur_dev: Current bootdev number, an index into @dev_order[]
 120  * @dev_order: List of bootdevs to scan, in order of priority. The scan starts
 121  *      with the first one on the list
 122  * @num_methods: Number of bootmeth devices in @method_order
 123  * @cur_method: Current method number, an index into @method_order
 124  * @first_glob_method: First global method, if any, else -1
 125  * @method_order: List of bootmeth devices to use, in order. The normal methods
 126  *      appear first, then the global ones, if any
 127  * @doing_global: true if we are iterating through the global bootmeths (which
 128  *      happens before the normal ones)
 129  */
 130 struct bootflow_iter {
 131         int flags;
 132         struct udevice *dev;
 133         int part;
 134         struct udevice *method;
 135         int max_part;
 136         int err;
 137         int num_devs;
 138         int cur_dev;
 139         struct udevice **dev_order;
 140         int num_methods;
 141         int cur_method;
 142         int first_glob_method;
 143         struct udevice **method_order;
 144         bool doing_global;
 145 };
 146
 147 /**
 148  * bootflow_init() - Set up a bootflow struct
 149  *
 150  * The bootflow is zeroed and set to state BOOTFLOWST_BASE
 151  *
 152  * @bflow: Struct to set up
 153  * @bootdev: Bootdev to use
 154  * @meth: Bootmeth to use
 155  */
 156 void bootflow_init(struct bootflow *bflow, struct udevice *bootdev,
 157                    struct udevice *meth);
 158
 159 /**
 160  * bootflow_iter_init() - Reset a bootflow iterator
 161  *
 162  * This sets everything to the starting point, ready for use.
 163  *
 164  * @iter: Place to store private info (inited by this call)
 165  * @flags: Flags to use (see enum bootflow_flags_t)
 166  */
 167 void bootflow_iter_init(struct bootflow_iter *iter, int flags);
 168
 169 /**
 170  * bootflow_iter_uninit() - Free memory used by an interator
 171  *
 172  * @iter:       Iterator to free
 173  */
 174 void bootflow_iter_uninit(struct bootflow_iter *iter);
 175
 176 /**
 177  * bootflow_iter_drop_bootmeth() - Remove a bootmeth from an iterator
 178  *
 179  * Update the iterator so that the bootmeth will not be used again while this
 180  * iterator is in use
 181  *
 182  * @iter: Iterator to update
 183  * @bmeth: Boot method to remove
 184  */
 185 int bootflow_iter_drop_bootmeth(struct bootflow_iter *iter,
 186                                 const struct udevice *bmeth);
 187
 188 /**
 189  * bootflow_scan_bootdev() - find the first bootflow in a bootdev
 190  *
 191  * If @flags includes BOOTFLOWF_ALL then bootflows with errors are returned too
 192  *
 193  * @dev:        Boot device to scan, NULL to work through all of them until it
 194  *      finds one that can supply a bootflow
 195  * @iter:       Place to store private info (inited by this call)
 196  * @flags:      Flags for iterator (enum bootflow_flags_t)
 197  * @bflow:      Place to put the bootflow if found
 198  * Return: 0 if found,  -ENODEV if no device, other -ve on other error
 199  *      (iteration can continue)
 200  */
 201 int bootflow_scan_bootdev(struct udevice *dev, struct bootflow_iter *iter,
 202                           int flags, struct bootflow *bflow);
 203
 204 /**
 205  * bootflow_scan_first() - find the first bootflow
 206  *
 207  * This works through the available bootdev devices until it finds one that
 208  * can supply a bootflow. It then returns that
 209  *
 210  * If @flags includes BOOTFLOWF_ALL then bootflows with errors are returned too
 211  *
 212  * @iter:       Place to store private info (inited by this call), with
 213  * @flags:      Flags for bootdev (enum bootflow_flags_t)
 214  * @bflow:      Place to put the bootflow if found
 215  * Return: 0 if found, -ENODEV if no device, other -ve on other error (iteration
 216  *      can continue)
 217  */
 218 int bootflow_scan_first(struct bootflow_iter *iter, int flags,
 219                         struct bootflow *bflow);
 220
 221 /**
 222  * bootflow_scan_next() - find the next bootflow
 223  *
 224  * This works through the available bootdev devices until it finds one that
 225  * can supply a bootflow. It then returns that bootflow
 226  *
 227  * @iter:       Private info (as set up by bootflow_scan_first())
 228  * @bflow:      Place to put the bootflow if found
 229  * Return: 0 if found, -ENODEV if no device, -ESHUTDOWN if no more bootflows,
 230  *      other -ve on other error (iteration can continue)
 231  */
 232 int bootflow_scan_next(struct bootflow_iter *iter, struct bootflow *bflow);
 233
 234 /**
 235  * bootflow_first_glob() - Get the first bootflow from the global list
 236  *
 237  * Returns the first bootflow in the global list, no matter what bootflow it is
 238  * attached to
 239  *
 240  * @bflowp: Returns a pointer to the bootflow
 241  * Return: 0 if found, -ENOENT if there are no bootflows
 242  */
 243 int bootflow_first_glob(struct bootflow **bflowp);
 244
 245 /**
 246  * bootflow_next_glob() - Get the next bootflow from the global list
 247  *
 248  * Returns the next bootflow in the global list, no matter what bootflow it is
 249  * attached to
 250  *
 251  * @bflowp: On entry, the last bootflow returned , e.g. from
 252  *      bootflow_first_glob()
 253  * Return: 0 if found, -ENOENT if there are no more bootflows
 254  */
 255 int bootflow_next_glob(struct bootflow **bflowp);
 256
 257 /**
 258  * bootflow_free() - Free memory used by a bootflow
 259  *
 260  * This frees fields within @bflow, but not the @bflow pointer itself
 261  */
 262 void bootflow_free(struct bootflow *bflow);
 263
 264 /**
 265  * bootflow_boot() - boot a bootflow
 266  *
 267  * @bflow: Bootflow to boot
 268  * Return: -EPROTO if bootflow has not been loaded, -ENOSYS if the bootflow
 269  *      type is not supported, -EFAULT if the boot returned without an error
 270  *      when we are expecting it to boot, -ENOTSUPP if trying method resulted in
 271  *      finding out that is not actually supported for this boot and should not
 272  *      be tried again unless something changes
 273  */
 274 int bootflow_boot(struct bootflow *bflow);
 275
 276 /**
 277  * bootflow_run_boot() - Try to boot a bootflow
 278  *
 279  * @iter: Current iteration (or NULL if none). Used to disable a bootmeth if the
 280  *      boot returns -ENOTSUPP
 281  * @bflow: Bootflow to boot
 282  * Return: result of trying to boot
 283  */
 284 int bootflow_run_boot(struct bootflow_iter *iter, struct bootflow *bflow);
 285
 286 /**
 287  * bootflow_state_get_name() - Get the name of a bootflow state
 288  *
 289  * @state: State to check
 290  * Return: name, or "?" if invalid
 291  */
 292 const char *bootflow_state_get_name(enum bootflow_state_t state);
 293
 294 /**
 295  * bootflow_remove() - Remove a bootflow and free its memory
 296  *
 297  * This updates the linked lists containing the bootflow then frees it.
 298  *
 299  * @bflow: Bootflow to remove
 300  */
 301 void bootflow_remove(struct bootflow *bflow);
 302
 303 /**
 304  * bootflow_iter_uses_blk_dev() - Check that a bootflow uses a block device
 305  *
 306  * This checks the bootdev in the bootflow to make sure it uses a block device
 307  *
 308  * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. ethernet)
 309  */
 310 int bootflow_iter_uses_blk_dev(const struct bootflow_iter *iter);
 311
 312 /**
 313  * bootflow_iter_uses_network() - Check that a bootflow uses a network device
 314  *
 315  * This checks the bootdev in the bootflow to make sure it uses a network
 316  * device
 317  *
 318  * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC)
 319  */
 320 int bootflow_iter_uses_network(const struct bootflow_iter *iter);
 321
 322 /**
 323  * bootflow_iter_uses_system() - Check that a bootflow uses the bootstd device
 324  *
 325  * This checks the bootdev in the bootflow to make sure it uses the bootstd
 326  * device
 327  *
 328  * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC)
 329  */
 330 int bootflow_iter_uses_system(const struct bootflow_iter *iter);
 331
 332 #endif