1.. SPDX-License-Identifier: GPL-2.0+
2
3Events
4======
5
6U-Boot supports a way for various events to be handled by interested
7subsystems. This provide a generic way to handle 'hooks' like setting up the
8CPUs after driver model is active, or reading a partition table after a new
9block device is probed.
10
11Rather than using weak functions and direct calls across subsystemss, it is
12often easier to use an event.
13
14An event consists of a type (e.g. EVT_DM_POST_INIT_F) and some optional data,
15in `union event_data`. An event spy can be created to watch for events of a
16particular type. When the event is created, it is sent to each spy in turn.
17
18
19Declaring a spy
20---------------
21
22To 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_F, snow_setup_cpus);
30
31This function is called when EVT_DM_POST_INIT_F is emitted, i.e. after the
32driver model is initialized (in U-Boot proper before and after relocation).
33
34
35Debugging
36---------
37
38To assist with debugging events, enable `CONFIG_EVENT_DEBUG` and
39`CONFIG_CMD_EVENT`. The :doc:`../usage/cmd/event` command can then be used to
40provide a spy list.
41
42It is also possible to list spy information from the U-Boot executable,, using
43the `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
50This shows each event spy in U-Boot, along with the event type, function name
51(or ID) and source location.
52
53Note that if `CONFIG_EVENT_DEBUG` is not enabled, the event ID is missing, so
54the function is shown instead (with an `f:` prefix as above). Since the ID is
55generally the same as the function name, this does not matter much.
56
57The event type is decoded by the symbol used by U-Boot for the event linker
58list. Symbols have the form::
59
60    _u_boot_list_2_evspy_info_2_EVT_MISC_INIT_F
61
62so the event type can be read from the end. To manually list spy information
63in 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
67
68Logging is also available. Events use category `LOGC_EVENT`, so you can enable
69logging on that, or add `#define LOG_DEBUG` to the top of `common/event.c` to
70see events being sent.
71
72
73Dynamic events
74--------------
75
76Static events provide a way of dealing with events known at build time. In some
77cases we want to attach an event handler at runtime. For example, we may wish
78to be notified when a particular device is probed or removed.
79
80This can be handled by enabling `CONFIG_EVENT_DYNAMIC`. It is then possible to
81call `event_register()` to register a new handler for a particular event.
82
83Dynamic event handlers are called after all the static event spy handlers have
84been processed. Of course, since dynamic event handlers are created at runtime
85it is not possible to use the `event_dump.py` to see them.
86
87At present there is no way to list dynamic event handlers from the command line,
88nor to deregister a dynamic event handler. These features can be added when
89needed.
90