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