Merge branch '2023-08-31-replace-more-init-hooks-with-events' into next

To quote the author:
This series replaces some more of the init hooks in board_f.c and
board_r.c with events. Notably it converts last_state_init() over.

It also provides a 'simple' event spy, which takes no arguments. It
turns out that this is quite a common case, so it is worth optimising
for this, to reduce code size, before events become too commonly used.

Finally, it introduces a way of emitting an event in an initcall,
instead of calling a function. This is likely to be used at least as
often as the functions, as we convert more of these initcalls.

As part of this, the initcall code is brought back into a C file. Somehow
the compiler has changed or something else, so that this does not confer
any benefits now.

For boards with EVENT enabled, this unfortunately results in small
growth, e.g. for firefly:

   aarch64: (for 1/1 boards) all +114.0 data +16.0 rodata +22.0 text +76.0
       arm: (for 1/1 boards) all +82.0 rodata +18.0 text +64.0

For boards without EVENT enabled the growth is smaller, e.g. nokia_rx51:

       arm: (for 1/1 boards) all +32.0 data +8.0 rodata -8.0 text +32.0

I cannot find a good way to avoid the latter, other than macro magic
with an embedded comma (to completely remove an event entry), which
seems nasty.

1 files changed, 21 insertions, 2 deletions

diff --git a/doc/develop/event.rst b/doc/develop/event.rst
index cb09e9c85a9..d5043ec4f4c 100644
--- a/doc/develop/event.rst
+++ b/doc/develop/event.rst
@@ -21,16 +21,31 @@ Declaring a spy
 
 To declare a spy, use something like this::
 
-    static int snow_setup_cpus(void *ctx, struct event *event)
+    static int snow_check_temperature(void)
     {
         /* do something */
         return 0;
     }
-    EVENT_SPY(EVT_DM_POST_INIT_F, snow_setup_cpus);
+    EVENT_SPY_SIMPLE(EVT_DM_POST_INIT_F, snow_check_temperature);
 
 This function is called when EVT_DM_POST_INIT_F is emitted, i.e. after the
 driver model is initialized (in U-Boot proper before and after relocation).
 
+If you need access to the event data, use `EVENT_SPY_FULL`, like this::
+
+    static int snow_setup_cpus(void *ctx, struct event *event)
+    {
+        /* do something that uses event->data*/
+        return 0;
+    }
+    EVENT_SPY_FULL(EVT_DM_POST_INIT_F, snow_setup_cpus);
+
+Note that the context is always NULL for a static spy. See below for information
+about how to use a dynamic spy.
+
+The return value is handled by the event emitter. If non-zero, then the error
+is returned to the function which emitted the event, i.e. the one that called
+`event_notify()`.
 
 Debugging
 ---------
@@ -80,6 +95,10 @@ to be notified when a particular device is probed or removed.
 This can be handled by enabling `CONFIG_EVENT_DYNAMIC`. It is then possible to
 call `event_register()` to register a new handler for a particular event.
 
+If some context is need for the spy, you can pass a pointer to
+`event_register()` to provide that. Note that the context is only passed to
+a spy registered with `EVENT_SPY_FULL`.
+
 Dynamic event handlers are called after all the static event spy handlers have
 been processed. Of course, since dynamic event handlers are created at runtime
 it is not possible to use the `event_dump.py` to see them.