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 #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         /**
  23          * @EVT_NONE: This zero value is not used for events.
  24          */
  25         EVT_NONE = 0,
  26
  27         /**
  28          * @EVT_TEST: This event is used in unit tests.
  29          */
  30         EVT_TEST,
  31
  32         /**
  33          * @EVT_DM_POST_INIT_F:
  34          * This event is triggered after pre-relocation initialization of the
  35          * driver model. Its parameter is NULL.
  36          * A non-zero return code from the event handler let's the boot process
  37          * fail.
  38          */
  39         EVT_DM_POST_INIT_F,
  40
  41         /**
  42          * @EVT_DM_POST_INIT_R:
  43          * This event is triggered after post-relocation initialization of the
  44          * driver model. Its parameter is NULL.
  45          * A non-zero return code from the event handler let's the boot process
  46          * fail.
  47          */
  48         EVT_DM_POST_INIT_R,
  49
  50         /**
  51          * @EVT_DM_PRE_PROBE:
  52          * This event is triggered before probing a device. Its parameter is the
  53          * device to be probed.
  54          * A non-zero return code from the event handler lets the device not
  55          * being probed.
  56          */
  57         EVT_DM_PRE_PROBE,
  58
  59         /**
  60          * @EVT_DM_POST_PROBE:
  61          * This event is triggered after probing a device. Its parameter is the
  62          * device that was probed.
  63          * A non-zero return code from the event handler leaves the device in
  64          * the unprobed state and therefore not usable.
  65          */
  66         EVT_DM_POST_PROBE,
  67
  68         /**
  69          * @EVT_DM_PRE_REMOVE:
  70          * This event is triggered after removing a device. Its parameter is
  71          * the device to be removed.
  72          * A non-zero return code from the event handler stops the removal of
  73          * the device before any changes.
  74          */
  75         EVT_DM_PRE_REMOVE,
  76
  77         /**
  78          * @EVT_DM_POST_REMOVE:
  79          * This event is triggered before removing a device. Its parameter is
  80          * the device that was removed.
  81          * A non-zero return code stops from the event handler the removal of
  82          * the device after all removal changes. The previous state is not
  83          * restored. All children will be gone and the device may not be
  84          * functional.
  85          */
  86         EVT_DM_POST_REMOVE,
  87
  88         /**
  89          * @EVT_MISC_INIT_F:
  90          * This event is triggered during the initialization sequence before
  91          * relocation. Its parameter is NULL.
  92          * A non-zero return code from the event handler let's the boot process
  93          * fail.
  94          */
  95         EVT_MISC_INIT_F,
  96
  97         /**
  98          * @EVT_FPGA_LOAD:
  99          * The FPGA load hook is called after loading an FPGA with a new binary.
 100          * Its parameter is of type struct event_fpga_load and contains
 101          * information about the loaded image.
 102          */
 103         EVT_FPGA_LOAD,
 104
 105         /**
 106          * @EVT_FT_FIXUP:
 107          * This event is triggered during device-tree fix up after all
 108          * other device-tree fixups have been executed.
 109          * Its parameter is of type struct event_ft_fixup which contains
 110          * the address of the device-tree to fix up and the list of images to be
 111          * booted.
 112          * A non-zero return code from the event handler let's booting the
 113          * images fail.
 114          */
 115         EVT_FT_FIXUP,
 116
 117         /**
 118          * @EVT_MAIN_LOOP:
 119          * This event is triggered immediately before calling main_loop() which
 120          * is the entry point of the command line. Its parameter is NULL.
 121          * A non-zero return value causes the boot to fail.
 122          */
 123         EVT_MAIN_LOOP,
 124
 125         /**
 126          * @EVT_COUNT:
 127          * This constants holds the maximum event number + 1 and is used when
 128          * looping over all event classes.
 129          */
 130         EVT_COUNT
 131 };
 132
 133 union event_data {
 134         /**
 135          * struct event_data_test  - test data
 136          *
 137          * @signal: A value to update the state with
 138          */
 139         struct event_data_test {
 140                 int signal;
 141         } test;
 142
 143         /**
 144          * struct event_dm - driver model event
 145          *
 146          * @dev: Device this event relates to
 147          */
 148         struct event_dm {
 149                 struct udevice *dev;
 150         } dm;
 151
 152         /**
 153          * struct event_fpga_load - fpga load event
 154          *
 155          * @buf: The buffer that was loaded into the fpga
 156          * @bsize: The size of the buffer that was loaded into the fpga
 157          * @result: Result of the load operation
 158          */
 159         struct event_fpga_load {
 160                 const void *buf;
 161                 size_t bsize;
 162                 int result;
 163         } fpga_load;
 164
 165         /**
 166          * struct event_ft_fixup - FDT fixup before booting
 167          *
 168          * @tree: tree to update
 169          * @images: images which are being booted
 170          */
 171         struct event_ft_fixup {
 172                 oftree tree;
 173                 struct bootm_headers *images;
 174         } ft_fixup;
 175 };
 176
 177 /**
 178  * struct event - an event that can be sent and received
 179  *
 180  * @type: Event type
 181  * @data: Data for this particular event
 182  */
 183 struct event {
 184         enum event_t type;
 185         union event_data data;
 186 };
 187
 188 /** Function type for event handlers */
 189 typedef int (*event_handler_t)(void *ctx, struct event *event);
 190
 191 /**
 192  * struct evspy_info - information about an event spy
 193  *
 194  * @func: Function to call when the event is activated (must be first)
 195  * @type: Event type
 196  * @id: Event id string
 197  */
 198 struct evspy_info {
 199         event_handler_t func;
 200         enum event_t type;
 201 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
 202         const char *id;
 203 #endif
 204 };
 205
 206 /* Declare a new event spy */
 207 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
 208 #define _ESPY_REC(_type, _func)   { _func, _type, #_func, }
 209 #else
 210 #define _ESPY_REC(_type, _func)   { _func, _type, }
 211 #endif
 212
 213 static inline const char *event_spy_id(struct evspy_info *spy)
 214 {
 215 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
 216         return spy->id;
 217 #else
 218         return "?";
 219 #endif
 220 }
 221
 222 /*
 223  * It seems that LTO will drop list entries if it decides they are not used,
 224  * although the conditions that cause this are unclear.
 225  *
 226  * The example found is the following:
 227  *
 228  * static int sandbox_misc_init_f(void *ctx, struct event *event)
 229  * {
 230  *    return sandbox_early_getopt_check();
 231  * }
 232  * EVENT_SPY(EVT_MISC_INIT_F, sandbox_misc_init_f);
 233  *
 234  * where EVENT_SPY uses ll_entry_declare()
 235  *
 236  * In this case, LTO decides to drop the sandbox_misc_init_f() function
 237  * (which is fine) but then drops the linker-list entry too. This means
 238  * that the code no longer works, in this case sandbox no-longer checks its
 239  * command-line arguments properly.
 240  *
 241  * Without LTO, the KEEP() command in the .lds file is enough to keep the
 242  * entry around. But with LTO it seems that the entry has already been
 243  * dropped before the link script is considered.
 244  *
 245  * The only solution I can think of is to mark linker-list entries as 'used'
 246  * using an attribute. This should be safe, since we don't actually want to drop
 247  * any of these. However this does slightly limit LTO's optimisation choices.
 248  *
 249  * Another issue has come up, only with clang: using 'static' makes it throw
 250  * away the linker-list entry sometimes, e.g. with the EVT_FT_FIXUP entry in
 251  * vbe_simple.c - so for now, make it global.
 252  */
 253 #define EVENT_SPY(_type, _func) \
 254         __used ll_entry_declare(struct evspy_info, _type ## _3_ ## _func, \
 255                 evspy_info) = _ESPY_REC(_type, _func)
 256
 257 /**
 258  * event_register - register a new spy
 259  *
 260  * @id: Spy ID
 261  * @type: Event type to subscribe to
 262  * @func: Function to call when the event is sent
 263  * @ctx: Context to pass to the function
 264  * @return 0 if OK, -ve on error
 265  */
 266 int event_register(const char *id, enum event_t type, event_handler_t func,
 267                    void *ctx);
 268
 269 /** event_show_spy_list( - Show a list of event spies */
 270 void event_show_spy_list(void);
 271
 272 /**
 273  * event_manual_reloc() - Relocate event handler pointers
 274  *
 275  * Relocate event handler pointers for all static event spies. It is called
 276  * during the generic board init sequence, after relocation.
 277  *
 278  * Return: 0 if OK
 279  */
 280 int event_manual_reloc(void);
 281
 282 /**
 283  * event_notify() - notify spies about an event
 284  *
 285  * It is possible to pass in union event_data here but that may not be
 286  * convenient if the data is elsewhere, or is one of the members of the union.
 287  * So this uses a void * for @data, with a separate @size.
 288  *
 289  * @type: Event type
 290  * @data: Event data to be sent (e.g. union_event_data)
 291  * @size: Size of data in bytes
 292  * @return 0 if OK, -ve on error
 293  */
 294 int event_notify(enum event_t type, void *data, int size);
 295
 296 #if CONFIG_IS_ENABLED(EVENT)
 297 /**
 298  * event_notify_null() - notify spies about an event
 299  *
 300  * Data is NULL and the size is 0
 301  *
 302  * @type: Event type
 303  * @return 0 if OK, -ve on error
 304  */
 305 int event_notify_null(enum event_t type);
 306 #else
 307 static inline int event_notify_null(enum event_t type)
 308 {
 309         return 0;
 310 }
 311 #endif
 312
 313 #if CONFIG_IS_ENABLED(EVENT_DYNAMIC)
 314 /**
 315  * event_uninit() - Clean up dynamic events
 316  *
 317  * This removes all dynamic event handlers
 318  */
 319 int event_uninit(void);
 320
 321 /**
 322  * event_uninit() - Set up dynamic events
 323  *
 324  * Init a list of dynamic event handlers, so that these can be added as
 325  * needed
 326  */
 327 int event_init(void);
 328 #else
 329 static inline int event_uninit(void)
 330 {
 331         return 0;
 332 }
 333
 334 static inline int event_init(void)
 335 {
 336         return 0;
 337 }
 338 #endif
 339
 340 #endif