[PATCH 12/12] event: Add documentation

[Simon Glass]

Add documentation for events, including the event command.

Signed-off-by: Simon Glass <sjg at 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
-- 
2.34.1.448.ga2b2bfdf31-goog