bootflow.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Copyright 2021 Google LLC
  4. * Written by Simon Glass <sjg@chromium.org>
  5. */
  6. #ifndef __bootflow_h
  7. #define __bootflow_h
  8. #include <bootdev.h>
  9. #include <dm/ofnode_decl.h>
  10. #include <linux/list.h>
  11. struct bootstd_priv;
  12. struct expo;
  13. enum {
  14. BOOTFLOW_MAX_USED_DEVS = 16,
  15. };
  16. /**
  17. * enum bootflow_state_t - states that a particular bootflow can be in
  18. *
  19. * Only bootflows in state BOOTFLOWST_READY can be used to boot.
  20. *
  21. * See bootflow_state[] for the names for each of these
  22. */
  23. enum bootflow_state_t {
  24. BOOTFLOWST_BASE, /**< Nothing known yet */
  25. BOOTFLOWST_MEDIA, /**< Media exists */
  26. BOOTFLOWST_PART, /**< Partition exists */
  27. BOOTFLOWST_FS, /**< Filesystem exists */
  28. BOOTFLOWST_FILE, /**< Bootflow file exists */
  29. BOOTFLOWST_READY, /**< Bootflow file loaded */
  30. BOOTFLOWST_COUNT
  31. };
  32. /**
  33. * enum bootflow_flags_t - flags for bootflows
  34. *
  35. * @BOOTFLOWF_USE_PRIOR_FDT: Indicates that an FDT was not found by the bootmeth
  36. * and it is using the prior-stage FDT, which is the U-Boot control FDT.
  37. * This is only possible with the EFI bootmeth (distro-efi) and only when
  38. * CONFIG_OF_HAS_PRIOR_STAGE is enabled
  39. */
  40. enum bootflow_flags_t {
  41. BOOTFLOWF_USE_PRIOR_FDT = 1 << 0,
  42. };
  43. /**
  44. * struct bootflow - information about a bootflow
  45. *
  46. * This is connected into two separate linked lists:
  47. *
  48. * bm_sibling - links all bootflows in the same bootdev
  49. * glob_sibling - links all bootflows in all bootdevs
  50. *
  51. * @bm_node: Points to siblings in the same bootdev
  52. * @glob_node: Points to siblings in the global list (all bootdev)
  53. * @dev: Bootdev device which produced this bootflow
  54. * @blk: Block device which contains this bootflow, NULL if this is a network
  55. * device or sandbox 'host' device
  56. * @part: Partition number (0 for whole device)
  57. * @fs_type: Filesystem type (FS_TYPE...) if this is fixed by the media, else 0.
  58. * For example, the sandbox host-filesystem bootdev sets this to
  59. * FS_TYPE_SANDBOX
  60. * @method: Bootmethod device used to perform the boot and read files
  61. * @name: Name of bootflow (allocated)
  62. * @state: Current state (enum bootflow_state_t)
  63. * @subdir: Subdirectory to fetch files from (with trailing /), or NULL if none
  64. * @fname: Filename of bootflow file (allocated)
  65. * @logo: Logo to display for this bootflow (BMP format)
  66. * @logo_size: Size of the logo in bytes
  67. * @buf: Bootflow file contents (allocated)
  68. * @size: Size of bootflow file in bytes
  69. * @err: Error number received (0 if OK)
  70. * @os_name: Name of the OS / distro being booted, or NULL if not known
  71. * (allocated)
  72. * @fdt_fname: Filename of FDT file
  73. * @fdt_size: Size of FDT file
  74. * @fdt_addr: Address of loaded fdt
  75. * @flags: Flags for the bootflow (see enum bootflow_flags_t)
  76. * @cmdline: OS command line, or NULL if not known (allocated)
  77. * @x86_setup: Pointer to x86 setup block inside @buf, NULL if not present
  78. */
  79. struct bootflow {
  80. struct list_head bm_node;
  81. struct list_head glob_node;
  82. struct udevice *dev;
  83. struct udevice *blk;
  84. int part;
  85. int fs_type;
  86. struct udevice *method;
  87. char *name;
  88. enum bootflow_state_t state;
  89. char *subdir;
  90. char *fname;
  91. void *logo;
  92. uint logo_size;
  93. char *buf;
  94. int size;
  95. int err;
  96. char *os_name;
  97. char *fdt_fname;
  98. int fdt_size;
  99. ulong fdt_addr;
  100. int flags;
  101. char *cmdline;
  102. char *x86_setup;
  103. };
  104. /**
  105. * enum bootflow_iter_flags_t - flags for the bootflow iterator
  106. *
  107. * @BOOTFLOWIF_FIXED: Only used fixed/internal media
  108. * @BOOTFLOWIF_SHOW: Show each bootdev before scanning it; show each hunter
  109. * before using it
  110. * @BOOTFLOWIF_ALL: Return bootflows with errors as well
  111. * @BOOTFLOWIF_HUNT: Hunt for new bootdevs using the bootdrv hunters
  112. *
  113. * Internal flags:
  114. * @BOOTFLOWIF_SINGLE_DEV: (internal) Just scan one bootdev
  115. * @BOOTFLOWIF_SKIP_GLOBAL: (internal) Don't scan global bootmeths
  116. * @BOOTFLOWIF_SINGLE_UCLASS: (internal) Keep scanning through all devices in
  117. * this uclass (used with things like "mmc")
  118. * @BOOTFLOWIF_SINGLE_MEDIA: (internal) Scan one media device in the uclass (used
  119. * with things like "mmc1")
  120. */
  121. enum bootflow_iter_flags_t {
  122. BOOTFLOWIF_FIXED = 1 << 0,
  123. BOOTFLOWIF_SHOW = 1 << 1,
  124. BOOTFLOWIF_ALL = 1 << 2,
  125. BOOTFLOWIF_HUNT = 1 << 3,
  126. /*
  127. * flags used internally by standard boot - do not set these when
  128. * calling bootflow_scan_bootdev() etc.
  129. */
  130. BOOTFLOWIF_SINGLE_DEV = 1 << 16,
  131. BOOTFLOWIF_SKIP_GLOBAL = 1 << 17,
  132. BOOTFLOWIF_SINGLE_UCLASS = 1 << 18,
  133. BOOTFLOWIF_SINGLE_MEDIA = 1 << 19,
  134. };
  135. /**
  136. * enum bootflow_meth_flags_t - flags controlling which bootmeths are used
  137. *
  138. * Used during iteration, e.g. by bootdev_find_by_label(), to determine which
  139. * bootmeths are used for the current bootdev. The flags reset when the bootdev
  140. * changes
  141. *
  142. * @BOOTFLOW_METHF_DHCP_ONLY: Only use dhcp (scripts and EFI)
  143. * @BOOTFLOW_METHF_PXE_ONLY: Only use pxe (PXE boot)
  144. * @BOOTFLOW_METHF_SINGLE_DEV: Scan only a single bootdev (used for labels like
  145. * "3"). This is used if a sequence number is provided instead of a label
  146. * @BOOTFLOW_METHF_SINGLE_UCLASS: Scan all bootdevs in this one uclass (used
  147. * with things like "mmc"). If this is not set, then the bootdev has an integer
  148. * value in the label (like "mmc2")
  149. */
  150. enum bootflow_meth_flags_t {
  151. BOOTFLOW_METHF_DHCP_ONLY = 1 << 0,
  152. BOOTFLOW_METHF_PXE_ONLY = 1 << 1,
  153. BOOTFLOW_METHF_SINGLE_DEV = 1 << 2,
  154. BOOTFLOW_METHF_SINGLE_UCLASS = 1 << 3,
  155. };
  156. /**
  157. * struct bootflow_iter - state for iterating through bootflows
  158. *
  159. * This starts at with the first bootdev/partition/bootmeth and can be used to
  160. * iterate through all of them.
  161. *
  162. * Iteration starts with the bootdev. The first partition (0, i.e. whole device)
  163. * is scanned first. For partition 0, it iterates through all the available
  164. * bootmeths to see which one(s) can provide a bootflow. Then it moves to
  165. * parition 1 (if there is one) and the process continues. Once all partitions
  166. * are examined, it moves to the next bootdev.
  167. *
  168. * Initially @max_part is 0, meaning that only the whole device (@part=0) can be
  169. * used. During scanning, if a partition table is found, then @max_part is
  170. * updated to a larger value, no less than the number of available partitions.
  171. * This ensures that iteration works through all partitions on the bootdev.
  172. *
  173. * @flags: Flags to use (see enum bootflow_iter_flags_t). If
  174. * BOOTFLOWIF_GLOBAL_FIRST is enabled then the global bootmeths are being
  175. * scanned, otherwise we have moved onto the bootdevs
  176. * @dev: Current bootdev, NULL if none. This is only ever updated in
  177. * bootflow_iter_set_dev()
  178. * @part: Current partition number (0 for whole device)
  179. * @method: Current bootmeth
  180. * @max_part: Maximum hardware partition number in @dev, 0 if there is no
  181. * partition table
  182. * @first_bootable: First bootable partition, or 0 if none
  183. * @err: Error obtained from checking the last iteration. This is used to skip
  184. * forward (e.g. to skip the current partition because it is not valid)
  185. * -ESHUTDOWN: try next bootdev
  186. * @num_devs: Number of bootdevs in @dev_used
  187. * @max_devs: Maximum number of entries in @dev_used
  188. * @dev_used: List of bootdevs used during iteration
  189. * @labels: List of labels to scan for bootdevs
  190. * @cur_label: Current label being processed
  191. * @num_methods: Number of bootmeth devices in @method_order
  192. * @cur_method: Current method number, an index into @method_order
  193. * @first_glob_method: First global method, if any, else -1
  194. * @cur_prio: Current priority being scanned
  195. * @method_order: List of bootmeth devices to use, in order. The normal methods
  196. * appear first, then the global ones, if any
  197. * @doing_global: true if we are iterating through the global bootmeths (which
  198. * happens before the normal ones)
  199. * @method_flags: flags controlling which methods should be used for this @dev
  200. * (enum bootflow_meth_flags_t)
  201. */
  202. struct bootflow_iter {
  203. int flags;
  204. struct udevice *dev;
  205. int part;
  206. struct udevice *method;
  207. int max_part;
  208. int first_bootable;
  209. int err;
  210. int num_devs;
  211. int max_devs;
  212. struct udevice *dev_used[BOOTFLOW_MAX_USED_DEVS];
  213. const char *const *labels;
  214. int cur_label;
  215. int num_methods;
  216. int cur_method;
  217. int first_glob_method;
  218. enum bootdev_prio_t cur_prio;
  219. struct udevice **method_order;
  220. bool doing_global;
  221. int method_flags;
  222. };
  223. /**
  224. * bootflow_init() - Set up a bootflow struct
  225. *
  226. * The bootflow is zeroed and set to state BOOTFLOWST_BASE
  227. *
  228. * @bflow: Struct to set up
  229. * @bootdev: Bootdev to use
  230. * @meth: Bootmeth to use
  231. */
  232. void bootflow_init(struct bootflow *bflow, struct udevice *bootdev,
  233. struct udevice *meth);
  234. /**
  235. * bootflow_iter_init() - Reset a bootflow iterator
  236. *
  237. * This sets everything to the starting point, ready for use.
  238. *
  239. * @iter: Place to store private info (inited by this call)
  240. * @flags: Flags to use (see enum bootflow_iter_flags_t)
  241. */
  242. void bootflow_iter_init(struct bootflow_iter *iter, int flags);
  243. /**
  244. * bootflow_iter_uninit() - Free memory used by an interator
  245. *
  246. * @iter: Iterator to free
  247. */
  248. void bootflow_iter_uninit(struct bootflow_iter *iter);
  249. /**
  250. * bootflow_iter_drop_bootmeth() - Remove a bootmeth from an iterator
  251. *
  252. * Update the iterator so that the bootmeth will not be used again while this
  253. * iterator is in use
  254. *
  255. * @iter: Iterator to update
  256. * @bmeth: Boot method to remove
  257. */
  258. int bootflow_iter_drop_bootmeth(struct bootflow_iter *iter,
  259. const struct udevice *bmeth);
  260. /**
  261. * bootflow_scan_first() - find the first bootflow for a device or label
  262. *
  263. * If @flags includes BOOTFLOWIF_ALL then bootflows with errors are returned too
  264. *
  265. * @dev: Boot device to scan, NULL to work through all of them until it
  266. * finds one that can supply a bootflow
  267. * @label: Label to control the scan, NULL to work through all devices
  268. * until it finds one that can supply a bootflow
  269. * @iter: Place to store private info (inited by this call)
  270. * @flags: Flags for iterator (enum bootflow_iter_flags_t). Note that if
  271. * @dev is NULL, then BOOTFLOWIF_SKIP_GLOBAL is set automatically by this
  272. * function
  273. * @bflow: Place to put the bootflow if found
  274. * Return: 0 if found, -ENODEV if no device, other -ve on other error
  275. * (iteration can continue)
  276. */
  277. int bootflow_scan_first(struct udevice *dev, const char *label,
  278. struct bootflow_iter *iter, int flags,
  279. struct bootflow *bflow);
  280. /**
  281. * bootflow_scan_next() - find the next bootflow
  282. *
  283. * This works through the available bootdev devices until it finds one that
  284. * can supply a bootflow. It then returns that bootflow
  285. *
  286. * @iter: Private info (as set up by bootflow_scan_first())
  287. * @bflow: Place to put the bootflow if found
  288. * Return: 0 if found, -ENODEV if no device, -ESHUTDOWN if no more bootflows,
  289. * other -ve on other error (iteration can continue)
  290. */
  291. int bootflow_scan_next(struct bootflow_iter *iter, struct bootflow *bflow);
  292. /**
  293. * bootflow_first_glob() - Get the first bootflow from the global list
  294. *
  295. * Returns the first bootflow in the global list, no matter what bootflow it is
  296. * attached to
  297. *
  298. * @bflowp: Returns a pointer to the bootflow
  299. * Return: 0 if found, -ENOENT if there are no bootflows
  300. */
  301. int bootflow_first_glob(struct bootflow **bflowp);
  302. /**
  303. * bootflow_next_glob() - Get the next bootflow from the global list
  304. *
  305. * Returns the next bootflow in the global list, no matter what bootflow it is
  306. * attached to
  307. *
  308. * @bflowp: On entry, the last bootflow returned , e.g. from
  309. * bootflow_first_glob()
  310. * Return: 0 if found, -ENOENT if there are no more bootflows
  311. */
  312. int bootflow_next_glob(struct bootflow **bflowp);
  313. /**
  314. * bootflow_free() - Free memory used by a bootflow
  315. *
  316. * This frees fields within @bflow, but not the @bflow pointer itself
  317. */
  318. void bootflow_free(struct bootflow *bflow);
  319. /**
  320. * bootflow_boot() - boot a bootflow
  321. *
  322. * @bflow: Bootflow to boot
  323. * Return: -EPROTO if bootflow has not been loaded, -ENOSYS if the bootflow
  324. * type is not supported, -EFAULT if the boot returned without an error
  325. * when we are expecting it to boot, -ENOTSUPP if trying method resulted in
  326. * finding out that is not actually supported for this boot and should not
  327. * be tried again unless something changes
  328. */
  329. int bootflow_boot(struct bootflow *bflow);
  330. /**
  331. * bootflow_run_boot() - Try to boot a bootflow
  332. *
  333. * @iter: Current iteration (or NULL if none). Used to disable a bootmeth if the
  334. * boot returns -ENOTSUPP
  335. * @bflow: Bootflow to boot
  336. * Return: result of trying to boot
  337. */
  338. int bootflow_run_boot(struct bootflow_iter *iter, struct bootflow *bflow);
  339. /**
  340. * bootflow_state_get_name() - Get the name of a bootflow state
  341. *
  342. * @state: State to check
  343. * Return: name, or "?" if invalid
  344. */
  345. const char *bootflow_state_get_name(enum bootflow_state_t state);
  346. /**
  347. * bootflow_remove() - Remove a bootflow and free its memory
  348. *
  349. * This updates the linked lists containing the bootflow then frees it.
  350. *
  351. * @bflow: Bootflow to remove
  352. */
  353. void bootflow_remove(struct bootflow *bflow);
  354. /**
  355. * bootflow_iter_check_blk() - Check that a bootflow uses a block device
  356. *
  357. * This checks the bootdev in the bootflow to make sure it uses a block device
  358. *
  359. * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. ethernet)
  360. */
  361. int bootflow_iter_check_blk(const struct bootflow_iter *iter);
  362. /**
  363. * bootflow_iter_check_sf() - Check that a bootflow uses SPI FLASH
  364. *
  365. * This checks the bootdev in the bootflow to make sure it uses SPI flash
  366. *
  367. * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. ethernet)
  368. */
  369. int bootflow_iter_check_sf(const struct bootflow_iter *iter);
  370. /**
  371. * bootflow_iter_check_net() - Check that a bootflow uses a network device
  372. *
  373. * This checks the bootdev in the bootflow to make sure it uses a network
  374. * device
  375. *
  376. * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC)
  377. */
  378. int bootflow_iter_check_net(const struct bootflow_iter *iter);
  379. /**
  380. * bootflow_iter_check_system() - Check that a bootflow uses the bootstd device
  381. *
  382. * This checks the bootdev in the bootflow to make sure it uses the bootstd
  383. * device
  384. *
  385. * Return: 0 if OK, -ENOTSUPP if some other device is used (e.g. MMC)
  386. */
  387. int bootflow_iter_check_system(const struct bootflow_iter *iter);
  388. /**
  389. * bootflow_menu_new() - Create a new bootflow menu
  390. *
  391. * @expp: Returns the expo created
  392. * Returns 0 on success, -ve on error
  393. */
  394. int bootflow_menu_new(struct expo **expp);
  395. /**
  396. * bootflow_menu_apply_theme() - Apply a theme to a bootmenu
  397. *
  398. * @exp: Expo to update
  399. * @node: Node containing the theme information
  400. * Returns 0 on success, -ve on error
  401. */
  402. int bootflow_menu_apply_theme(struct expo *exp, ofnode node);
  403. /**
  404. * bootflow_menu_run() - Create and run a menu of available bootflows
  405. *
  406. * @std: Bootstd information
  407. * @text_mode: Uses a text-based menu suitable for a serial port
  408. * @bflowp: Returns chosen bootflow (set to NULL if nothing is chosen)
  409. * @return 0 if an option was chosen, -EAGAIN if nothing was chosen, -ve on
  410. * error
  411. */
  412. int bootflow_menu_run(struct bootstd_priv *std, bool text_mode,
  413. struct bootflow **bflowp);
  414. #define BOOTFLOWCL_EMPTY ((void *)1)
  415. /**
  416. * cmdline_set_arg() - Update or read an argument in a cmdline string
  417. *
  418. * Handles updating a single arg in a cmdline string, returning it in a supplied
  419. * buffer; also reading an arg from a cmdline string
  420. *
  421. * When updating, consecutive spaces are squashed as are spaces at the start and
  422. * end.
  423. *
  424. * @buf: Working buffer to use (initial contents are ignored). Use NULL when
  425. * reading
  426. * @maxlen: Length of working buffer. Use 0 when reading
  427. * @cmdline: Command line to update, in the form:
  428. *
  429. * fred mary= jane=123 john="has spaces"
  430. *
  431. * @set_arg: Argument to set or read (may or may not exist)
  432. * @new_val: Value for the new argument. May not include quotes (") but may
  433. * include embedded spaces, in which case it will be quoted when added to the
  434. * command line. Use NULL to delete the argument from @cmdline, BOOTFLOWCL_EMPTY
  435. * to set it to an empty value (no '=' sign after arg), "" to add an '=' sign
  436. * but with an empty value. Use NULL when reading.
  437. * @posp: Ignored when setting an argument; when getting an argument, returns
  438. * the start position of its value in @cmdline, after the first quote, if any
  439. *
  440. * Return:
  441. * For updating:
  442. * length of new buffer (including \0 terminator) on success, -ENOENT if
  443. * @new_val is NULL and @set_arg does not exist in @from, -EINVAL if a
  444. * quoted arg-value in @from is not terminated with a quote, -EBADF if
  445. * @new_val has spaces but does not start and end with quotes (or it has
  446. * quotes in the middle of the string), -E2BIG if @maxlen is too small
  447. * For reading:
  448. * length of arg value (excluding quotes), -ENOENT if not found
  449. */
  450. int cmdline_set_arg(char *buf, int maxlen, const char *cmdline,
  451. const char *set_arg, const char *new_val, int *posp);
  452. /**
  453. * bootflow_cmdline_set_arg() - Set a single argument for a bootflow
  454. *
  455. * Update the allocated cmdline and set the bootargs variable
  456. *
  457. * @bflow: Bootflow to update
  458. * @arg: Argument to update (e.g. "console")
  459. * @val: Value to set (e.g. "ttyS2") or NULL to delete the argument if present,
  460. * "" to set it to an empty value (e.g. "console=") and BOOTFLOWCL_EMPTY to add
  461. * it without any value ("initrd")
  462. * @set_env: true to set the "bootargs" environment variable too
  463. *
  464. * Return: 0 if OK, -ENOMEM if out of memory
  465. */
  466. int bootflow_cmdline_set_arg(struct bootflow *bflow, const char *arg,
  467. const char *val, bool set_env);
  468. /**
  469. * cmdline_get_arg() - Read an argument from a cmdline
  470. *
  471. * @cmdline: Command line to read, in the form:
  472. *
  473. * fred mary= jane=123 john="has spaces"
  474. * @arg: Argument to read (may or may not exist)
  475. * @posp: Returns position of argument (after any leading quote) if present
  476. * Return: Length of argument value excluding quotes if found, -ENOENT if not
  477. * found
  478. */
  479. int cmdline_get_arg(const char *cmdline, const char *arg, int *posp);
  480. /**
  481. * bootflow_cmdline_get_arg() - Read an argument from a cmdline
  482. *
  483. * @bootflow: Bootflow to read from
  484. * @arg: Argument to read (may or may not exist)
  485. * @valp: Returns a pointer to the argument (after any leading quote) if present
  486. * Return: Length of argument value excluding quotes if found, -ENOENT if not
  487. * found
  488. */
  489. int bootflow_cmdline_get_arg(struct bootflow *bflow, const char *arg,
  490. const char **val);
  491. /**
  492. * bootflow_cmdline_auto() - Automatically set a value for a known argument
  493. *
  494. * This handles a small number of known arguments, for Linux in particular. It
  495. * adds suitable kernel parameters automatically, e.g. to enable the console.
  496. *
  497. * @bflow: Bootflow to update
  498. * @arg: Name of argument to set (e.g. "earlycon" or "console")
  499. * Return: 0 if OK -ve on error
  500. */
  501. int bootflow_cmdline_auto(struct bootflow *bflow, const char *arg);
  502. #endif