blob: d3d8d608cd78903af6e80278fb0944a607eeca00 [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
19 */
20enum bootmeth_flags {
21 BOOTMETHF_GLOBAL = BIT(0),
22};
23
24/**
Simon Glassa950d312022-04-24 23:31:08 -060025 * struct bootmeth_uc_plat - information the uclass keeps about each bootmeth
26 *
27 * @desc: A long description of the bootmeth
Simon Glassbc06aa02022-07-30 15:52:21 -060028 * @flags: Flags for this bootmeth (enum bootmeth_flags)
Simon Glassa950d312022-04-24 23:31:08 -060029 */
30struct bootmeth_uc_plat {
31 const char *desc;
Simon Glassbc06aa02022-07-30 15:52:21 -060032 int flags;
Simon Glassa950d312022-04-24 23:31:08 -060033};
34
35/** struct bootmeth_ops - Operations for boot methods */
36struct bootmeth_ops {
37 /**
Simon Glass988caca2022-07-30 15:52:19 -060038 * get_state_desc() - get detailed state information
39 *
40 * Prodecues a textual description of the state of the bootmeth. This
41 * can include newline characters if it extends to multiple lines. It
42 * must be a nul-terminated string.
43 *
44 * This may involve reading state from the system, e.g. some data in
45 * the firmware area.
46 *
47 * @dev: Bootmethod device to check
48 * @buf: Buffer to place the info in (terminator must fit)
49 * @maxsize: Size of buffer
50 * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if
51 * something else went wrong
52 */
53 int (*get_state_desc)(struct udevice *dev, char *buf, int maxsize);
54
55 /**
56 * check_supported() - check if a bootmeth supports this bootdev
Simon Glassa950d312022-04-24 23:31:08 -060057 *
58 * This is optional. If not provided, the bootdev is assumed to be
59 * supported
60 *
61 * The bootmeth can check the bootdev (e.g. to make sure it is a
62 * network device) or the partition information. The following fields
63 * in @iter are available:
64 *
65 * name, dev, state, part
66 * max_part may be set if part != 0 (i.e. there is a valid partition
67 * table). Otherwise max_part is 0
68 * method is available but is the same as @dev
69 * the partition has not yet been read, nor has the filesystem been
70 * checked
71 *
72 * It may update only the flags in @iter
73 *
74 * @dev: Bootmethod device to check against
75 * @iter: On entry, provides bootdev, hwpart, part
76 * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported
77 */
78 int (*check)(struct udevice *dev, struct bootflow_iter *iter);
79
80 /**
81 * read_bootflow() - read a bootflow for a device
82 *
83 * @dev: Bootmethod device to use
84 * @bflow: On entry, provides dev, hwpart, part and method.
85 * Returns updated bootflow if found
86 * Return: 0 if OK, -ve on error
87 */
88 int (*read_bootflow)(struct udevice *dev, struct bootflow *bflow);
89
90 /**
Simon Glass22061d32023-01-17 10:48:01 -070091 * set_bootflow() - set the bootflow for a device
92 *
93 * This provides a bootflow file to the bootmeth, to see if it is valid.
94 * If it is, the bootflow is set up accordingly.
95 *
96 * @dev: Bootmethod device to use
97 * @bflow: On entry, provides bootdev.
98 * Returns updated bootflow if found
99 * @buf: Buffer containing the possible bootflow file
100 * @size: Size of file
101 * Return: 0 if OK, -ve on error
102 */
103 int (*set_bootflow)(struct udevice *dev, struct bootflow *bflow,
104 char *buf, int size);
105
106 /**
Simon Glassa950d312022-04-24 23:31:08 -0600107 * read_file() - read a file needed for a bootflow
108 *
109 * Read a file from the same place as the bootflow came from
110 *
111 * @dev: Bootmethod device to use
112 * @bflow: Bootflow providing info on where to read from
113 * @file_path: Path to file (may be absolute or relative)
114 * @addr: Address to load file
115 * @sizep: On entry provides the maximum permitted size; on exit
116 * returns the size of the file
117 * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other
118 * -ve value if something else goes wrong
119 */
120 int (*read_file)(struct udevice *dev, struct bootflow *bflow,
121 const char *file_path, ulong addr, ulong *sizep);
Simon Glassc2792242023-08-10 19:33:18 -0600122#if CONFIG_IS_ENABLED(BOOTSTD_FULL)
123 /**
124 * readall() - read all files for a bootflow
125 *
126 * @dev: Bootmethod device to boot
127 * @bflow: Bootflow to read
128 * Return: 0 if OK, -EIO on I/O error, other -ve on other error
129 */
130 int (*read_all)(struct udevice *dev, struct bootflow *bflow);
131#endif /* BOOTSTD_FULL */
Simon Glassa950d312022-04-24 23:31:08 -0600132 /**
133 * boot() - boot a bootflow
134 *
135 * @dev: Bootmethod device to boot
136 * @bflow: Bootflow to boot
137 * Return: does not return on success, since it should boot the
138 * Operating Systemn. Returns -EFAULT if that fails, -ENOTSUPP if
139 * trying method resulted in finding out that is not actually
140 * supported for this boot and should not be tried again unless
141 * something changes, other -ve on other error
142 */
143 int (*boot)(struct udevice *dev, struct bootflow *bflow);
144};
145
146#define bootmeth_get_ops(dev) ((struct bootmeth_ops *)(dev)->driver->ops)
147
148/**
Simon Glass988caca2022-07-30 15:52:19 -0600149 * bootmeth_get_state_desc() - get detailed state information
150 *
151 * Prodecues a textual description of the state of the bootmeth. This
152 * can include newline characters if it extends to multiple lines. It
153 * must be a nul-terminated string.
154 *
155 * This may involve reading state from the system, e.g. some data in
156 * the firmware area.
157 *
158 * @dev: Bootmethod device to check
159 * @buf: Buffer to place the info in (terminator must fit)
160 * @maxsize: Size of buffer
161 * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if
162 * something else went wrong
163 */
164int bootmeth_get_state_desc(struct udevice *dev, char *buf, int maxsize);
165
166/**
Simon Glassa950d312022-04-24 23:31:08 -0600167 * bootmeth_check() - check if a bootmeth supports this bootflow
168 *
169 * This is optional. If not provided, the bootdev is assumed to be
170 * supported
171 *
172 * The bootmeth can check the bootdev (e.g. to make sure it is a
173 * network device) or the partition information. The following fields
174 * in @iter are available:
175 *
176 * name, dev, state, part
177 * max_part may be set if part != 0 (i.e. there is a valid partition
178 * table). Otherwise max_part is 0
179 * method is available but is the same as @dev
180 * the partition has not yet been read, nor has the filesystem been
181 * checked
182 *
183 * It may update only the flags in @iter
184 *
185 * @dev: Bootmethod device to check against
186 * @iter: On entry, provides bootdev, hwpart, part
187 * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported
188 */
189int bootmeth_check(struct udevice *dev, struct bootflow_iter *iter);
190
191/**
192 * bootmeth_read_bootflow() - set up a bootflow for a device
193 *
194 * @dev: Bootmethod device to check
195 * @bflow: On entry, provides dev, hwpart, part and method.
196 * Returns updated bootflow if found
197 * Return: 0 if OK, -ve on error
198 */
199int bootmeth_read_bootflow(struct udevice *dev, struct bootflow *bflow);
200
201/**
Simon Glass22061d32023-01-17 10:48:01 -0700202 * bootmeth_set_bootflow() - set the bootflow for a device
203 *
204 * This provides a bootflow file to the bootmeth, to see if it is valid.
205 * If it is, the bootflow is set up accordingly.
206 *
207 * @dev: Bootmethod device to use
208 * @bflow: On entry, provides bootdev.
209 * Returns updated bootflow if found
210 * @buf: Buffer containing the possible bootflow file (must be allocated
211 * by caller to @size + 1 bytes)
212 * @size: Size of file
213 * Return: 0 if OK, -ve on error
214 */
215int bootmeth_set_bootflow(struct udevice *dev, struct bootflow *bflow,
216 char *buf, int size);
217
218/**
Simon Glassa950d312022-04-24 23:31:08 -0600219 * bootmeth_read_file() - read a file needed for a bootflow
220 *
221 * Read a file from the same place as the bootflow came from
222 *
223 * @dev: Bootmethod device to use
224 * @bflow: Bootflow providing info on where to read from
225 * @file_path: Path to file (may be absolute or relative)
226 * @addr: Address to load file
227 * @sizep: On entry provides the maximum permitted size; on exit
228 * returns the size of the file
229 * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other
230 * -ve value if something else goes wrong
231 */
232int bootmeth_read_file(struct udevice *dev, struct bootflow *bflow,
233 const char *file_path, ulong addr, ulong *sizep);
234
235/**
Simon Glassc2792242023-08-10 19:33:18 -0600236 * bootmeth_read_all() - read all bootflow files
237 *
238 * Some bootmeths delay reading of large files until booting is requested. This
239 * causes those files to be read.
240 *
241 * @dev: Bootmethod device to use
242 * @bflow: Bootflow to read
243 * Return: does not return on success, since it should boot the
244 * Operating Systemn. Returns -EFAULT if that fails, other -ve on
245 * other error
246 */
247int bootmeth_read_all(struct udevice *dev, struct bootflow *bflow);
248
249/**
Simon Glassa950d312022-04-24 23:31:08 -0600250 * bootmeth_boot() - boot a bootflow
251 *
252 * @dev: Bootmethod device to boot
253 * @bflow: Bootflow to boot
254 * Return: does not return on success, since it should boot the
255 * Operating Systemn. Returns -EFAULT if that fails, other -ve on
256 * other error
257 */
258int bootmeth_boot(struct udevice *dev, struct bootflow *bflow);
259
260/**
261 * bootmeth_setup_iter_order() - Set up the ordering of bootmeths to scan
262 *
263 * This sets up the ordering information in @iter, based on the selected
264 * ordering of the bootmethds in bootstd_priv->bootmeth_order. If there is no
265 * ordering there, then all bootmethods are added
266 *
267 * @iter: Iterator to update with the order
Simon Glassc627cfc2022-07-30 15:52:27 -0600268 * @include_global: true to add the global bootmeths, in which case they appear
269 * first
Simon Glassa950d312022-04-24 23:31:08 -0600270 * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve
271 * on other error
272 */
Simon Glassc627cfc2022-07-30 15:52:27 -0600273int bootmeth_setup_iter_order(struct bootflow_iter *iter, bool include_global);
Simon Glassa950d312022-04-24 23:31:08 -0600274
275/**
276 * bootmeth_set_order() - Set the bootmeth order
277 *
278 * This selects the ordering to use for bootmeths
279 *
280 * @order_str: String containing the ordering. This is a comma-separate list of
Simon Glass79f66352023-05-10 16:34:46 -0600281 * bootmeth-device names, e.g. "extlinux,efi". If empty then a default ordering
Simon Glassa950d312022-04-24 23:31:08 -0600282 * is used, based on the sequence number of devices (i.e. using aliases)
283 * Return: 0 if OK, -ENODEV if an unknown bootmeth is mentioned, -ENOMEM if
284 * out of memory, -ENOENT if there are no bootmeth devices
285 */
286int bootmeth_set_order(const char *order_str);
287
288/**
Simon Glass0c0c82b2023-07-26 21:01:21 -0600289 * bootmeth_setup_fs() - Set up read to read a file
290 *
291 * We must redo the setup before each filesystem operation. This function
292 * handles that, including setting the filesystem type if a block device is not
293 * being used
294 *
295 * @bflow: Information about file to try
296 * @desc: Block descriptor to read from (NULL if not a block device)
297 * Return: 0 if OK, -ve on error
298 */
299int bootmeth_setup_fs(struct bootflow *bflow, struct blk_desc *desc);
300
301/**
Simon Glassa950d312022-04-24 23:31:08 -0600302 * bootmeth_try_file() - See we can access a given file
303 *
304 * Check for a file with a given name. If found, the filename is allocated in
305 * @bflow
306 *
307 * Sets the state to BOOTFLOWST_FILE on success. It also calls
308 * fs_set_blk_dev_with_part() so that this does not need to be done by the
309 * caller before reading the file.
310 *
311 * @bflow: Information about file to try
Simon Glassa58e7bb2023-01-17 10:47:59 -0700312 * @desc: Block descriptor to read from (NULL for sandbox host)
Simon Glassa950d312022-04-24 23:31:08 -0600313 * @prefix: Filename prefix to prepend to @fname (NULL for none)
314 * @fname: Filename to read
315 * Return: 0 if OK, -ENOMEM if not enough memory to allocate bflow->fname,
316 * other -ve value on other error
317 */
318int bootmeth_try_file(struct bootflow *bflow, struct blk_desc *desc,
319 const char *prefix, const char *fname);
320
321/**
322 * bootmeth_alloc_file() - Allocate and read a bootflow file
323 *
324 * Allocates memory for a bootflow file and reads it in. Sets the state to
325 * BOOTFLOWST_READY on success
326 *
327 * Note that fs_set_blk_dev_with_part() must have been called previously.
328 *
329 * @bflow: Information about file to read
330 * @size_limit: Maximum file size to permit
331 * @align: Allocation alignment (1 for unaligned)
332 * Return: 0 if OK, -E2BIG if file is too large, -ENOMEM if out of memory,
333 * other -ve on other error
334 */
335int bootmeth_alloc_file(struct bootflow *bflow, uint size_limit, uint align);
336
337/**
Simon Glass24d8e1b2023-01-06 08:52:34 -0600338 * bootmeth_alloc_other() - Allocate and read a file for a bootflow
339 *
340 * This reads an arbitrary file in the same directory as the bootflow,
341 * allocating memory for it. The buffer is one byte larger than the file length,
342 * so that it can be nul-terminated.
343 *
344 * @bflow: Information about file to read
345 * @fname: Filename to read from (within bootflow->subdir)
346 * @bufp: Returns a pointer to the allocated buffer
347 * @sizep: Returns the size of the buffer
348 * Return: 0 if OK, -ENOMEM if out of memory, other -ve on other error
349 */
350int bootmeth_alloc_other(struct bootflow *bflow, const char *fname,
351 void **bufp, uint *sizep);
352
353/**
Simon Glassa950d312022-04-24 23:31:08 -0600354 * bootmeth_common_read_file() - Common handler for reading a file
355 *
356 * Reads a named file from the same location as the bootflow file.
357 *
358 * @dev: bootmeth device to read from
359 * @bflow: Bootflow information
360 * @file_path: Path to file
361 * @addr: Address to load file to
362 * @sizep: On entry, the maximum file size to accept, on exit the actual file
363 * size read
364 */
365int bootmeth_common_read_file(struct udevice *dev, struct bootflow *bflow,
366 const char *file_path, ulong addr, ulong *sizep);
367
Simon Glassbc06aa02022-07-30 15:52:21 -0600368/**
369 * bootmeth_get_bootflow() - Get a bootflow from a global bootmeth
370 *
371 * Check the bootmeth for a bootflow which can be used. In this case the
372 * bootmeth handles all bootdev selection, etc.
373 *
374 * @dev: bootmeth device to read from
375 * @bflow: Bootflow information
376 * @return 0 on success, -ve if a bootflow could not be found or had an error
377 */
378int bootmeth_get_bootflow(struct udevice *dev, struct bootflow *bflow);
379
Simon Glassa950d312022-04-24 23:31:08 -0600380#endif