]>
Commit | Line | Data |
---|---|---|
a950d31a SG |
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 | ||
bc06aa03 SG |
15 | /** |
16 | * enum bootmeth_flags - Flags for bootmeths | |
17 | * | |
18 | * @BOOTMETHF_GLOBAL: bootmeth handles bootdev selection automatically | |
831405f4 SG |
19 | * @BOOTMETHF_ANY_PART: bootmeth is willing to check any partition, even if it |
20 | * has no filesystem | |
bc06aa03 SG |
21 | */ |
22 | enum bootmeth_flags { | |
23 | BOOTMETHF_GLOBAL = BIT(0), | |
831405f4 | 24 | BOOTMETHF_ANY_PART = BIT(1), |
bc06aa03 SG |
25 | }; |
26 | ||
a950d31a SG |
27 | /** |
28 | * struct bootmeth_uc_plat - information the uclass keeps about each bootmeth | |
29 | * | |
30 | * @desc: A long description of the bootmeth | |
bc06aa03 | 31 | * @flags: Flags for this bootmeth (enum bootmeth_flags) |
a950d31a SG |
32 | */ |
33 | struct bootmeth_uc_plat { | |
34 | const char *desc; | |
bc06aa03 | 35 | int flags; |
a950d31a SG |
36 | }; |
37 | ||
38 | /** struct bootmeth_ops - Operations for boot methods */ | |
39 | struct bootmeth_ops { | |
40 | /** | |
988cacae SG |
41 | * 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 | |
a950d31a SG |
60 | * |
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 | ||
22061d3d SG |
93 | /** |
94 | * 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 | ||
a950d31a SG |
109 | /** |
110 | * 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); | |
c279224e SG |
125 | #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 */ | |
a950d31a SG |
135 | /** |
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 | ||
988cacae SG |
151 | /** |
152 | * 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 | */ | |
167 | int bootmeth_get_state_desc(struct udevice *dev, char *buf, int maxsize); | |
168 | ||
a950d31a SG |
169 | /** |
170 | * 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 | */ | |
192 | int 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 | */ | |
202 | int bootmeth_read_bootflow(struct udevice *dev, struct bootflow *bflow); | |
203 | ||
22061d3d SG |
204 | /** |
205 | * 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 | */ | |
218 | int bootmeth_set_bootflow(struct udevice *dev, struct bootflow *bflow, | |
219 | char *buf, int size); | |
220 | ||
a950d31a SG |
221 | /** |
222 | * 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 | */ | |
235 | int bootmeth_read_file(struct udevice *dev, struct bootflow *bflow, | |
236 | const char *file_path, ulong addr, ulong *sizep); | |
237 | ||
c279224e SG |
238 | /** |
239 | * 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 | */ | |
250 | int bootmeth_read_all(struct udevice *dev, struct bootflow *bflow); | |
251 | ||
a950d31a SG |
252 | /** |
253 | * 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 | */ | |
261 | int 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 | |
c627cfc1 SG |
271 | * @include_global: true to add the global bootmeths, in which case they appear |
272 | * first | |
a950d31a SG |
273 | * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve |
274 | * on other error | |
275 | */ | |
c627cfc1 | 276 | int bootmeth_setup_iter_order(struct bootflow_iter *iter, bool include_global); |
a950d31a SG |
277 | |
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 | |
79f66351 | 284 | * bootmeth-device names, e.g. "extlinux,efi". If empty then a default ordering |
a950d31a SG |
285 | * 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 | */ | |
289 | int bootmeth_set_order(const char *order_str); | |
290 | ||
0c0c82b5 SG |
291 | /** |
292 | * 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 | */ | |
302 | int bootmeth_setup_fs(struct bootflow *bflow, struct blk_desc *desc); | |
303 | ||
a950d31a SG |
304 | /** |
305 | * 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 | |
a58e7bbe | 315 | * @desc: Block descriptor to read from (NULL for sandbox host) |
a950d31a SG |
316 | * @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 | */ | |
321 | int 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 | */ | |
338 | int bootmeth_alloc_file(struct bootflow *bflow, uint size_limit, uint align); | |
339 | ||
24d8e1b3 SG |
340 | /** |
341 | * 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 | */ | |
353 | int bootmeth_alloc_other(struct bootflow *bflow, const char *fname, | |
354 | void **bufp, uint *sizep); | |
355 | ||
a950d31a SG |
356 | /** |
357 | * 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 | */ | |
368 | int bootmeth_common_read_file(struct udevice *dev, struct bootflow *bflow, | |
369 | const char *file_path, ulong addr, ulong *sizep); | |
370 | ||
bc06aa03 SG |
371 | /** |
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 | */ | |
381 | int bootmeth_get_bootflow(struct udevice *dev, struct bootflow *bflow); | |
382 | ||
a950d31a | 383 | #endif |