--- /dev/null
-`CONFIG_CMD_EVENT`. The :doc:`../usage/event` command can then be used to
+ .. 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/cmd/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
--- /dev/null
-
- When you intend to use the bootmenu on a color frame buffer console,
- make sure to additionally define::
-
- CONFIG_CFB_CONSOLE_ANSI=y
+.. SPDX-License-Identifier: GPL-2.0+
+
+bootmenu command
+================
+
+The "bootmenu" command uses U-Boot menu interfaces and provides
+a simple mechanism for creating menus with different boot items.
+The cursor keys "Up" and "Down" are used for navigation through
+the items. Current active menu item is highlighted and can be
+selected using the "Enter" key. The selection of the highlighted
+menu entry invokes an U-Boot command (or a list of commands)
+associated with this menu entry.
+
+The "bootmenu" command interprets ANSI escape sequencies, so
+an ANSI terminal is required for proper menu rendering and item
+selection.
+
+The assembling of the menu is done via a set of environment variables
+"bootmenu_<num>" and "bootmenu_delay", i.e.::
+
+ bootmenu_delay=<delay>
+ bootmenu_<num>="<title>=<commands>"
+
+<delay>
+ is the autoboot delay in seconds, after which the first
+ menu entry will be selected automatically
+
+<num>
+ is the boot menu entry number, starting from zero
+
+<title>
+ is the text of the menu entry shown on the console
+ or on the boot screen
+
+<commands>
+ are commands which will be executed when a menu
+ entry is selected
+
+Title and commands are separated by the first appearance of a '='
+character in the value of the environment variable.
+
+The first (optional) argument of the "bootmenu" command is a delay specifier
+and it overrides the delay value defined by "bootmenu_delay" environment
+variable. If the environment variable "bootmenu_delay" is not set or if
+the argument of the "bootmenu" command is not specified, the default delay
+will be CONFIG_BOOTDELAY. If delay is 0, no menu entries will be shown on
+the console (or on the screen) and the command of the first menu entry will
+be called immediately. If delay is less then 0, bootmenu will be shown and
+autoboot will be disabled.
+
+Bootmenu always adds menu entry "U-Boot console" at the end of all menu
+entries specified by environment variables. When selecting this entry
+the bootmenu terminates and the usual U-Boot command prompt is presented
+to the user.
+
+Example environment::
+
+ setenv bootmenu_0 Boot 1. kernel=bootm 0x82000000 # Set first menu entry
+ setenv bootmenu_1 Boot 2. kernel=bootm 0x83000000 # Set second menu entry
+ setenv bootmenu_2 Reset board=reset # Set third menu entry
+ setenv bootmenu_3 U-Boot boot order=boot # Set fourth menu entry
+ bootmenu 20 # Run bootmenu with autoboot delay 20s
+
+
+The above example will be rendered as below::
+
+ *** U-Boot Boot Menu ***
+
+ Boot 1. kernel
+ Boot 2. kernel
+ Reset board
+ U-Boot boot order
+ U-Boot console
+
+ Hit any key to stop autoboot: 20
+ Press UP/DOWN to move, ENTER to select
+
+The selected menu entry will be highlighted - it will have inverted
+background and text colors.
+
+The "bootmenu" cammand is enabled by::
+
+ CONFIG_CMD_BOOTMENU=y
+
+To run the bootmenu at startup add these additional settings::
+
+ CONFIG_AUTOBOOT_KEYED=y
+ CONFIG_BOOTDELAY=30
+ CONFIG_AUTOBOOT_MENU_SHOW=y
--- /dev/null
--- /dev/null
++.. 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.
.. toctree::
:maxdepth: 1
- acpi
- addrmap
- askenv
- base
- bootefi
- booti
- bootmenu
- button
- x86/cbsysinfo
- conitrace
- echo
- event
- exception
- extension
- exit
- false
- fatinfo
- fatload
- for
- load
- loady
- mbr
- md
- mmc
- pinmux
- pstore
- qfw
- reset
- sbi
- sf
- scp03
- setexpr
- size
- true
- ums
- wdt
+ cmd/acpi
+ cmd/addrmap
+ cmd/askenv
+ cmd/base
+ cmd/bootefi
+ cmd/booti
+ cmd/bootmenu
+ cmd/button
+ cmd/cbsysinfo
+ cmd/conitrace
+ cmd/echo
++ cmd/event
+ cmd/exception
+ cmd/extension
+ cmd/exit
+ cmd/false
+ cmd/fatinfo
+ cmd/fatload
+ cmd/for
+ cmd/load
+ cmd/loady
+ cmd/mbr
+ cmd/md
+ cmd/mmc
+ cmd/pinmux
+ cmd/pstore
+ cmd/qfw
+ cmd/reset
+ cmd/sbi
+ cmd/sf
+ cmd/scp03
+ cmd/setexpr
+ cmd/size
+ cmd/true
+ cmd/ums
+ cmd/wdt
+
+Booting OS
+----------
+
+.. toctree::
+ :maxdepth: 1
+
+ os/plan9
+ os/vxworks