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