Add documentation for events, including the event command.
Signed-off-by: Simon Glass sjg@chromium.org ---
doc/develop/event.rst | 100 ++++++++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + doc/usage/event.rst | 49 +++++++++++++++++++++ doc/usage/index.rst | 1 + 4 files changed, 151 insertions(+) create mode 100644 doc/develop/event.rst create mode 100644 doc/usage/event.rst
diff --git a/doc/develop/event.rst b/doc/develop/event.rst new file mode 100644 index 00000000000..1069d247aa0 --- /dev/null +++ b/doc/develop/event.rst @@ -0,0 +1,100 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Events +====== + +U-Boot supports a way for various events to be handled by interested +subsystems. This provide a generic way to handle 'hooks' like setting up the +CPUs after driver model is active, or reading a partition table after a new +block device is probed. + +Rather than using weak functions and direct calls across subsystemss, it is +often easier to use an event. + +An event consists of a type (e.g. EVT_DM_POST_INIT) and some optional data, +in `union event_data`. An event spy can be creasted to watch for events of a +particular type. When the event is created, it is sent to each spy in turn. + + +Declaring a spy +--------------- + +To declare a spy, use something like this:: + + static int snow_setup_cpus(void *ctx, struct event *event) + { + /* do something */ + return 0; + } + EVENT_SPY(EVT_DM_POST_INIT, snow_setup_cpus); + +Your function is then called when `EVT_DM_POST_INIT` is emitted, i.e. after +driver model is inited (in SPL, or in U-Boot proper before and after +relocation). + +The `ctx` value is intended to pass context information to the handler. At +present this is not used by EVENT_SPY(). The `event` struction holds more +information about the event, if any. + +Each spy declaration uses at least two 32- or 64-bit words, depending on the +architecture. If `CONFIG_EVENT_DEBUG` is enabled, an extra word is used. +Enabling events uses a little over 200 bytes of extra code space, on 32-bit +machines. + +Logging +------- + +Logging of spy invocation is available through the `LOGC_EVENT` log category. +For quick one-off debugging, add this to the very top of `common/event.c`:: + + #define LOG_DEBUG + +Debugging +--------- + +To assist with debugging events, enable `CONFIG_EVENT_DEBUG` and +`CONFIG_CMD_EVENT`. The :doc:`../usage/event` command can then be used to +provide a spy list. + +It is also possible to list spy information from the U-Boot executable,, using +the `event_dump.py` script:: + + $ scripts/event_dump.py /tmp/b/sandbox/u-boot + Event type Id Source location + -------------------- ------------------------------ ------------------------------ + EVT_MISC_INIT_F f:sandbox_misc_init_f arch/sandbox/cpu/start.c:125 + +This shows each event spy in U-Boot, along with the event type, function name +(or ID) and source location. + +Note that if `CONFIG_EVENT_DEBUG` is not enabled, the event ID is not stored, +to save space. In this case the function is shown instead (with an `f:` +prefix as above). Since the ID is generally the same as the function name, +this does not matter much. + +The event type is decoded by the symbol used by U-Boot for the event linker +list. Symbols have the form:: + + _u_boot_list_2_evspy_info_2_EVT_MISC_INIT_F + +so the event type can be read from the end. To manually list spy information +in an image, use $(CROSS_COMPILE)nm:: + + nm u-boot |grep evspy |grep list + 00000000002d6300 D _u_boot_list_2_evspy_info_2_EVT_MISC_INIT_F + +Some attempt is made to use the word `spy` everywhere, so make the code easier +to find in U-Boot, which does not use this word otherwise. The plural of `spy` +is not used, for similar reasons. + +To do +----- + +Some ideas: + +- Consider putting the event context inside `struct event` +- Allow an event-spy function to have no arguments, to save code space +- Convert more of the init hooks to use events +- Use events for `ft_board_setup()` and the like +- Add event-spy flags for things like before/after relocation +- Support event-spy priority diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 9592d193fca..9cbe3f87bdf 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -17,6 +17,7 @@ Implementation distro driver-model/index environment + event global_data logging makefiles diff --git a/doc/usage/event.rst b/doc/usage/event.rst new file mode 100644 index 00000000000..c0f8acd727b --- /dev/null +++ b/doc/usage/event.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +event command +============= + +Synopsis +-------- + +:: + + event list + +Description +----------- + +The event command provides spy list. + +This shows the following information: + +Seq + Sequence number of the spy, numbered from 0 + +Type + Type of the spy, both as a number and a label. If `CONFIG_EVENT_DEBUG` is + not enabled, the label just shows `(unknown)`. + +Function + Address of the function to call + +ID + ID string for this event, if `CONFIG_EVENT_DEBUG` is enabled. Otherwise this + just shows `?`. + + +See :doc:`../develop/event` for more information on events. + +Example +------- + +:: + + => event list + Seq Type Function ID + 0 7 misc_init_f 55a070517c68 ? + +Configuration +------------- + +The event command is only available if CONFIG_CMD_EVENT=y. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 33761af96af..97c3ec2e039 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -28,6 +28,7 @@ Shell commands x86/cbsysinfo conitrace echo + event exception extension exit