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