diff options
| -rw-r--r-- | doc/develop/event.rst | 66 | ||||
| -rw-r--r-- | doc/develop/index.rst | 1 | ||||
| -rw-r--r-- | doc/usage/event.rst | 49 | ||||
| -rw-r--r-- | doc/usage/index.rst | 1 |
4 files changed, 117 insertions, 0 deletions
diff --git a/doc/develop/event.rst b/doc/develop/event.rst new file mode 100644 index 0000000..6e144cf --- /dev/null +++ b/doc/develop/event.rst @@ -0,0 +1,66 @@ +.. 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 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). + + +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 missing, so +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 diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 93ebfa4..2e6d6c3 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 0000000..c0f8acd --- /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 0aacf53..7501028 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -29,6 +29,7 @@ Shell commands x86/cbsysinfo conitrace echo + event exception extension exit |