blob: e8f2f55c63da8176f584b91be0e4e30c1d3380f4 [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 Glass7fe32b32022-03-04 08:43:05 -070025 EVT_DM_POST_INIT,
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
Simon Glass87a5d1b2022-03-04 08:43:00 -070037 EVT_COUNT
38};
39
40union 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;
Simon Glass5b896ed2022-03-04 08:43:03 -070049
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;
Simon Glass98887ab2022-07-30 15:52:31 -060058
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;
Simon Glass87a5d1b2022-03-04 08:43:00 -070067};
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 */
75struct event {
76 enum event_t type;
77 union event_data data;
78};
79
80/** Function type for event handlers */
81typedef 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 */
90struct 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
105static 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.
Simon Glass56952472022-07-30 15:52:30 -0600140 *
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.
Simon Glass87a5d1b2022-03-04 08:43:00 -0700144 */
145#define EVENT_SPY(_type, _func) \
Simon Glass56952472022-07-30 15:52:30 -0600146 __used ll_entry_declare(struct evspy_info, _type, evspy_info) = \
Simon Glass87a5d1b2022-03-04 08:43:00 -0700147 _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 */
158int event_register(const char *id, enum event_t type, event_handler_t func,
159 void *ctx);
160
Simon Glassc81b4602022-03-04 08:43:06 -0700161/** event_show_spy_list( - Show a list of event spies */
162void event_show_spy_list(void);
163
Simon Glass87a5d1b2022-03-04 08:43:00 -0700164/**
Ovidiu Panaitcebc8162022-05-15 21:40:29 +0300165 * 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 */
172int event_manual_reloc(void);
173
174/**
Simon Glass87a5d1b2022-03-04 08:43:00 -0700175 * 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 */
186int event_notify(enum event_t type, void *data, int size);
187
Heinrich Schuchardtc5ef2022022-05-07 22:39:01 +0200188#if CONFIG_IS_ENABLED(EVENT)
Simon Glass87a5d1b2022-03-04 08:43:00 -0700189/**
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 */
197int event_notify_null(enum event_t type);
198#else
Simon Glass87a5d1b2022-03-04 08:43:00 -0700199static 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 */
211int 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 */
219int event_init(void);
220#else
221static inline int event_uninit(void)
222{
223 return 0;
224}
225
226static inline int event_init(void)
227{
228 return 0;
229}
230#endif
231
232#endif