blob: 0fc36104ece0ebcbe899a93e8df7ac1f2cd921a7 [file] [log] [blame]
Simon Glassa950d312022-04-24 23:31:08 -06001/* 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
10struct blk_desc;
11struct bootflow;
12struct bootflow_iter;
13struct udevice;
14
15/**
Simon Glassbc06aa02022-07-30 15:52:21 -060016 * enum bootmeth_flags - Flags for bootmeths
17 *
18 * @BOOTMETHF_GLOBAL: bootmeth handles bootdev selection automatically
Simon Glass831405f2023-08-24 13:55:43 -060019 * @BOOTMETHF_ANY_PART: bootmeth is willing to check any partition, even if it
20 * has no filesystem
Simon Glassbc06aa02022-07-30 15:52:21 -060021 */
22enum bootmeth_flags {
23 BOOTMETHF_GLOBAL = BIT(0),
Simon Glass831405f2023-08-24 13:55:43 -060024 BOOTMETHF_ANY_PART = BIT(1),
Simon Glassbc06aa02022-07-30 15:52:21 -060025};
26
27/**
Simon Glassa950d312022-04-24 23:31:08 -060028 * struct bootmeth_uc_plat - information the uclass keeps about each bootmeth
29 *
30 * @desc: A long description of the bootmeth
Simon Glassbc06aa02022-07-30 15:52:21 -060031 * @flags: Flags for this bootmeth (enum bootmeth_flags)
Simon Glassa950d312022-04-24 23:31:08 -060032 */
33struct bootmeth_uc_plat {
34 const char *desc;
Simon Glassbc06aa02022-07-30 15:52:21 -060035 int flags;
Simon Glassa950d312022-04-24 23:31:08 -060036};
37
38/** struct bootmeth_ops - Operations for boot methods */
39struct bootmeth_ops {
40 /**
Simon Glass988caca2022-07-30 15:52:19 -060041 * 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
Simon Glassa950d312022-04-24 23:31:08 -060060 *
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 /**
Simon Glass22061d32023-01-17 10:48:01 -070094 * 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 /**
Simon Glassa950d312022-04-24 23:31:08 -0600110 * 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);
Simon Glassc2792242023-08-10 19:33:18 -0600125#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 */
Simon Glassa950d312022-04-24 23:31:08 -0600135 /**
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/**
Simon Glass988caca2022-07-30 15:52:19 -0600152 * 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 */
167int bootmeth_get_state_desc(struct udevice *dev, char *buf, int maxsize);
168
169/**
Simon Glassa950d312022-04-24 23:31:08 -0600170 * 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 */
192int 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 */
202int bootmeth_read_bootflow(struct udevice *dev, struct bootflow *bflow);
203
204/**
Simon Glass22061d32023-01-17 10:48:01 -0700205 * 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 */
218int bootmeth_set_bootflow(struct udevice *dev, struct bootflow *bflow,
219 char *buf, int size);
220
221/**
Simon Glassa950d312022-04-24 23:31:08 -0600222 * 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 */
235int bootmeth_read_file(struct udevice *dev, struct bootflow *bflow,
236 const char *file_path, ulong addr, ulong *sizep);
237
238/**
Simon Glassc2792242023-08-10 19:33:18 -0600239 * 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 */
250int bootmeth_read_all(struct udevice *dev, struct bootflow *bflow);
251
252/**
Simon Glassa950d312022-04-24 23:31:08 -0600253 * 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 */
261int 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
Simon Glassc627cfc2022-07-30 15:52:27 -0600271 * @include_global: true to add the global bootmeths, in which case they appear
272 * first
Simon Glassa950d312022-04-24 23:31:08 -0600273 * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve
274 * on other error
275 */
Simon Glassc627cfc2022-07-30 15:52:27 -0600276int bootmeth_setup_iter_order(struct bootflow_iter *iter, bool include_global);
Simon Glassa950d312022-04-24 23:31:08 -0600277
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
Simon Glass79f66352023-05-10 16:34:46 -0600284 * bootmeth-device names, e.g. "extlinux,efi". If empty then a default ordering
Simon Glassa950d312022-04-24 23:31:08 -0600285 * 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 */
289int bootmeth_set_order(const char *order_str);
290
291/**
Simon Glass0c0c82b2023-07-26 21:01:21 -0600292 * 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 */
302int bootmeth_setup_fs(struct bootflow *bflow, struct blk_desc *desc);
303
304/**
Simon Glassa950d312022-04-24 23:31:08 -0600305 * 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
Simon Glassa58e7bb2023-01-17 10:47:59 -0700315 * @desc: Block descriptor to read from (NULL for sandbox host)
Simon Glassa950d312022-04-24 23:31:08 -0600316 * @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 */
321int 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 */
338int bootmeth_alloc_file(struct bootflow *bflow, uint size_limit, uint align);
339
340/**
Simon Glass24d8e1b2023-01-06 08:52:34 -0600341 * 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 */
353int bootmeth_alloc_other(struct bootflow *bflow, const char *fname,
354 void **bufp, uint *sizep);
355
356/**
Simon Glassa950d312022-04-24 23:31:08 -0600357 * 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 */
368int bootmeth_common_read_file(struct udevice *dev, struct bootflow *bflow,
369 const char *file_path, ulong addr, ulong *sizep);
370
Simon Glassbc06aa02022-07-30 15:52:21 -0600371/**
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 */
381int bootmeth_get_bootflow(struct udevice *dev, struct bootflow *bflow);
382
Simon Glassa950d312022-04-24 23:31:08 -0600383#endif