Provide Sphinx documentation for all events.

Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com --- include/event.h | 84 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 82 insertions(+), 2 deletions(-)

diff --git a/include/event.h b/include/event.h index bb38ba98e7..6dee4adef2 100644 --- a/include/event.h +++ b/include/event.h @@ -19,29 +19,109 @@ * @EVT_DM_PRE_PROBE: Device is about to be probed */ enum event_t { - EVT_NONE, + /** + * @EVT_NONE: This zero value is not used for events. + */ + EVT_NONE = 0, + + /** + * @EVT_TEST: This event is used in unit tests. + */ EVT_TEST,

/* Events related to driver model */ + /** + * @EVT_DM_POST_INIT_F: + * This event is triggered after initialization of the driver model + * before relocation. Its parameter is NULL. + * A non-zero return code from the event handler let's the boot process + * fail. + */ EVT_DM_POST_INIT_F, + /** + * @EVT_DM_POST_INIT_R: + * This event is triggered after initialization of the driver model + * after relocation. Its parameter is NULL. + * A non-zero return code from the event handler let's the boot process + * fail. + */ EVT_DM_POST_INIT_R, + /** + * @EVT_DM_PRE_PROBE: + * This event is triggered before probing a device. Its parameter is the + * udevice to be probed. + * A non-zero return code lets the device not being probed. + */ EVT_DM_PRE_PROBE, + /** + * @EVT_DM_POST_PROBE: + * This event is triggered after probing a device. Its parameter is the + * udevice to be probed. + * A non-zero return code leaves the device in the unprobed state and + * therefore not usable. + */ EVT_DM_POST_PROBE, + /** + * @EVT_DM_PRE_REMOVE: + * This event is triggered before removing a device. Its parameter is + * the udevice to be removed. + * A non-zero return code stops the removal of the device before any + * changes. + */ EVT_DM_PRE_REMOVE, + /** + * @EVT_DM_POST_REMOVE: + * This event is triggered before removing a device. Its parameter is + * the udevice to be removed. + * A non-zero return code stops the removal of the device after all + * removal changes. The previous state is not restored. All children + * will be gone and the device may not be functional. + */ EVT_DM_POST_REMOVE,

/* Init hooks */ + /** + * @EVT_MISC_INIT_F: + * This event is triggered during the initialization sequence bofore + * relocation. Its parameter is NULL. + * A non-zero return code from the event handler let's the boot process + * fail. + */ EVT_MISC_INIT_F,

- /* Fpga load hook */ + /** + * @EVT_FPGA_LOAD: + * The FPGA load hook is called after loading an FPGA with a new binary. + * Its parameter is of type struct event_fpga_load and contains + * information about the loaded image. + */ EVT_FPGA_LOAD,

/* Device tree fixups before booting */ + /** + * @EVT_FT_FIXUP: + * This event is triggered during device-tree fix up after all + * other device-tree fixups have been executed. + * Its parameter is of type struct event_ft_fixup which contains + * the address of the device-tree to fix up and the list of images to be + * booted. + */ EVT_FT_FIXUP,

/* To be called once, before calling main_loop() */ + /** + * @EVT_MAIN_LOOP: + * This event is triggered immediately before calling main_loop() which + * is the entry point of the command line. + * Its parameter is NULL. + */ EVT_MAIN_LOOP,

+ /** + * @EVT_COUNT: + * This constants holds the maximum event number + 1 and is used when + * looping over all event classes. + */ EVT_COUNT };

Add the events.h include to the API documentation.

Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com --- doc/api/event.rst | 9 +++++++++ doc/api/index.rst | 1 + 2 files changed, 10 insertions(+) create mode 100644 doc/api/event.rst

diff --git a/doc/api/event.rst b/doc/api/event.rst new file mode 100644 index 0000000000..8a57d43832 --- /dev/null +++ b/doc/api/event.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Events +====== + +The concept of events is decribed :doc:`here <../develop/event>`. + +.. kernel-doc:: include/event.h + :internal: diff --git a/doc/api/index.rst b/doc/api/index.rst index 3a80ae0635..2f0218c47a 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -10,6 +10,7 @@ U-Boot API documentation dfu dm efi + event getopt linker_lists lmb