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