]>
Commit | Line | Data |
---|---|---|
87a5d1b5 SG |
1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
2 | /* | |
3 | * Events provide a general-purpose way to react to / subscribe to changes | |
4 | * within U-Boot | |
5 | * | |
6 | * Copyright 2021 Google LLC | |
7 | * Written by Simon Glass <sjg@chromium.org> | |
8 | */ | |
9 | ||
10 | #ifndef __event_h | |
11 | #define __event_h | |
12 | ||
98887ab8 | 13 | #include <dm/ofnode_decl.h> |
a1190b4d | 14 | #include <linux/types.h> |
98887ab8 | 15 | |
87a5d1b5 SG |
16 | /** |
17 | * enum event_t - Types of events supported by U-Boot | |
18 | * | |
19 | * @EVT_DM_PRE_PROBE: Device is about to be probed | |
20 | */ | |
21 | enum event_t { | |
6a407076 HS |
22 | /** |
23 | * @EVT_NONE: This zero value is not used for events. | |
24 | */ | |
25 | EVT_NONE = 0, | |
26 | ||
27 | /** | |
28 | * @EVT_TEST: This event is used in unit tests. | |
29 | */ | |
87a5d1b5 SG |
30 | EVT_TEST, |
31 | ||
6a407076 HS |
32 | /** |
33 | * @EVT_DM_POST_INIT_F: | |
34 | * This event is triggered after pre-relocation initialization of the | |
35 | * driver model. Its parameter is NULL. | |
36 | * A non-zero return code from the event handler let's the boot process | |
37 | * fail. | |
38 | */ | |
55171aed | 39 | EVT_DM_POST_INIT_F, |
6a407076 HS |
40 | |
41 | /** | |
42 | * @EVT_DM_POST_INIT_R: | |
43 | * This event is triggered after post-relocation initialization of the | |
44 | * driver model. Its parameter is NULL. | |
45 | * A non-zero return code from the event handler let's the boot process | |
46 | * fail. | |
47 | */ | |
27c7a629 | 48 | EVT_DM_POST_INIT_R, |
6a407076 HS |
49 | |
50 | /** | |
51 | * @EVT_DM_PRE_PROBE: | |
52 | * This event is triggered before probing a device. Its parameter is the | |
53 | * device to be probed. | |
54 | * A non-zero return code from the event handler lets the device not | |
55 | * being probed. | |
56 | */ | |
5b896ed5 | 57 | EVT_DM_PRE_PROBE, |
6a407076 HS |
58 | |
59 | /** | |
60 | * @EVT_DM_POST_PROBE: | |
61 | * This event is triggered after probing a device. Its parameter is the | |
62 | * device that was probed. | |
63 | * A non-zero return code from the event handler leaves the device in | |
64 | * the unprobed state and therefore not usable. | |
65 | */ | |
5b896ed5 | 66 | EVT_DM_POST_PROBE, |
6a407076 HS |
67 | |
68 | /** | |
69 | * @EVT_DM_PRE_REMOVE: | |
70 | * This event is triggered after removing a device. Its parameter is | |
71 | * the device to be removed. | |
72 | * A non-zero return code from the event handler stops the removal of | |
73 | * the device before any changes. | |
74 | */ | |
5b896ed5 | 75 | EVT_DM_PRE_REMOVE, |
6a407076 HS |
76 | |
77 | /** | |
78 | * @EVT_DM_POST_REMOVE: | |
79 | * This event is triggered before removing a device. Its parameter is | |
80 | * the device that was removed. | |
81 | * A non-zero return code stops from the event handler the removal of | |
82 | * the device after all removal changes. The previous state is not | |
83 | * restored. All children will be gone and the device may not be | |
84 | * functional. | |
85 | */ | |
5b896ed5 SG |
86 | EVT_DM_POST_REMOVE, |
87 | ||
6a407076 HS |
88 | /** |
89 | * @EVT_MISC_INIT_F: | |
90 | * This event is triggered during the initialization sequence before | |
91 | * relocation. Its parameter is NULL. | |
92 | * A non-zero return code from the event handler let's the boot process | |
93 | * fail. | |
94 | */ | |
42fdcebf SG |
95 | EVT_MISC_INIT_F, |
96 | ||
b53ab971 TR |
97 | /** |
98 | * @EVT_FSP_INIT_F: | |
99 | * This event is triggered before relocation to set up Firmware Support | |
100 | * Package. | |
13a7db9a SG |
101 | * Where U-Boot relies on binary blobs to handle part of the system |
102 | * init, this event can be used to set up the blobs. This is used on | |
103 | * some Intel platforms | |
104 | */ | |
105 | EVT_FSP_INIT_F, | |
106 | ||
6092ce50 AR |
107 | /** |
108 | * @EVT_SETTINGS_R: | |
109 | * This event is triggered post-relocation and before console init. | |
110 | * This gives an option to perform any platform-dependent setup, which | |
111 | * needs to take place before show_board_info() (e.g. readout of EEPROM | |
112 | * stored settings). | |
113 | */ | |
114 | EVT_SETTINGS_R, | |
115 | ||
b53ab971 TR |
116 | /** |
117 | * @EVT_LAST_STAGE_INIT: | |
118 | * This event is triggered just before jumping to the main loop. | |
91caa3bb SG |
119 | * Some boards need to perform initialisation immediately before control |
120 | * is passed to the command-line interpreter (e.g. for init that depend | |
121 | * on later phases in the init sequence). | |
122 | * | |
123 | * Some parts can be only initialized if all others (like Interrupts) | |
124 | * are up and running (e.g. the PC-style ISA keyboard). | |
125 | */ | |
126 | EVT_LAST_STAGE_INIT, | |
127 | ||
6a407076 HS |
128 | /** |
129 | * @EVT_FPGA_LOAD: | |
130 | * The FPGA load hook is called after loading an FPGA with a new binary. | |
131 | * Its parameter is of type struct event_fpga_load and contains | |
132 | * information about the loaded image. | |
133 | */ | |
a1190b4d CT |
134 | EVT_FPGA_LOAD, |
135 | ||
6a407076 HS |
136 | /** |
137 | * @EVT_FT_FIXUP: | |
138 | * This event is triggered during device-tree fix up after all | |
139 | * other device-tree fixups have been executed. | |
140 | * Its parameter is of type struct event_ft_fixup which contains | |
141 | * the address of the device-tree to fix up and the list of images to be | |
142 | * booted. | |
143 | * A non-zero return code from the event handler let's booting the | |
144 | * images fail. | |
145 | */ | |
98887ab8 SG |
146 | EVT_FT_FIXUP, |
147 | ||
6a407076 HS |
148 | /** |
149 | * @EVT_MAIN_LOOP: | |
150 | * This event is triggered immediately before calling main_loop() which | |
151 | * is the entry point of the command line. Its parameter is NULL. | |
152 | * A non-zero return value causes the boot to fail. | |
153 | */ | |
467bad5e SG |
154 | EVT_MAIN_LOOP, |
155 | ||
6a407076 HS |
156 | /** |
157 | * @EVT_COUNT: | |
158 | * This constants holds the maximum event number + 1 and is used when | |
159 | * looping over all event classes. | |
160 | */ | |
87a5d1b5 SG |
161 | EVT_COUNT |
162 | }; | |
163 | ||
164 | union event_data { | |
165 | /** | |
166 | * struct event_data_test - test data | |
167 | * | |
168 | * @signal: A value to update the state with | |
169 | */ | |
170 | struct event_data_test { | |
171 | int signal; | |
172 | } test; | |
5b896ed5 SG |
173 | |
174 | /** | |
175 | * struct event_dm - driver model event | |
176 | * | |
177 | * @dev: Device this event relates to | |
178 | */ | |
179 | struct event_dm { | |
180 | struct udevice *dev; | |
181 | } dm; | |
98887ab8 | 182 | |
a1190b4d CT |
183 | /** |
184 | * struct event_fpga_load - fpga load event | |
185 | * | |
186 | * @buf: The buffer that was loaded into the fpga | |
187 | * @bsize: The size of the buffer that was loaded into the fpga | |
188 | * @result: Result of the load operation | |
189 | */ | |
190 | struct event_fpga_load { | |
191 | const void *buf; | |
192 | size_t bsize; | |
193 | int result; | |
194 | } fpga_load; | |
195 | ||
98887ab8 SG |
196 | /** |
197 | * struct event_ft_fixup - FDT fixup before booting | |
198 | * | |
199 | * @tree: tree to update | |
b215b603 | 200 | * @images: images which are being booted |
98887ab8 SG |
201 | */ |
202 | struct event_ft_fixup { | |
203 | oftree tree; | |
b215b603 | 204 | struct bootm_headers *images; |
98887ab8 | 205 | } ft_fixup; |
87a5d1b5 SG |
206 | }; |
207 | ||
208 | /** | |
209 | * struct event - an event that can be sent and received | |
210 | * | |
211 | * @type: Event type | |
212 | * @data: Data for this particular event | |
213 | */ | |
214 | struct event { | |
215 | enum event_t type; | |
216 | union event_data data; | |
217 | }; | |
218 | ||
ba5e3e1e SG |
219 | /* Flags for event spy */ |
220 | enum evspy_flags { | |
221 | EVSPYF_SIMPLE = 1 << 0, | |
222 | }; | |
223 | ||
87a5d1b5 SG |
224 | /** Function type for event handlers */ |
225 | typedef int (*event_handler_t)(void *ctx, struct event *event); | |
226 | ||
ba5e3e1e SG |
227 | /** Function type for simple event handlers */ |
228 | typedef int (*event_handler_simple_t)(void); | |
229 | ||
87a5d1b5 SG |
230 | /** |
231 | * struct evspy_info - information about an event spy | |
232 | * | |
233 | * @func: Function to call when the event is activated (must be first) | |
234 | * @type: Event type | |
b53ab971 | 235 | * @flags: Flags for this spy |
87a5d1b5 SG |
236 | * @id: Event id string |
237 | */ | |
238 | struct evspy_info { | |
239 | event_handler_t func; | |
ba5e3e1e SG |
240 | u8 type; |
241 | u8 flags; | |
242 | #if CONFIG_IS_ENABLED(EVENT_DEBUG) | |
243 | const char *id; | |
244 | #endif | |
245 | }; | |
246 | ||
247 | /** | |
248 | * struct evspy_info_simple - information about an event spy | |
249 | * | |
250 | * THis is the 'simple' record, the only difference being the handler function | |
251 | * | |
252 | * @func: Function to call when the event is activated (must be first) | |
253 | * @type: Event type | |
b53ab971 | 254 | * @flags: Flags for this spy |
ba5e3e1e SG |
255 | * @id: Event id string |
256 | */ | |
257 | struct evspy_info_simple { | |
258 | event_handler_simple_t func; | |
259 | u8 type; | |
260 | u8 flags; | |
87a5d1b5 SG |
261 | #if CONFIG_IS_ENABLED(EVENT_DEBUG) |
262 | const char *id; | |
263 | #endif | |
264 | }; | |
265 | ||
266 | /* Declare a new event spy */ | |
267 | #if CONFIG_IS_ENABLED(EVENT_DEBUG) | |
ba5e3e1e SG |
268 | #define _ESPY_REC(_type, _func) { _func, _type, 0, #_func, } |
269 | #define _ESPY_REC_SIMPLE(_type, _func) { _func, _type, EVSPYF_SIMPLE, #_func, } | |
87a5d1b5 SG |
270 | #else |
271 | #define _ESPY_REC(_type, _func) { _func, _type, } | |
ba5e3e1e | 272 | #define _ESPY_REC_SIMPLE(_type, _func) { _func, _type, EVSPYF_SIMPLE } |
87a5d1b5 SG |
273 | #endif |
274 | ||
275 | static inline const char *event_spy_id(struct evspy_info *spy) | |
276 | { | |
277 | #if CONFIG_IS_ENABLED(EVENT_DEBUG) | |
278 | return spy->id; | |
279 | #else | |
280 | return "?"; | |
281 | #endif | |
282 | } | |
283 | ||
284 | /* | |
285 | * It seems that LTO will drop list entries if it decides they are not used, | |
286 | * although the conditions that cause this are unclear. | |
287 | * | |
288 | * The example found is the following: | |
289 | * | |
290 | * static int sandbox_misc_init_f(void *ctx, struct event *event) | |
291 | * { | |
292 | * return sandbox_early_getopt_check(); | |
293 | * } | |
e65f6ba0 | 294 | * EVENT_SPY_FULL(EVT_MISC_INIT_F, sandbox_misc_init_f); |
87a5d1b5 | 295 | * |
e65f6ba0 | 296 | * where EVENT_SPY_FULL uses ll_entry_declare() |
87a5d1b5 SG |
297 | * |
298 | * In this case, LTO decides to drop the sandbox_misc_init_f() function | |
299 | * (which is fine) but then drops the linker-list entry too. This means | |
300 | * that the code no longer works, in this case sandbox no-longer checks its | |
301 | * command-line arguments properly. | |
302 | * | |
303 | * Without LTO, the KEEP() command in the .lds file is enough to keep the | |
304 | * entry around. But with LTO it seems that the entry has already been | |
305 | * dropped before the link script is considered. | |
306 | * | |
307 | * The only solution I can think of is to mark linker-list entries as 'used' | |
308 | * using an attribute. This should be safe, since we don't actually want to drop | |
309 | * any of these. However this does slightly limit LTO's optimisation choices. | |
56952474 SG |
310 | * |
311 | * Another issue has come up, only with clang: using 'static' makes it throw | |
312 | * away the linker-list entry sometimes, e.g. with the EVT_FT_FIXUP entry in | |
313 | * vbe_simple.c - so for now, make it global. | |
87a5d1b5 | 314 | */ |
6c4cad74 | 315 | #define EVENT_SPY_FULL(_type, _func) \ |
b5001cb4 SG |
316 | __used ll_entry_declare(struct evspy_info, _type ## _3_ ## _func, \ |
317 | evspy_info) = _ESPY_REC(_type, _func) | |
87a5d1b5 | 318 | |
ba5e3e1e SG |
319 | /* Simple spy with no function arguemnts */ |
320 | #define EVENT_SPY_SIMPLE(_type, _func) \ | |
321 | __used ll_entry_declare(struct evspy_info_simple, \ | |
322 | _type ## _3_ ## _func, \ | |
323 | evspy_info) = _ESPY_REC_SIMPLE(_type, _func) | |
324 | ||
87a5d1b5 SG |
325 | /** |
326 | * event_register - register a new spy | |
327 | * | |
328 | * @id: Spy ID | |
329 | * @type: Event type to subscribe to | |
330 | * @func: Function to call when the event is sent | |
331 | * @ctx: Context to pass to the function | |
332 | * @return 0 if OK, -ve on error | |
333 | */ | |
334 | int event_register(const char *id, enum event_t type, event_handler_t func, | |
335 | void *ctx); | |
336 | ||
c81b460c SG |
337 | /** event_show_spy_list( - Show a list of event spies */ |
338 | void event_show_spy_list(void); | |
339 | ||
fb7dfca2 SG |
340 | /** |
341 | * event_type_name() - Get the name of an event type | |
342 | * | |
343 | * @type: Type to check | |
344 | * Return: Name of event, or "(unknown)" if not known | |
345 | */ | |
346 | const char *event_type_name(enum event_t type); | |
347 | ||
87a5d1b5 SG |
348 | /** |
349 | * event_notify() - notify spies about an event | |
350 | * | |
351 | * It is possible to pass in union event_data here but that may not be | |
352 | * convenient if the data is elsewhere, or is one of the members of the union. | |
353 | * So this uses a void * for @data, with a separate @size. | |
354 | * | |
355 | * @type: Event type | |
356 | * @data: Event data to be sent (e.g. union_event_data) | |
357 | * @size: Size of data in bytes | |
358 | * @return 0 if OK, -ve on error | |
359 | */ | |
360 | int event_notify(enum event_t type, void *data, int size); | |
361 | ||
c5ef2025 | 362 | #if CONFIG_IS_ENABLED(EVENT) |
87a5d1b5 SG |
363 | /** |
364 | * event_notify_null() - notify spies about an event | |
365 | * | |
366 | * Data is NULL and the size is 0 | |
367 | * | |
368 | * @type: Event type | |
369 | * @return 0 if OK, -ve on error | |
370 | */ | |
371 | int event_notify_null(enum event_t type); | |
372 | #else | |
87a5d1b5 SG |
373 | static inline int event_notify_null(enum event_t type) |
374 | { | |
375 | return 0; | |
376 | } | |
377 | #endif | |
378 | ||
379 | #if CONFIG_IS_ENABLED(EVENT_DYNAMIC) | |
380 | /** | |
381 | * event_uninit() - Clean up dynamic events | |
382 | * | |
383 | * This removes all dynamic event handlers | |
384 | */ | |
385 | int event_uninit(void); | |
386 | ||
387 | /** | |
388 | * event_uninit() - Set up dynamic events | |
389 | * | |
390 | * Init a list of dynamic event handlers, so that these can be added as | |
391 | * needed | |
392 | */ | |
393 | int event_init(void); | |
394 | #else | |
395 | static inline int event_uninit(void) | |
396 | { | |
397 | return 0; | |
398 | } | |
399 | ||
400 | static inline int event_init(void) | |
401 | { | |
402 | return 0; | |
403 | } | |
404 | #endif | |
405 | ||
406 | #endif |