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
13 #include <dm/ofnode_decl.h>
14 #include <linux/types.h>
15
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 {
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 */
30 EVT_TEST,
31
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 */
39 EVT_DM_POST_INIT_F,
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 */
48 EVT_DM_POST_INIT_R,
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 */
57 EVT_DM_PRE_PROBE,
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 */
66 EVT_DM_POST_PROBE,
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 */
75 EVT_DM_PRE_REMOVE,
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 */
86 EVT_DM_POST_REMOVE,
87
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 */
95 EVT_MISC_INIT_F,
96
97 /**
98 * @EVT_FSP_INIT_F:
99 * This event is triggered before relocation to set up Firmware Support
100 * Package.
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
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
116 /**
117 * @EVT_LAST_STAGE_INIT:
118 * This event is triggered just before jumping to the main loop.
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
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 */
134 EVT_FPGA_LOAD,
135
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 */
146 EVT_FT_FIXUP,
147
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 */
154 EVT_MAIN_LOOP,
155
156 /**
157 * @EVT_OF_LIVE_BUILT:
158 * This event is triggered immediately after the live device tree has been
159 * built. This allows for machine specific fixups to be done to the live tree
160 * (like disabling known-unsupported devices) before it is used. This
161 * event is only available if OF_LIVE is enabled and is only used after relocation.
162 */
163 EVT_OF_LIVE_BUILT,
164
165 /**
166 * @EVT_COUNT:
167 * This constants holds the maximum event number + 1 and is used when
168 * looping over all event classes.
169 */
170 EVT_COUNT
171 };
172
173 union event_data {
174 /**
175 * struct event_data_test - test data
176 *
177 * @signal: A value to update the state with
178 */
179 struct event_data_test {
180 int signal;
181 } test;
182
183 /**
184 * struct event_dm - driver model event
185 *
186 * @dev: Device this event relates to
187 */
188 struct event_dm {
189 struct udevice *dev;
190 } dm;
191
192 /**
193 * struct event_fpga_load - fpga load event
194 *
195 * @buf: The buffer that was loaded into the fpga
196 * @bsize: The size of the buffer that was loaded into the fpga
197 * @result: Result of the load operation
198 */
199 struct event_fpga_load {
200 const void *buf;
201 size_t bsize;
202 int result;
203 } fpga_load;
204
205 /**
206 * struct event_ft_fixup - FDT fixup before booting
207 *
208 * @tree: tree to update
209 * @images: images which are being booted
210 */
211 struct event_ft_fixup {
212 oftree tree;
213 struct bootm_headers *images;
214 } ft_fixup;
215
216 /**
217 * struct event_of_live_built - livetree has been built
218 *
219 * @root: The root node of the live device tree
220 */
221 struct event_of_live_built {
222 struct device_node *root;
223 } of_live_built;
224 };
225
226 /**
227 * struct event - an event that can be sent and received
228 *
229 * @type: Event type
230 * @data: Data for this particular event
231 */
232 struct event {
233 enum event_t type;
234 union event_data data;
235 };
236
237 /* Flags for event spy */
238 enum evspy_flags {
239 EVSPYF_SIMPLE = 1 << 0,
240 };
241
242 /** Function type for event handlers */
243 typedef int (*event_handler_t)(void *ctx, struct event *event);
244
245 /** Function type for simple event handlers */
246 typedef int (*event_handler_simple_t)(void);
247
248 /**
249 * struct evspy_info - information about an event spy
250 *
251 * @func: Function to call when the event is activated (must be first)
252 * @type: Event type
253 * @flags: Flags for this spy
254 * @id: Event id string
255 */
256 struct evspy_info {
257 event_handler_t func;
258 u8 type;
259 u8 flags;
260 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
261 const char *id;
262 #endif
263 };
264
265 /**
266 * struct evspy_info_simple - information about an event spy
267 *
268 * THis is the 'simple' record, the only difference being the handler function
269 *
270 * @func: Function to call when the event is activated (must be first)
271 * @type: Event type
272 * @flags: Flags for this spy
273 * @id: Event id string
274 */
275 struct evspy_info_simple {
276 event_handler_simple_t func;
277 u8 type;
278 u8 flags;
279 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
280 const char *id;
281 #endif
282 };
283
284 /* Declare a new event spy */
285 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
286 #define _ESPY_REC(_type, _func) { _func, _type, 0, #_func, }
287 #define _ESPY_REC_SIMPLE(_type, _func) { _func, _type, EVSPYF_SIMPLE, #_func, }
288 #else
289 #define _ESPY_REC(_type, _func) { _func, _type, }
290 #define _ESPY_REC_SIMPLE(_type, _func) { _func, _type, EVSPYF_SIMPLE }
291 #endif
292
event_spy_id(struct evspy_info * spy)293 static inline const char *event_spy_id(struct evspy_info *spy)
294 {
295 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
296 return spy->id;
297 #else
298 return "?";
299 #endif
300 }
301
302 /*
303 * It seems that LTO will drop list entries if it decides they are not used,
304 * although the conditions that cause this are unclear.
305 *
306 * The example found is the following:
307 *
308 * static int sandbox_misc_init_f(void *ctx, struct event *event)
309 * {
310 * return sandbox_early_getopt_check();
311 * }
312 * EVENT_SPY_FULL(EVT_MISC_INIT_F, sandbox_misc_init_f);
313 *
314 * where EVENT_SPY_FULL uses ll_entry_declare()
315 *
316 * In this case, LTO decides to drop the sandbox_misc_init_f() function
317 * (which is fine) but then drops the linker-list entry too. This means
318 * that the code no longer works, in this case sandbox no-longer checks its
319 * command-line arguments properly.
320 *
321 * Without LTO, the KEEP() command in the .lds file is enough to keep the
322 * entry around. But with LTO it seems that the entry has already been
323 * dropped before the link script is considered.
324 *
325 * The only solution I can think of is to mark linker-list entries as 'used'
326 * using an attribute. This should be safe, since we don't actually want to drop
327 * any of these. However this does slightly limit LTO's optimisation choices.
328 *
329 * Another issue has come up, only with clang: using 'static' makes it throw
330 * away the linker-list entry sometimes, e.g. with the EVT_FT_FIXUP entry in
331 * vbe_simple.c - so for now, make it global.
332 */
333 #define EVENT_SPY_FULL(_type, _func) \
334 __used ll_entry_declare(struct evspy_info, _type ## _3_ ## _func, \
335 evspy_info) = _ESPY_REC(_type, _func)
336
337 /* Simple spy with no function arguments */
338 #define EVENT_SPY_SIMPLE(_type, _func) \
339 __used ll_entry_declare(struct evspy_info_simple, \
340 _type ## _3_ ## _func, \
341 evspy_info) = _ESPY_REC_SIMPLE(_type, _func)
342
343 /**
344 * event_register - register a new spy
345 *
346 * @id: Spy ID
347 * @type: Event type to subscribe to
348 * @func: Function to call when the event is sent
349 * @ctx: Context to pass to the function
350 * @return 0 if OK, -ve on error
351 */
352 int event_register(const char *id, enum event_t type, event_handler_t func,
353 void *ctx);
354
355 /** event_show_spy_list( - Show a list of event spies */
356 void event_show_spy_list(void);
357
358 /**
359 * event_type_name() - Get the name of an event type
360 *
361 * @type: Type to check
362 * Return: Name of event, or "(unknown)" if not known
363 */
364 const char *event_type_name(enum event_t type);
365
366 /**
367 * event_notify() - notify spies about an event
368 *
369 * It is possible to pass in union event_data here but that may not be
370 * convenient if the data is elsewhere, or is one of the members of the union.
371 * So this uses a void * for @data, with a separate @size.
372 *
373 * @type: Event type
374 * @data: Event data to be sent (e.g. union_event_data)
375 * @size: Size of data in bytes
376 * @return 0 if OK, -ve on error
377 */
378 int event_notify(enum event_t type, void *data, int size);
379
380 #if CONFIG_IS_ENABLED(EVENT)
381 /**
382 * event_notify_null() - notify spies about an event
383 *
384 * Data is NULL and the size is 0
385 *
386 * @type: Event type
387 * @return 0 if OK, -ve on error
388 */
389 int event_notify_null(enum event_t type);
390 #else
event_notify_null(enum event_t type)391 static inline int event_notify_null(enum event_t type)
392 {
393 return 0;
394 }
395 #endif
396
397 #if CONFIG_IS_ENABLED(EVENT_DYNAMIC)
398 /**
399 * event_uninit() - Clean up dynamic events
400 *
401 * This removes all dynamic event handlers
402 */
403 int event_uninit(void);
404
405 /**
406 * event_init() - Set up dynamic events
407 *
408 * Init a list of dynamic event handlers, so that these can be added as
409 * needed
410 */
411 int event_init(void);
412 #else
event_uninit(void)413 static inline int event_uninit(void)
414 {
415 return 0;
416 }
417
event_init(void)418 static inline int event_init(void)
419 {
420 return 0;
421 }
422 #endif
423
424 #endif
425