blob: fe41080fa63b5918524dcc77781be954399fd242 [file] [log] [blame]
Simon Glass87a5d1b2022-03-04 08:43:00 -07001/* 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
Simon Glass98887ab2022-07-30 15:52:31 -060013#include <dm/ofnode_decl.h>
14
Simon Glass87a5d1b2022-03-04 08:43:00 -070015/**
16 * enum event_t - Types of events supported by U-Boot
17 *
18 * @EVT_DM_PRE_PROBE: Device is about to be probed
19 */
20enum event_t {
21 EVT_NONE,
22 EVT_TEST,
23
Simon Glass5b896ed2022-03-04 08:43:03 -070024 /* Events related to driver model */
Simon Glass55171ae2023-05-04 16:50:45 -060025 EVT_DM_POST_INIT_F,
Simon Glass5b896ed2022-03-04 08:43:03 -070026 EVT_DM_PRE_PROBE,
27 EVT_DM_POST_PROBE,
28 EVT_DM_PRE_REMOVE,
29 EVT_DM_POST_REMOVE,
30
Simon Glass42fdceb2022-03-04 08:43:04 -070031 /* Init hooks */
32 EVT_MISC_INIT_F,
33
Simon Glass98887ab2022-07-30 15:52:31 -060034 /* Device tree fixups before booting */
35 EVT_FT_FIXUP,
36
Sughosh Ganu467bad52022-10-21 18:16:01 +053037 /* To be called once, before calling main_loop() */
38 EVT_MAIN_LOOP,
39
Simon Glass87a5d1b2022-03-04 08:43:00 -070040 EVT_COUNT
41};
42
43union event_data {
44 /**
45 * struct event_data_test - test data
46 *
47 * @signal: A value to update the state with
48 */
49 struct event_data_test {
50 int signal;
51 } test;
Simon Glass5b896ed2022-03-04 08:43:03 -070052
53 /**
54 * struct event_dm - driver model event
55 *
56 * @dev: Device this event relates to
57 */
58 struct event_dm {
59 struct udevice *dev;
60 } dm;
Simon Glass98887ab2022-07-30 15:52:31 -060061
62 /**
63 * struct event_ft_fixup - FDT fixup before booting
64 *
65 * @tree: tree to update
Simon Glassb215b602022-09-06 20:26:58 -060066 * @images: images which are being booted
Simon Glass98887ab2022-07-30 15:52:31 -060067 */
68 struct event_ft_fixup {
69 oftree tree;
Simon Glassb215b602022-09-06 20:26:58 -060070 struct bootm_headers *images;
Simon Glass98887ab2022-07-30 15:52:31 -060071 } ft_fixup;
Simon Glass87a5d1b2022-03-04 08:43:00 -070072};
73
74/**
75 * struct event - an event that can be sent and received
76 *
77 * @type: Event type
78 * @data: Data for this particular event
79 */
80struct event {
81 enum event_t type;
82 union event_data data;
83};
84
85/** Function type for event handlers */
86typedef int (*event_handler_t)(void *ctx, struct event *event);
87
88/**
89 * struct evspy_info - information about an event spy
90 *
91 * @func: Function to call when the event is activated (must be first)
92 * @type: Event type
93 * @id: Event id string
94 */
95struct evspy_info {
96 event_handler_t func;
97 enum event_t type;
98#if CONFIG_IS_ENABLED(EVENT_DEBUG)
99 const char *id;
100#endif
101};
102
103/* Declare a new event spy */
104#if CONFIG_IS_ENABLED(EVENT_DEBUG)
105#define _ESPY_REC(_type, _func) { _func, _type, #_func, }
106#else
107#define _ESPY_REC(_type, _func) { _func, _type, }
108#endif
109
110static inline const char *event_spy_id(struct evspy_info *spy)
111{
112#if CONFIG_IS_ENABLED(EVENT_DEBUG)
113 return spy->id;
114#else
115 return "?";
116#endif
117}
118
119/*
120 * It seems that LTO will drop list entries if it decides they are not used,
121 * although the conditions that cause this are unclear.
122 *
123 * The example found is the following:
124 *
125 * static int sandbox_misc_init_f(void *ctx, struct event *event)
126 * {
127 * return sandbox_early_getopt_check();
128 * }
129 * EVENT_SPY(EVT_MISC_INIT_F, sandbox_misc_init_f);
130 *
131 * where EVENT_SPY uses ll_entry_declare()
132 *
133 * In this case, LTO decides to drop the sandbox_misc_init_f() function
134 * (which is fine) but then drops the linker-list entry too. This means
135 * that the code no longer works, in this case sandbox no-longer checks its
136 * command-line arguments properly.
137 *
138 * Without LTO, the KEEP() command in the .lds file is enough to keep the
139 * entry around. But with LTO it seems that the entry has already been
140 * dropped before the link script is considered.
141 *
142 * The only solution I can think of is to mark linker-list entries as 'used'
143 * using an attribute. This should be safe, since we don't actually want to drop
144 * any of these. However this does slightly limit LTO's optimisation choices.
Simon Glass56952472022-07-30 15:52:30 -0600145 *
146 * Another issue has come up, only with clang: using 'static' makes it throw
147 * away the linker-list entry sometimes, e.g. with the EVT_FT_FIXUP entry in
148 * vbe_simple.c - so for now, make it global.
Simon Glass87a5d1b2022-03-04 08:43:00 -0700149 */
150#define EVENT_SPY(_type, _func) \
Simon Glassb5001cb2022-09-06 20:26:56 -0600151 __used ll_entry_declare(struct evspy_info, _type ## _3_ ## _func, \
152 evspy_info) = _ESPY_REC(_type, _func)
Simon Glass87a5d1b2022-03-04 08:43:00 -0700153
154/**
155 * event_register - register a new spy
156 *
157 * @id: Spy ID
158 * @type: Event type to subscribe to
159 * @func: Function to call when the event is sent
160 * @ctx: Context to pass to the function
161 * @return 0 if OK, -ve on error
162 */
163int event_register(const char *id, enum event_t type, event_handler_t func,
164 void *ctx);
165
Simon Glassc81b4602022-03-04 08:43:06 -0700166/** event_show_spy_list( - Show a list of event spies */
167void event_show_spy_list(void);
168
Simon Glass87a5d1b2022-03-04 08:43:00 -0700169/**
Ovidiu Panaitcebc8162022-05-15 21:40:29 +0300170 * event_manual_reloc() - Relocate event handler pointers
171 *
172 * Relocate event handler pointers for all static event spies. It is called
173 * during the generic board init sequence, after relocation.
174 *
175 * Return: 0 if OK
176 */
177int event_manual_reloc(void);
178
179/**
Simon Glass87a5d1b2022-03-04 08:43:00 -0700180 * event_notify() - notify spies about an event
181 *
182 * It is possible to pass in union event_data here but that may not be
183 * convenient if the data is elsewhere, or is one of the members of the union.
184 * So this uses a void * for @data, with a separate @size.
185 *
186 * @type: Event type
187 * @data: Event data to be sent (e.g. union_event_data)
188 * @size: Size of data in bytes
189 * @return 0 if OK, -ve on error
190 */
191int event_notify(enum event_t type, void *data, int size);
192
Heinrich Schuchardtc5ef2022022-05-07 22:39:01 +0200193#if CONFIG_IS_ENABLED(EVENT)
Simon Glass87a5d1b2022-03-04 08:43:00 -0700194/**
195 * event_notify_null() - notify spies about an event
196 *
197 * Data is NULL and the size is 0
198 *
199 * @type: Event type
200 * @return 0 if OK, -ve on error
201 */
202int event_notify_null(enum event_t type);
203#else
Simon Glass87a5d1b2022-03-04 08:43:00 -0700204static inline int event_notify_null(enum event_t type)
205{
206 return 0;
207}
208#endif
209
210#if CONFIG_IS_ENABLED(EVENT_DYNAMIC)
211/**
212 * event_uninit() - Clean up dynamic events
213 *
214 * This removes all dynamic event handlers
215 */
216int event_uninit(void);
217
218/**
219 * event_uninit() - Set up dynamic events
220 *
221 * Init a list of dynamic event handlers, so that these can be added as
222 * needed
223 */
224int event_init(void);
225#else
226static inline int event_uninit(void)
227{
228 return 0;
229}
230
231static inline int event_init(void)
232{
233 return 0;
234}
235#endif
236
237#endif