e4580b683502c710f7a88b88223c5d70795074ac
[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         /* To be called once, before calling main_loop() */
38         EVT_MAIN_LOOP,
39
40         EVT_COUNT
41 };
42
43 union 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;
52
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;
61
62         /**
63          * struct event_ft_fixup - FDT fixup before booting
64          *
65          * @tree: tree to update
66          * @images: images which are being booted
67          */
68         struct event_ft_fixup {
69                 oftree tree;
70                 struct bootm_headers *images;
71         } ft_fixup;
72 };
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  */
80 struct event {
81         enum event_t type;
82         union event_data data;
83 };
84
85 /** Function type for event handlers */
86 typedef 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  */
95 struct 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
110 static 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.
145  *
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.
149  */
150 #define EVENT_SPY(_type, _func) \
151         __used ll_entry_declare(struct evspy_info, _type ## _3_ ## _func, \
152                 evspy_info) = _ESPY_REC(_type, _func)
153
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  */
163 int event_register(const char *id, enum event_t type, event_handler_t func,
164                    void *ctx);
165
166 /** event_show_spy_list( - Show a list of event spies */
167 void event_show_spy_list(void);
168
169 /**
170  * 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  */
177 int event_manual_reloc(void);
178
179 /**
180  * 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  */
191 int event_notify(enum event_t type, void *data, int size);
192
193 #if CONFIG_IS_ENABLED(EVENT)
194 /**
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  */
202 int event_notify_null(enum event_t type);
203 #else
204 static 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  */
216 int 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  */
224 int event_init(void);
225 #else
226 static inline int event_uninit(void)
227 {
228         return 0;
229 }
230
231 static inline int event_init(void)
232 {
233         return 0;
234 }
235 #endif
236
237 #endif