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_PRE_PROBE,
  24         EVT_DM_POST_PROBE,
  25         EVT_DM_PRE_REMOVE,
  26         EVT_DM_POST_REMOVE,
  27
  28         EVT_COUNT
  29 };
  30
  31 union event_data {
  32         /**
  33          * struct event_data_test  - test data
  34          *
  35          * @signal: A value to update the state with
  36          */
  37         struct event_data_test {
  38                 int signal;
  39         } test;
  40
  41         /**
  42          * struct event_dm - driver model event
  43          *
  44          * @dev: Device this event relates to
  45          */
  46         struct event_dm {
  47                 struct udevice *dev;
  48         } dm;
  49 };
  50
  51 /**
  52  * struct event - an event that can be sent and received
  53  *
  54  * @type: Event type
  55  * @data: Data for this particular event
  56  */
  57 struct event {
  58         enum event_t type;
  59         union event_data data;
  60 };
  61
  62 /** Function type for event handlers */
  63 typedef int (*event_handler_t)(void *ctx, struct event *event);
  64
  65 /**
  66  * struct evspy_info - information about an event spy
  67  *
  68  * @func: Function to call when the event is activated (must be first)
  69  * @type: Event type
  70  * @id: Event id string
  71  */
  72 struct evspy_info {
  73         event_handler_t func;
  74         enum event_t type;
  75 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
  76         const char *id;
  77 #endif
  78 };
  79
  80 /* Declare a new event spy */
  81 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
  82 #define _ESPY_REC(_type, _func)   { _func, _type, #_func, }
  83 #else
  84 #define _ESPY_REC(_type, _func)   { _func, _type, }
  85 #endif
  86
  87 static inline const char *event_spy_id(struct evspy_info *spy)
  88 {
  89 #if CONFIG_IS_ENABLED(EVENT_DEBUG)
  90         return spy->id;
  91 #else
  92         return "?";
  93 #endif
  94 }
  95
  96 /*
  97  * It seems that LTO will drop list entries if it decides they are not used,
  98  * although the conditions that cause this are unclear.
  99  *
 100  * The example found is the following:
 101  *
 102  * static int sandbox_misc_init_f(void *ctx, struct event *event)
 103  * {
 104  *    return sandbox_early_getopt_check();
 105  * }
 106  * EVENT_SPY(EVT_MISC_INIT_F, sandbox_misc_init_f);
 107  *
 108  * where EVENT_SPY uses ll_entry_declare()
 109  *
 110  * In this case, LTO decides to drop the sandbox_misc_init_f() function
 111  * (which is fine) but then drops the linker-list entry too. This means
 112  * that the code no longer works, in this case sandbox no-longer checks its
 113  * command-line arguments properly.
 114  *
 115  * Without LTO, the KEEP() command in the .lds file is enough to keep the
 116  * entry around. But with LTO it seems that the entry has already been
 117  * dropped before the link script is considered.
 118  *
 119  * The only solution I can think of is to mark linker-list entries as 'used'
 120  * using an attribute. This should be safe, since we don't actually want to drop
 121  * any of these. However this does slightly limit LTO's optimisation choices.
 122  */
 123 #define EVENT_SPY(_type, _func) \
 124         static __attribute__((used)) ll_entry_declare(struct evspy_info, \
 125                                                       _type, evspy_info) = \
 126         _ESPY_REC(_type, _func)
 127
 128 /**
 129  * event_register - register a new spy
 130  *
 131  * @id: Spy ID
 132  * @type: Event type to subscribe to
 133  * @func: Function to call when the event is sent
 134  * @ctx: Context to pass to the function
 135  * @return 0 if OK, -ve on error
 136  */
 137 int event_register(const char *id, enum event_t type, event_handler_t func,
 138                    void *ctx);
 139
 140 #if CONFIG_IS_ENABLED(EVENT)
 141 /**
 142  * event_notify() - notify spies about an event
 143  *
 144  * It is possible to pass in union event_data here but that may not be
 145  * convenient if the data is elsewhere, or is one of the members of the union.
 146  * So this uses a void * for @data, with a separate @size.
 147  *
 148  * @type: Event type
 149  * @data: Event data to be sent (e.g. union_event_data)
 150  * @size: Size of data in bytes
 151  * @return 0 if OK, -ve on error
 152  */
 153 int event_notify(enum event_t type, void *data, int size);
 154
 155 /**
 156  * event_notify_null() - notify spies about an event
 157  *
 158  * Data is NULL and the size is 0
 159  *
 160  * @type: Event type
 161  * @return 0 if OK, -ve on error
 162  */
 163 int event_notify_null(enum event_t type);
 164 #else
 165 static inline int event_notify(enum event_t type, void *data, int size)
 166 {
 167         return 0;
 168 }
 169
 170 static inline int event_notify_null(enum event_t type)
 171 {
 172         return 0;
 173 }
 174 #endif
 175
 176 #if CONFIG_IS_ENABLED(EVENT_DYNAMIC)
 177 /**
 178  * event_uninit() - Clean up dynamic events
 179  *
 180  * This removes all dynamic event handlers
 181  */
 182 int event_uninit(void);
 183
 184 /**
 185  * event_uninit() - Set up dynamic events
 186  *
 187  * Init a list of dynamic event handlers, so that these can be added as
 188  * needed
 189  */
 190 int event_init(void);
 191 #else
 192 static inline int event_uninit(void)
 193 {
 194         return 0;
 195 }
 196
 197 static inline int event_init(void)
 198 {
 199         return 0;
 200 }
 201 #endif
 202
 203 #endif