aboutsummaryrefslogtreecommitdiff
path: root/include/bootmeth.h
blob: 669b14ce81e6de130e34b212b199ac9f33205a05 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
/* SPDX-License-Identifier: GPL-2.0+ */
/*
 * Copyright 2021 Google LLC
 * Written by Simon Glass <sjg@chromium.org>
 */

#ifndef __bootmeth_h
#define __bootmeth_h

struct blk_desc;
struct bootflow;
struct bootflow_iter;
struct udevice;

/**
 * enum bootmeth_flags - Flags for bootmeths
 *
 * @BOOTMETHF_GLOBAL: bootmeth handles bootdev selection automatically
 */
enum bootmeth_flags {
	BOOTMETHF_GLOBAL	= BIT(0),
};

/**
 * struct bootmeth_uc_plat - information the uclass keeps about each bootmeth
 *
 * @desc: A long description of the bootmeth
 * @flags: Flags for this bootmeth (enum bootmeth_flags)
 */
struct bootmeth_uc_plat {
	const char *desc;
	int flags;
};

/** struct bootmeth_ops - Operations for boot methods */
struct bootmeth_ops {
	/**
	 * get_state_desc() - get detailed state information
	 *
	 * Prodecues a textual description of the state of the bootmeth. This
	 * can include newline characters if it extends to multiple lines. It
	 * must be a nul-terminated string.
	 *
	 * This may involve reading state from the system, e.g. some data in
	 * the firmware area.
	 *
	 * @dev:	Bootmethod device to check
	 * @buf:	Buffer to place the info in (terminator must fit)
	 * @maxsize:	Size of buffer
	 * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if
	 * something else went wrong
	 */
	int (*get_state_desc)(struct udevice *dev, char *buf, int maxsize);

	/**
	 * check_supported() - check if a bootmeth supports this bootdev
	 *
	 * This is optional. If not provided, the bootdev is assumed to be
	 * supported
	 *
	 * The bootmeth can check the bootdev (e.g. to make sure it is a
	 * network device) or the partition information. The following fields
	 * in @iter are available:
	 *
	 *   name, dev, state, part
	 *   max_part may be set if part != 0 (i.e. there is a valid partition
	 *      table). Otherwise max_part is 0
	 *   method is available but is the same as @dev
	 *   the partition has not yet been read, nor has the filesystem been
	 *   checked
	 *
	 * It may update only the flags in @iter
	 *
	 * @dev:	Bootmethod device to check against
	 * @iter:	On entry, provides bootdev, hwpart, part
	 * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported
	 */
	int (*check)(struct udevice *dev, struct bootflow_iter *iter);

	/**
	 * read_bootflow() - read a bootflow for a device
	 *
	 * @dev:	Bootmethod device to use
	 * @bflow:	On entry, provides dev, hwpart, part and method.
	 *	Returns updated bootflow if found
	 * Return: 0 if OK, -ve on error
	 */
	int (*read_bootflow)(struct udevice *dev, struct bootflow *bflow);

	/**
	 * read_file() - read a file needed for a bootflow
	 *
	 * Read a file from the same place as the bootflow came from
	 *
	 * @dev:	Bootmethod device to use
	 * @bflow:	Bootflow providing info on where to read from
	 * @file_path:	Path to file (may be absolute or relative)
	 * @addr:	Address to load file
	 * @sizep:	On entry provides the maximum permitted size; on exit
	 *		returns the size of the file
	 * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other
	 *	-ve value if something else goes wrong
	 */
	int (*read_file)(struct udevice *dev, struct bootflow *bflow,
			 const char *file_path, ulong addr, ulong *sizep);

	/**
	 * boot() - boot a bootflow
	 *
	 * @dev:	Bootmethod device to boot
	 * @bflow:	Bootflow to boot
	 * Return: does not return on success, since it should boot the
	 *	Operating Systemn. Returns -EFAULT if that fails, -ENOTSUPP if
	 *	trying method resulted in finding out that is not actually
	 *	supported for this boot and should not be tried again unless
	 *	something changes, other -ve on other error
	 */
	int (*boot)(struct udevice *dev, struct bootflow *bflow);
};

#define bootmeth_get_ops(dev)  ((struct bootmeth_ops *)(dev)->driver->ops)

/**
 * bootmeth_get_state_desc() - get detailed state information
 *
 * Prodecues a textual description of the state of the bootmeth. This
 * can include newline characters if it extends to multiple lines. It
 * must be a nul-terminated string.
 *
 * This may involve reading state from the system, e.g. some data in
 * the firmware area.
 *
 * @dev:	Bootmethod device to check
 * @buf:	Buffer to place the info in (terminator must fit)
 * @maxsize:	Size of buffer
 * Returns: 0 if OK, -ENOSPC is buffer is too small, other -ve error if
 * something else went wrong
 */
int bootmeth_get_state_desc(struct udevice *dev, char *buf, int maxsize);

/**
 * bootmeth_check() - check if a bootmeth supports this bootflow
 *
 * This is optional. If not provided, the bootdev is assumed to be
 * supported
 *
 * The bootmeth can check the bootdev (e.g. to make sure it is a
 * network device) or the partition information. The following fields
 * in @iter are available:
 *
 *   name, dev, state, part
 *   max_part may be set if part != 0 (i.e. there is a valid partition
 *      table). Otherwise max_part is 0
 *   method is available but is the same as @dev
 *   the partition has not yet been read, nor has the filesystem been
 *   checked
 *
 * It may update only the flags in @iter
 *
 * @dev:	Bootmethod device to check against
 * @iter:	On entry, provides bootdev, hwpart, part
 * Return: 0 if OK, -ENOTSUPP if this bootdev is not supported
 */
int bootmeth_check(struct udevice *dev, struct bootflow_iter *iter);

/**
 * bootmeth_read_bootflow() - set up a bootflow for a device
 *
 * @dev:	Bootmethod device to check
 * @bflow:	On entry, provides dev, hwpart, part and method.
 *	Returns updated bootflow if found
 * Return: 0 if OK, -ve on error
 */
int bootmeth_read_bootflow(struct udevice *dev, struct bootflow *bflow);

/**
 * bootmeth_read_file() - read a file needed for a bootflow
 *
 * Read a file from the same place as the bootflow came from
 *
 * @dev:	Bootmethod device to use
 * @bflow:	Bootflow providing info on where to read from
 * @file_path:	Path to file (may be absolute or relative)
 * @addr:	Address to load file
 * @sizep:	On entry provides the maximum permitted size; on exit
 *		returns the size of the file
 * Return: 0 if OK, -ENOSPC if the file is too large for @sizep, other
 *	-ve value if something else goes wrong
 */
int bootmeth_read_file(struct udevice *dev, struct bootflow *bflow,
		       const char *file_path, ulong addr, ulong *sizep);

/**
 * bootmeth_boot() - boot a bootflow
 *
 * @dev:	Bootmethod device to boot
 * @bflow:	Bootflow to boot
 * Return: does not return on success, since it should boot the
 *	Operating Systemn. Returns -EFAULT if that fails, other -ve on
 *	other error
 */
int bootmeth_boot(struct udevice *dev, struct bootflow *bflow);

/**
 * bootmeth_setup_iter_order() - Set up the ordering of bootmeths to scan
 *
 * This sets up the ordering information in @iter, based on the selected
 * ordering of the bootmethds in bootstd_priv->bootmeth_order. If there is no
 * ordering there, then all bootmethods are added
 *
 * @iter: Iterator to update with the order
 * @include_global: true to add the global bootmeths, in which case they appear
 * first
 * Return: 0 if OK, -ENOENT if no bootdevs, -ENOMEM if out of memory, other -ve
 *	on other error
 */
int bootmeth_setup_iter_order(struct bootflow_iter *iter, bool include_global);

/**
 * bootmeth_set_order() - Set the bootmeth order
 *
 * This selects the ordering to use for bootmeths
 *
 * @order_str: String containing the ordering. This is a comma-separate list of
 * bootmeth-device names, e.g. "syslinux,efi". If empty then a default ordering
 * is used, based on the sequence number of devices (i.e. using aliases)
 * Return: 0 if OK, -ENODEV if an unknown bootmeth is mentioned, -ENOMEM if
 * out of memory, -ENOENT if there are no bootmeth devices
 */
int bootmeth_set_order(const char *order_str);

/**
 * bootmeth_try_file() - See we can access a given file
 *
 * Check for a file with a given name. If found, the filename is allocated in
 * @bflow
 *
 * Sets the state to BOOTFLOWST_FILE on success. It also calls
 * fs_set_blk_dev_with_part() so that this does not need to be done by the
 * caller before reading the file.
 *
 * @bflow: Information about file to try
 * @desc: Block descriptor to read from
 * @prefix: Filename prefix to prepend to @fname (NULL for none)
 * @fname: Filename to read
 * Return: 0 if OK, -ENOMEM if not enough memory to allocate bflow->fname,
 * other -ve value on other error
 */
int bootmeth_try_file(struct bootflow *bflow, struct blk_desc *desc,
		      const char *prefix, const char *fname);

/**
 * bootmeth_alloc_file() - Allocate and read a bootflow file
 *
 * Allocates memory for a bootflow file and reads it in. Sets the state to
 * BOOTFLOWST_READY on success
 *
 * Note that fs_set_blk_dev_with_part() must have been called previously.
 *
 * @bflow: Information about file to read
 * @size_limit: Maximum file size to permit
 * @align: Allocation alignment (1 for unaligned)
 * Return: 0 if OK, -E2BIG if file is too large, -ENOMEM if out of memory,
 *	other -ve on other error
 */
int bootmeth_alloc_file(struct bootflow *bflow, uint size_limit, uint align);

/**
 * bootmeth_alloc_other() - Allocate and read a file for a bootflow
 *
 * This reads an arbitrary file in the same directory as the bootflow,
 * allocating memory for it. The buffer is one byte larger than the file length,
 * so that it can be nul-terminated.
 *
 * @bflow: Information about file to read
 * @fname: Filename to read from (within bootflow->subdir)
 * @bufp: Returns a pointer to the allocated buffer
 * @sizep: Returns the size of the buffer
 * Return: 0 if OK,  -ENOMEM if out of memory, other -ve on other error
 */
int bootmeth_alloc_other(struct bootflow *bflow, const char *fname,
			 void **bufp, uint *sizep);

/**
 * bootmeth_common_read_file() - Common handler for reading a file
 *
 * Reads a named file from the same location as the bootflow file.
 *
 * @dev: bootmeth device to read from
 * @bflow: Bootflow information
 * @file_path: Path to file
 * @addr: Address to load file to
 * @sizep: On entry, the maximum file size to accept, on exit the actual file
 *	size read
 */
int bootmeth_common_read_file(struct udevice *dev, struct bootflow *bflow,
			      const char *file_path, ulong addr, ulong *sizep);

/**
 * bootmeth_get_bootflow() - Get a bootflow from a global bootmeth
 *
 * Check the bootmeth for a bootflow which can be used. In this case the
 * bootmeth handles all bootdev selection, etc.
 *
 * @dev: bootmeth device to read from
 * @bflow: Bootflow information
 * @return 0 on success, -ve if a bootflow could not be found or had an error
 */
int bootmeth_get_bootflow(struct udevice *dev, struct bootflow *bflow);

#endif