From 12be60daab224f2cbcb7c6584ab87f0f7caba83c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 21 Aug 2023 21:16:58 -0600 Subject: [PATCH] event: Update documentation for simple spy Now that we have two types of spy, mention this in the documentation. Put the simple spy first, since it seems to be the common case. Signed-off-by: Simon Glass --- doc/develop/event.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/doc/develop/event.rst b/doc/develop/event.rst index cb09e9c85a..d5043ec4f4 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. -- 2.39.5