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