doc/develop/event.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Events
   4 ======
   5
   6 U-Boot supports a way for various events to be handled by interested
   7 subsystems. This provide a generic way to handle 'hooks' like setting up the
   8 CPUs after driver model is active, or reading a partition table after a new
   9 block device is probed.
  10
  11 Rather than using weak functions and direct calls across subsystemss, it is
  12 often easier to use an event.
  13
  14 An event consists of a type (e.g. EVT_DM_POST_INIT) and some optional data,
  15 in `union event_data`. An event spy can be creasted to watch for events of a
  16 particular type. When the event is created, it is sent to each spy in turn.
  17
  18
  19 Declaring a spy
  20 ---------------
  21
  22 To declare a spy, use something like this::
  23
  24     static int snow_setup_cpus(void *ctx, struct event *event)
  25     {
  26         /* do something */
  27         return 0;
  28     }
  29     EVENT_SPY(EVT_DM_POST_INIT, snow_setup_cpus);
  30
  31 Your function is called when EVT_DM_POST_INIT is emitted, i.e. after driver
  32 model is inited (in SPL, or in U-Boot proper before and after relocation).
  33
  34
  35 Debugging
  36 ---------
  37
  38 To assist with debugging events, enable `CONFIG_EVENT_DEBUG` and
  39 `CONFIG_CMD_EVENT`. The :doc:`../usage/event` command can then be used to
  40 provide a spy list.
  41
  42 It is also possible to list spy information from the U-Boot executable,, using
  43 the `event_dump.py` script::
  44
  45     $ scripts/event_dump.py /tmp/b/sandbox/u-boot
  46     Event type            Id                              Source location
  47     --------------------  ------------------------------  ------------------------------
  48     EVT_MISC_INIT_F       f:sandbox_misc_init_f           arch/sandbox/cpu/start.c:125
  49
  50 This shows each event spy in U-Boot, along with the event type, function name
  51 (or ID) and source location.
  52
  53 Note that if `CONFIG_EVENT_DEBUG` is not enabled, the event ID is missing, so
  54 the function is shown instead (with an `f:` prefix as above). Since the ID is
  55 generally the same as the function name, this does not matter much.
  56
  57 The event type is decoded by the symbol used by U-Boot for the event linker
  58 list. Symbols have the form::
  59
  60     _u_boot_list_2_evspy_info_2_EVT_MISC_INIT_F
  61
  62 so the event type can be read from the end. To manually list spy information
  63 in an image, use $(CROSS_COMPILE)nm::
  64
  65     nm u-boot |grep evspy |grep list
  66     00000000002d6300 D _u_boot_list_2_evspy_info_2_EVT_MISC_INIT_F