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