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 <[email protected]>
   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  * Another issue has come up, only with clang: using 'static' makes it throw
 128  * away the linker-list entry sometimes, e.g. with the EVT_FT_FIXUP entry in
 129  * vbe_simple.c - so for now, make it global.
 130  */
 131 #define EVENT_SPY(_type, _func) \
 132         __used ll_entry_declare(struct evspy_info, _type, evspy_info) = \
 133         _ESPY_REC(_type, _func)
 134
 135 /**
 136  * event_register - register a new spy
 137  *
 138  * @id: Spy ID
 139  * @type: Event type to subscribe to
 140  * @func: Function to call when the event is sent
 141  * @ctx: Context to pass to the function
 142  * @return 0 if OK, -ve on error
 143  */
 144 int event_register(const char *id, enum event_t type, event_handler_t func,
 145                    void *ctx);
 146
 147 /** event_show_spy_list( - Show a list of event spies */
 148 void event_show_spy_list(void);
 149
 150 /**
 151  * event_manual_reloc() - Relocate event handler pointers
 152  *
 153  * Relocate event handler pointers for all static event spies. It is called
 154  * during the generic board init sequence, after relocation.
 155  *
 156  * Return: 0 if OK
 157  */
 158 int event_manual_reloc(void);
 159
 160 /**
 161  * event_notify() - notify spies about an event
 162  *
 163  * It is possible to pass in union event_data here but that may not be
 164  * convenient if the data is elsewhere, or is one of the members of the union.
 165  * So this uses a void * for @data, with a separate @size.
 166  *
 167  * @type: Event type
 168  * @data: Event data to be sent (e.g. union_event_data)
 169  * @size: Size of data in bytes
 170  * @return 0 if OK, -ve on error
 171  */
 172 int event_notify(enum event_t type, void *data, int size);
 173
 174 #if CONFIG_IS_ENABLED(EVENT)
 175 /**
 176  * event_notify_null() - notify spies about an event
 177  *
 178  * Data is NULL and the size is 0
 179  *
 180  * @type: Event type
 181  * @return 0 if OK, -ve on error
 182  */
 183 int event_notify_null(enum event_t type);
 184 #else
 185 static inline int event_notify_null(enum event_t type)
 186 {
 187         return 0;
 188 }
 189 #endif
 190
 191 #if CONFIG_IS_ENABLED(EVENT_DYNAMIC)
 192 /**
 193  * event_uninit() - Clean up dynamic events
 194  *
 195  * This removes all dynamic event handlers
 196  */
 197 int event_uninit(void);
 198
 199 /**
 200  * event_uninit() - Set up dynamic events
 201  *
 202  * Init a list of dynamic event handlers, so that these can be added as
 203  * needed
 204  */
 205 int event_init(void);
 206 #else
 207 static inline int event_uninit(void)
 208 {
 209         return 0;
 210 }
 211
 212 static inline int event_init(void)
 213 {
 214         return 0;
 215 }
 216 #endif
 217
 218 #endif