diff options
Diffstat (limited to 'Documentation/user')
| -rw-r--r-- | Documentation/user/automount.rst | 2 | ||||
| -rw-r--r-- | Documentation/user/barebox.rst | 123 | ||||
| -rw-r--r-- | Documentation/user/bootchooser.rst | 8 | ||||
| -rw-r--r-- | Documentation/user/booting-linux.rst | 79 | ||||
| -rw-r--r-- | Documentation/user/defaultenv-2.rst | 24 | ||||
| -rw-r--r-- | Documentation/user/devicetree.rst | 45 | ||||
| -rw-r--r-- | Documentation/user/driver-model.rst | 9 | ||||
| -rw-r--r-- | Documentation/user/framebuffer.rst | 6 | ||||
| -rw-r--r-- | Documentation/user/introduction.rst | 13 | ||||
| -rw-r--r-- | Documentation/user/multi-image.rst | 2 | ||||
| -rw-r--r-- | Documentation/user/networking.rst | 10 | ||||
| -rw-r--r-- | Documentation/user/pbl.rst | 9 | ||||
| -rw-r--r-- | Documentation/user/reboot-mode.rst | 104 | ||||
| -rw-r--r-- | Documentation/user/remote-control.rst | 10 | ||||
| -rw-r--r-- | Documentation/user/state.rst | 112 | ||||
| -rw-r--r-- | Documentation/user/system-reset.rst | 2 | ||||
| -rw-r--r-- | Documentation/user/usb.rst | 79 | ||||
| -rw-r--r-- | Documentation/user/user-manual.rst | 2 | ||||
| -rw-r--r-- | Documentation/user/virtio.rst | 88 | ||||
| -rw-r--r-- | Documentation/user/watchdog.rst | 47 |
20 files changed, 668 insertions, 106 deletions
diff --git a/Documentation/user/automount.rst b/Documentation/user/automount.rst index 1fdeffc663..b41b41ef02 100644 --- a/Documentation/user/automount.rst +++ b/Documentation/user/automount.rst @@ -15,7 +15,7 @@ TFTP server, the following is required: .. code-block:: sh mkdir -p /mnt/tftp - automount /mnt/tftp 'ifup -a && mount -t tftp $global.net.server /mnt/tftp' + automount /mnt/tftp 'ifup -a1 && mount -t tftp $global.net.server /mnt/tftp' This creates an automountpoint on ``/mnt/tftp``. Whenever this directory is accessed, the command ``ifup eth0 && mount -t tftp $eth0.serverip /mnt/tftp`` is executed. diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst index 6bea883115..43e5a631ba 100644 --- a/Documentation/user/barebox.rst +++ b/Documentation/user/barebox.rst @@ -54,7 +54,6 @@ variable. Currently, ``ARCH`` must be one of: * arm * mips -* nios2 * openrisc * ppc * riscv @@ -204,13 +203,66 @@ Starting barebox Bringing barebox to a board for the first time is highly board specific, see your board documentation for initial bringup. -barebox binaries are, where possible, designed to be startable second stage from another -bootloader. For example, if you have U-Boot running on your board, you can start barebox -with U-Boot's ``bootm`` command: +For ARM and RISC-V, the barebox build can additionally generate a generic DT image +(enable ``CONFIG_BOARD_ARM_GENERIC_DT`` or ``CONFIG_BOARD_RISCV_GENERIC_DT``, +respectively). The resulting ``images/barebox-dt-2nd.img`` can be booted just +like a Linux kernel that is passed an external device tree. For example: .. code-block:: console - U-Boot: tftp $load_addr barebox.bin + U-Boot: tftp $kernel_addr barebox-dt-2nd.img + U-Boot: tftp $fdt_addr my-board.dtb + U-Boot: bootz $kernel_addr - $fdt_addr # On 32-bit ARM + U-Boot: booti $kernel_addr - $fdt_addr # for other platforms + +Another option is to generate a FIT image containing the generic DT image and a +matching device tree with ``mkimage``: + +.. code-block:: console + + sh: mkimage --architecture arm \ + --os linux \ + --type kernel \ + --fit auto \ + --load-address $kernel_addr_r \ + --compression none \ + --image images/barebox-dt-2nd.img \ + --device-tree arch/${ARCH}/dts/my-board.dtb \ + barebox-dt-2nd.fit + +This FIT image can then be loaded by U-Boot and executed just like a regular +Linux kernel: + +.. code-block:: console + + U-Boot: tftp $fit_addr barebox-dt-2nd.fit + U-Boot: bootm $fit_addr + +Make sure that the address in ``$fit_addr`` is different from the +``$kernel_addr_r`` passed to ``mkimage`` as the load address of the Kernel +image. Otherwise U-Boot may attempt to overwrite the FIT image with the barebox +image contained within. + +For non-DT enabled-bootloaders or other architectures, often the normal barebox +binaries can also be used as they are designed to be startable second stage +from another bootloader, where possible. For example, if you have U-Boot running +on your board, you can start barebox with U-Boot's ``bootm`` command. The bootm +command doesn't support the barebox binaries directly, they first have to be +converted to uImage format using the mkimage tool provided with U-Boot: + +.. code-block:: console + + sh: mkimage -n barebox -A arm -T kernel -C none -a 0x80000000 -d \ + build/images/barebox-freescale-imx53-loco.img barebox.uImage + +U-Boot expects the start address of the binary to be given in the image using the +``-a`` option. The address depends on the board and must be an address which isn't +used by U-Boot. You can pick the same address you would use for generating a kernel +image for that board. The image can then be started with ``bootm``: + +.. code-block:: console + + U-Boot: tftp $load_addr barebox.uImage U-Boot: bootm $load_addr With barebox already running on your board, this can be used to chainload @@ -221,10 +273,11 @@ another barebox. For instance, if you mounted a TFTP server to ``/mnt/tftp`` bootm /mnt/tftp/barebox.bin -At least ``barebox.bin`` (with :ref:`pbl` support enabled ``arch/$ARCH/pbl/zbarebox.bin``) -should be startable second stage. The flash binary (``barebox-flash-image``) may or may not +At least ``barebox.bin`` (with :ref:`pbl` support enabled ``images/*.pblb``) +should be startable second stage. The final binaries (``images/*.img``) may or may not be startable second stage as it may have SoC specific headers which prevent running second -stage. +stage. barebox will usually have handlers in-place to skip these headers, so +it can chainload itself regardless. First Steps ----------- @@ -263,3 +316,57 @@ the usage for a particular command. barebox has tab completion which will comple your command. Arguments to commands are also completed depending on the command. If a command expects a file argument only files will be offered as completion. Other commands will only complete devices or devicetree nodes. + +Building barebox tools +---------------------- + +The normal barebox build results in one or more barebox images (cf. :ref:`multi_image`) +and a number of tools built from its ``scripts/`` directory. + +Most tools are used for the barebox build itself: e.g. the device tree compiler, +the Kconfig machinery and the different image formatting tools that wrap barebox, +so it may be loaded by the boot ROM of the relevant SoCs. + +In addition to these barebox also builds host and target tools that are useful +outside of barebox build: e.g. to manipulate the environment or to load an +image over a boot ROM's USB recovery protocol. These tools may link against +libraries, which are detected using ``PKG_CONFIG`` and ``CROSS_PKG_CONFIG`` +for native and cross build respectively. Their default values are:: + + PKG_CONFIG=pkg-config + CROSS_PKG_CONFIG=${CROSS_COMPILE}pkg-config + +These can be overridden using environment or make variables. + +As use of pkg-config both for host and target tool in the same build can +complicate build system integration. There are two ``ARCH=sandbox`` configuration +to make this more straight forward: + +Host Tools +^^^^^^^^^^ + +The ``hosttools_defconfig`` will compile standalone host tools for the +host (build) system. To build the USB loaders, ``PKG_CONFIG`` needs to know +about ``libusb-1.0``. This config won't build any target tools. + +.. code-block:: console + + export ARCH=sandbox + make hosttools_defconfig + make scripts + +Target Tools +^^^^^^^^^^^^ + +The ``targettools_defconfig`` will cross-compile standalone target tools for the +target system. To build the USB loaders, ``CROSS_PKG_CONFIG`` needs to know +about ``libusb-1.0``. This config won't build any host tools, so it's ok to +set ``CROSS_PKG_CONFIG=pkg-config`` if ``pkg-config`` is primed for target +use. Example: + +.. code-block:: console + + export ARCH=sandbox CROSS_COMPILE=aarch64-linux-gnu- + export CROSS_PKG_CONFIG=pkg-config + make targettools_defconfig + make scripts diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst index 8456e11823..1a2ce70bb2 100644 --- a/Documentation/user/bootchooser.rst +++ b/Documentation/user/bootchooser.rst @@ -83,7 +83,7 @@ The bootchooser algorithm aborts when all enabled targets (priority > 0) have no remaining attempts left. To prevent ending up in an unbootable system after a number of failed boot -attempts, there is a also a built-in mechanism to reset the counters to their defaults, +attempts, there is also a built-in mechanism to reset the counters to their defaults, controlled by the ``global.bootchooser.reset_attempts`` variable. It holds a list of space-separated flags. Possible values are: @@ -92,6 +92,12 @@ list of space-separated flags. Possible values are: (``$global.system.reset="POR"``) is detected, the ``remaining_attempts`` counters of all enabled targets are reset to their defaults. This means after a power cycle all boot targets will be tried again for the configured number of retries. +- ``reset``: When the bootchooser starts and a generic reset + (``$global.system.reset="RST"``) is detected, the ``remaining_attempts`` + counters of all enabled targets are reset to their defaults. + This means that, if the systems reports a generic restart, the + ``remaining_attempts`` counters of all enabled targets are reset to + their defaults. - ``all-zero``: When the bootchooser starts and the ``remaining_attempts`` counters of all enabled targets are zero, the ``remaining_attempts`` counters of all enabled targets are reset to their defaults. diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst index 983b56deef..b26ada943a 100644 --- a/Documentation/user/booting-linux.rst +++ b/Documentation/user/booting-linux.rst @@ -19,8 +19,10 @@ architecture the bootm command handles different image types. On ARM the following images are supported: * ARM Linux zImage +* ARM64 Linux Image, plain or compressed * U-Boot uImage * barebox images +* FIT images, containing a zImage or Image The images can either be passed directly to the bootm command as argument or in the ``global.bootm.image`` variable: @@ -48,6 +50,14 @@ variable: global.bootm.image=/path/to/zImage bootm +FIT image configurations will be matched by comparing the ``compatible`` property +inside the configuration node with the barebox live tree's ``/compatible``. +It's also possible to select a specific configuration explicitly: + +.. code-block:: sh + + global.bootm.image=/dev/mmc0.fit@conf-imx8mm-evk.dtb + **NOTE:** it may happen that barebox is probed from the devicetree, but you have want to start a Kernel without passing a devicetree. In this case set the ``global.bootm.boot_atag`` variable to ``true``. @@ -153,22 +163,23 @@ setting the ``global.boot.default`` variable to ``mmc`` and then calling .. _bootloader_spec: -Bootloader Spec -^^^^^^^^^^^^^^^ - -barebox supports booting according to the bootloader spec: +Boot Loader Specification +^^^^^^^^^^^^^^^^^^^^^^^^^ -https://systemd.io/BOOT_LOADER_SPECIFICATION/ +barebox supports booting according to the `Boot Loader Specification +<https://uapi-group.org/specifications/specs/boot_loader_specification/>`__ +(sometimes also known as *Bootloader Spec*, *bootspec* or *blspec*). It follows another philosophy than the :ref:`boot_entries`. With Boot Entries booting is completely configured in the bootloader. Bootloader Spec Entries -on the other hand the boot entries are on a boot medium. This gives a boot medium -the possibility to describe where a Kernel is and what parameters it needs. +on the other hand are part of the boot medium. This gives a boot medium +the possibility to describe where a kernel is located and which parameters are +needed to boot it. -All Bootloader Spec Entries are in a partition on the boot medium under ``/loader/entries/*.conf``. -In the Bootloader Spec a boot medium has a dedicated partition to use for -boot entries. barebox is less strict, it accepts Bootloader Spec Entries on -every partition barebox can read. +All Bootloader Spec Entries are located in a partition on the boot medium under +``/loader/entries/*.conf``. According to the Bootloader Spec, a boot medium has +to use a dedicated partition for boot entries. barebox is less strict, it +accepts Bootloader Spec Entries on every partition that barebox can read. A Bootloader Spec Entry consists of key value pairs:: @@ -184,7 +195,7 @@ A Bootloader Spec Entry consists of key value pairs:: All paths are absolute paths in the partition. Bootloader Spec Entries can be created manually, but there also is the ``scripts/kernel-install`` tool to create/list/modify entries directly on a MMC/SD card or other media. To use -it create a SD card / USB memory stick with a /boot partition with type 0xea. +it, create an SD card / USB memory stick with a ``/boot`` partition with type ``0xea``. The partition can be formatted with FAT or EXT4 filesystem. If you wish to write to it from barebox later you must use FAT. The following creates a Bootloader Spec Entry on a SD card: @@ -196,9 +207,9 @@ Spec Entry on a SD card: --kernel=/home/sha/linux/arch/arm/boot/zImage --add-root-option \ --root=/dev/mmcblk0p1 -o "console=ttymxc0,115200" -The entry can be listed with the -l option: +The entry can be listed with the ``-l`` option: -.. code-block:: sh +.. code-block:: none scripts/kernel-install --device=/dev/mmcblk0 -l @@ -209,28 +220,34 @@ The entry can be listed with the -l option: options: console=ttymxc0,115200 root=PARTUUID=0007CB20-01 linux: 11ab7c89d02c4f66a4e2474ea25b2b84.15/linux -When on barebox the SD card shows up as ``mmc1`` then this entry can be booted with -``boot mmc1`` or with setting ``global.boot.default`` to ``mmc1``. - -``machine-id`` is an optional key. If ``global.boot.machine_id`` variable is set to -non-empty value, then barebox accepts only Bootloader Spec entries with ``machine-id`` -key. In case if value of global variable and Bootloader Spec key match each other, -barebox will choose the boot entry for booting. All other Bootloader Spec entries will -be ignored. +When the SD card shows up as ``mmc1`` in barebox, this entry can be booted with +``boot mmc1`` or by setting ``global.boot.default`` to ``mmc1``. -A bootloader spec entry can also reside on an NFS server in which case a RFC2224 -compatible NFS URI string must be passed to the boot command: +A bootloader spec entry can also reside on an NFS server, in which case an +`RFC 2224 <https://datatracker.ietf.org/doc/html/rfc2224>`__-compatible NFS URI +must be passed to the boot command: .. code-block:: sh boot nfs://nfshost[:port]//path/ -Additionally to the options defined in the original spec barebox understands the -``linux-appendroot`` option. This is a boolean value and if set to ``true`` barebox -will automatically append a ``root=`` string to the Linux commandline based on the -device where the entry is found on. This makes it possible to use the same rootfs -image on different devices without having to specify a different root= option each -time. +Additional notes about keys in the bootloader spec entries: + +``machine-id`` + This key is optional. If the ``global.boot.machine_id`` variable is set to a + non-empty value, barebox will only boot the Bootloader Spec Entry whose + ``machine-id`` key matches the ``global.boot.machine_id`` variable. All + other Bootloader Spec entries will be ignored. + +``linux-appendroot`` + This boolean option is understood by Barebox although it is not part of the + original specification. If set to ``true``, barebox will automatically append + a ``root=`` string to the Linux commandline based on the device where the + entry is found on. This makes it possible to use the same rootfs image on + different devices without having to specify a different ``root=`` option each + time. + +.. _booting_linux_net: Network boot ------------ @@ -274,7 +291,7 @@ In any case, make sure that the specified mountpoint is exported by your NFS server. For more information about booting with ``nfsroot``, see -`Documentation/filesystems/nfs/nfsroot.txt <https://github.com/torvalds/linux/blob/master/Documentation/filesystems/nfs/nfsroot.txt>`__ +`Documentation/admin-guide/nfs/nfsroot.rst <https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/nfs/nfsroot.rst>`__ in the Linux kernel documentation. If the preconfigured paths or names are not suitable, they can be adjusted in diff --git a/Documentation/user/defaultenv-2.rst b/Documentation/user/defaultenv-2.rst index a79ae83d56..a01a70fa93 100644 --- a/Documentation/user/defaultenv-2.rst +++ b/Documentation/user/defaultenv-2.rst @@ -19,13 +19,18 @@ All new boards should use defaultenv-2 exclusively. The default environment is composed from different directories during compilation:: - defaultenv/defaultenv-2-base -> base files - defaultenv/defaultenv-2-dfu -> overlay for DFU - defaultenv/defaultenv-2-menu -> overlay for menus - arch/$ARCH/boards/<board>/env -> board specific overlay + defaultenv/defaultenv-2-base -> base files + defaultenv/defaultenv-2-dfu -> overlay for DFU + defaultenv/defaultenv-2-reboot-mode -> overlay for reboot modes + defaultenv/defaultenv-2-menu -> overlay for menus + arch/$ARCH/boards/<board>/defaultenv-<board> -> board specific overlay + $(CONFIG_DEFAULT_ENVIRONMENT_PATH) -> config specific overlay The content of the above directories is applied one after another. If the -same file exists in a later overlay, it will overwrite the preceding one. +same file exists in a later overlay, it will overwrite the preceding one. The +board specific overlay, or overlays, could be at any path, but usually follows +the form given. They must be added to a Makefile in ``bbenv-y`` and +``defaultenv_append_directory()`` used to add them in board init code. Note that not all of the above directories will necessarily be included in your default environment, it depends on your barebox @@ -37,6 +42,7 @@ and their respective included directories in ``defaultenv/Makefile``: bbenv-$(CONFIG_DEFAULT_ENVIRONMENT_GENERIC_NEW) += defaultenv-2-base bbenv-$(CONFIG_DEFAULT_ENVIRONMENT_GENERIC_NEW_MENU) += defaultenv-2-menu bbenv-$(CONFIG_DEFAULT_ENVIRONMENT_GENERIC_NEW_DFU) += defaultenv-2-dfu + bbenv-$(CONFIG_DEFAULT_ENVIRONMENT_GENERIC_NEW_REBOOT_MODE) += defaultenv-2-reboot-mode bbenv-$(CONFIG_DEFAULT_ENVIRONMENT_GENERIC) += defaultenv-1 /env/bin/init @@ -138,3 +144,11 @@ there will be a file ``eth0`` with a content like this: # put code to discover eth0 (i.e. 'usb') to /env/network/eth0-discover exit 0 + +/env/bmode/ +----------- + +This contains the files to be sourced when barebox detects that the OS +had requested a specific :ref:`reboot_mode` (via e.g. ``reboot bootloader`` +under Linux). After the ``/env/init`` scripts were executed, barebox will +``source /env/bmode/${global.system.reboot_mode.prev}`` if available. diff --git a/Documentation/user/devicetree.rst b/Documentation/user/devicetree.rst index 679cae7f00..91afffdcda 100644 --- a/Documentation/user/devicetree.rst +++ b/Documentation/user/devicetree.rst @@ -21,7 +21,7 @@ The internal devicetree ----------------------- The devicetree consulted by barebox plays a special role. It is referred to -as the "internal devicetree." The barebox devicetree commands work on this +as the "internal devicetree" or "live tree". The barebox devicetree commands work on this devicetree. The devicetree source (DTS) files are kept in sync with the kernel DTS files. As the FDT files are meant to be backward compatible, it should always be possible to start a kernel with the barebox internal devicetree. However, since the barebox @@ -75,3 +75,46 @@ It is important to know that these commands normally work on the internal devicetree. If you want to modify the devicetree the kernel is started with see the -f options to of_property and of_node. This option will register the operation for later execution on the Kernel devicetree. + +Device tree overlays +-------------------- + +barebox has support for device tree overlays. barebox knows two different trees, +the live tree and the device tree the kernel is started with. Both can be applied +overlays to. + +Device tree overlays on the live tree +..................................... + +While the live tree can be patched by board code, barebox does not +detect any changes to the live tree. To let the overlays have any effect, board +code must make sure the live tree is patched before the devices are instanciated +from it. + +Device tree overlays on the kernel device tree +.............................................. + +Overlays can be applied to the kernel device tree before it is handed over to +the kernel. The behaviour is controlled by different variables: + +``global.of.overlay.dir`` + Overlays are read from this directory. barebox will try to apply all overlays + found here if not limited by one of the other variables below. When the path + given here is an absolute path it is used as is. A relative path is relative + to ``/`` or relative to the rootfs when using bootloader spec. +``global.of.overlay.compatible`` + This is a space separated list of compatibles. Only overlays matching one of + these compatibles will be applied. When this list is empty then all overlays + will be applied. Overlays that don't have a compatible are considered being + always compatible. +``global.of.overlay.filepattern`` + This is a space separated list of file patterns. An overlay is only applied + when its filename matches one of the patterns. The patterns can contain + ``*`` and ``?`` as wildcards. The default is ``*`` which means all files are + applied. +``global.of.overlay.filter`` + This is a space separated list of filters to apply. There are two generic filters: + ``filepattern`` matches ``global.of.overlay.filepattern`` above, ``compatible`` matches + ``global.of.overlay.compatible`` above. The default is ``filepattern compatible`` + which means the two generic filters are active. This list may be replaced or + supplemented by board specific filters. diff --git a/Documentation/user/driver-model.rst b/Documentation/user/driver-model.rst index a0fd3e99b5..c543d6d9c4 100644 --- a/Documentation/user/driver-model.rst +++ b/Documentation/user/driver-model.rst @@ -88,7 +88,14 @@ The parameters can be used as shell variables: .. code-block:: sh eth0.ipaddr=192.168.23.15 - echo "my current ip is: $eth0.ipaddr" + echo "my current ip is: ${eth0.ipaddr}" + +.. note:: + + Hush shell syntax for defining and setting variables is the same, so + some characters such as hyphens are not allowed on the left hand side + of a shell variable assignment. :ref:`command_setenv`, if enabled, + can still be used to write such a variable though. device variables may have a type, so assigning wrong values may fail: diff --git a/Documentation/user/framebuffer.rst b/Documentation/user/framebuffer.rst index 8b95ad6b87..d17df822f2 100644 --- a/Documentation/user/framebuffer.rst +++ b/Documentation/user/framebuffer.rst @@ -4,9 +4,7 @@ Framebuffer support Framebuffer splash screen ------------------------- -barebox supports BMP and PNG graphics using the :ref:`command_splash` command. barebox -currently has no support for backlights, so unless there is a board specific enable -hook for enabling a display it must be done manually with a script. Since barebox +barebox supports BMP and PNG graphics using the :ref:`command_splash` command. Since barebox has nothing useful to show on the framebuffer it doesn't enable it during startup. A framebuffer can be enabled with the ``enable`` parameter of the framebuffer device: @@ -39,7 +37,7 @@ A typical script to enable the framebuffer could look like this: # wait for signals to become stable msleep 100 - # finally enable backlight + # finally enable backlight manually if no driver exists gpio_direction_output 42 1 Framebuffer console diff --git a/Documentation/user/introduction.rst b/Documentation/user/introduction.rst index 8a980a70ab..63a4c29cba 100644 --- a/Documentation/user/introduction.rst +++ b/Documentation/user/introduction.rst @@ -15,6 +15,8 @@ development binary as well as for lean production systems. Just like busybox is the Swiss Army Knife for embedded Linux, barebox is the Swiss Army Knife for bare metal, hence the name. +.. _feedback: + Feedback -------- @@ -24,6 +26,13 @@ discussion of barebox takes place here: http://lists.infradead.org/mailman/listinfo/barebox/ -There's also an IRC channel: +Mails sent to the barebox mailing list are archived on +`lore.barebox.org <https://lore.barebox.org/barebox/>`_. + +Patch series sent there can be applied with `b4 <https://pypi.org/project/b4/>`_ :: + + git config b4.midmask https://lore.barebox.org/%s + git config b4.linkmask https://lore.barebox.org/%s + b4 shazam -M https://lore.barebox.org/$messageid # replace with link -IRC: #barebox (Freenode) +There's also an IRC channel: #barebox on Libera Chat diff --git a/Documentation/user/multi-image.rst b/Documentation/user/multi-image.rst index 727b98fe5a..3b37d13794 100644 --- a/Documentation/user/multi-image.rst +++ b/Documentation/user/multi-image.rst @@ -51,4 +51,4 @@ generated a different entry point is selected using the ``-e`` option to ld. The linker will throw away all unused entry points and only keep the functions used by a particular entry point. -The Multi Image PBL files can be disassembled with ``make <entry-function-name.pbl.S`` +The Multi Image PBL files can be disassembled with ``make images/<entry-function-name>.pbl.S`` diff --git a/Documentation/user/networking.rst b/Documentation/user/networking.rst index 9231ebde56..2306cb6a60 100644 --- a/Documentation/user/networking.rst +++ b/Documentation/user/networking.rst @@ -45,15 +45,17 @@ device: | | | any directly visible subnet. May be set | | | | automatically by DHCP. | +------------------------------+--------------+------------------------------------------------+ -| global.net.server | hostname or | The default server. If unspecified, may be set | -| | ipv4 address | by DHCP | +| global.net.server | hostname or | The default server used by the defaultenv boot | +| | ipv4 address | scripts for NFS and TFTP; see | +| | | :ref:`booting_linux_net`. | +| | | If unspecified, may be set by DHCP. | +------------------------------+--------------+------------------------------------------------+ | global.net.nameserver | ipv4 address | The DNS server used for resolving host names. | -| | | May be set by DHCP | +| | | May be set by DHCP. | +------------------------------+--------------+------------------------------------------------+ | global.net.ifup_force_detect | boolean | Set to true if your network device is not | | | | detected automatically during start (i.e. for | -| | | USB network adapters) | +| | | USB network adapters). | +------------------------------+--------------+------------------------------------------------+ The first step for networking is configuring the network device. The network diff --git a/Documentation/user/pbl.rst b/Documentation/user/pbl.rst index 6757768e42..b0acd1a4f2 100644 --- a/Documentation/user/pbl.rst +++ b/Documentation/user/pbl.rst @@ -13,8 +13,7 @@ PBL is available for ARM and MIPS. It can be enabled in ``make menuconfig`` with the ``[*] Pre-Bootloader image`` option. The user visible difference is that with PBL support ``barebox.bin`` is no longer -the final binary image, but instead ``arch/$ARCH/pbl/zbarebox.bin``. Use the -``barebox-flash-image`` link which always points to the correct image. +the final binary image, but instead the images are placed in ``images/``. Technical background -------------------- @@ -26,6 +25,6 @@ This way source code can be shared between regular barebox and PBL. A special case is ``lwl-y += file.o`` which expands to ``obj-y`` when PBL is disabled and to ``pbl-y`` when PBL is enabled. -**HINT:** for getting an overview over the binaries, disassemble barebox.bin -(``make barebox.S``) with or without PBL support and also disassemble the -PBL (``make arch/$ARCH/pbl/zbarebox.S``) +**HINT:** for getting an overview over the binaries, disassemble +``barebox.bin`` with or without PBL support and also disassemble the PBL +(``./images/*.pblb``). diff --git a/Documentation/user/reboot-mode.rst b/Documentation/user/reboot-mode.rst new file mode 100644 index 0000000000..1929a67e0b --- /dev/null +++ b/Documentation/user/reboot-mode.rst @@ -0,0 +1,104 @@ +.. _reboot_mode: + +########### +Reboot Mode +########### + +To simplify debugging, many BootROMs sample registers that survive +a warm reset to customize the boot. These registers can e.g. indicate +that boot should happen from a different boot medium. + +Likewise, many bootloaders reuse such registers, or if unavailable, +non-volatile memory to determine whether the OS requested a special +reboot mode, e.g. rebooting into a USB recovery mode. This is +common on Android systems. + +barebox implements the upstream device tree bindings for +`reboot-modes <https://www.kernel.org/doc/Documentation/devicetree/bindings/power/reset/reboot-mode.txt>`_ +to act upon reboot mode protocols specified in the device tree. + +The device tree nodes list a number of reboot modes along with a +magic value for each. On reboot, an OS implementing the binding +would take the reboot command's argument and match it against the +modes in the device tree. If a match is found the associated magic +is written to the location referenced in the device tree node. + +User API +======== + +Devices registered with the reboot mode API gain two parameters: + + - ``$dev_of_reboot_mode.prev`` (read-only): The reboot mode that was + set previously to barebox startup. + - ``$dev_of_reboot_mode.next``: The next reboot mode, for when the + system is reset. Its initial value after startup is 0 which corresponds + to ``normal`` by default. + +The reboot mode driver core use the alias name if available to name +the device. By convention, this should end with ``.reboot_mode``, e.g.:: + + / { + aliases { + gpr.reboot_name = &reboot_name_gpr; + }; + }; + +Reboot mode providers have priorities. The provider with the highest +priority has its parameters aliased as ``$global.system.reboot_mode.prev`` +and ``$global.system.reboot_mode.next``. After executing the init scripts, +barebox startup will ``source /env/bmode/${global.system.reboot_mode.prev}`` +if available. Example usage:: + + gpr.reboot_mode=serial reset -w + +Reset +===== + +Reboot modes can be stored on a syscon wrapping general purpose registers +that survive warm resets. If the system instead did reset via an external +power management IC, the registers may lose their value. + +If such reboot mode storage is used, users must take care to use the correct +reset provider. In barebox, multiple reset providers may co-exist. The +``reset`` command allows listing and choosing a specific reboot mode. + +For communication with the SoC's BootROM, a warm reset can be triggered +with ``reset -w`` if a suitable reset handler has been registered. + +Disambiguation +============== + +Some uses of reboot modes partially overlap with other barebox +functionality. They all ultimately serve different purposes, however. + +Comparison to reset reason +--------------------------- + +The reset reason ``$global.system.reset`` is populated by different drivers +to reflect the hardware cause of a reset, e.g. a watchdog. A reboot mode +describes the OS intention behind a reset, e.g. to fall into a recovery +mode. Reboot modes besides the default ``normal`` mode usually accompany +a reset reason of ``RST`` (because the OS intentionally triggered a reset +to activate the next reboot mode). + +Comparison to bootsource +------------------------ + +``$bootsource`` reflects the current boot's medium as indicated by the +SoC. In cases where the reboot mode is used to communicate with the BootROM, +``$bootsource`` and ``$bootsource_instance`` may describe the same device +as the reboot mode. + +For cases, where the communication instead happens between barebox and an OS, +they can be completely different, e.g. ``$bootsource`` may say barebox was +booted from ``spi-nor``, while the reboot mode describes that barebox should +boot the Kernel off a USB flash drive. + +Comparison to barebox state +--------------------------- + +barebox state also allows sharing information between barebox and the OS, +but it does so while providing atomic updates, redundant storage and +optionally wear leveling. In contrast to state, reboot mode is just that: +a mode for a single reboot. barebox clears the reboot mode after reading it, +so this can be reliably used across one reset only. diff --git a/Documentation/user/remote-control.rst b/Documentation/user/remote-control.rst index c8b7442f17..b285c2297b 100644 --- a/Documentation/user/remote-control.rst +++ b/Documentation/user/remote-control.rst @@ -35,17 +35,15 @@ can also be enabled. Running the bbremote tool ------------------------- -The bbremote host tool is written in python. To run it python2 has to be +The bbremote host tool is written in python. To run it python3 has to be installed with the following additional packages: +----------------+---------------------+ | python package | Debian package name | +================+=====================+ -| crcmod | python-crcmod | +| crcmod | python3-crcmod | +----------------+---------------------+ -| enum | python-enum | -+----------------+---------------------+ -| enum34 | python-enum34 | +| pyserial | python3-serial | +----------------+---------------------+ If your distribution does not provide aforementioned packages, you can @@ -54,7 +52,7 @@ account via: .. code-block:: sh - pip install --user crcmod enum enum34 + python -m pip install --user crcmod pyserial configuring bbremote ^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/user/state.rst b/Documentation/user/state.rst index 78ce24f9ed..9054a37923 100644 --- a/Documentation/user/state.rst +++ b/Documentation/user/state.rst @@ -24,7 +24,7 @@ barebox itself uses a *state* driver to access the variables in the persistent memory. Currently there is only one implementation, enabled by -``CONFIG_STATE_DRV=y``. Without driver, the state framework will silently +``CONFIG_STATE_DRV=y``. Without driver, the state framework will silently fail and be non-functional. For the Linux run-time there is a userspace tool_ to do @@ -540,22 +540,14 @@ content, its backend-type and *state* variable layout. SD/eMMC and ATA ############### -The following devicetree node entry defines some kind of SD/eMMC memory and -a partition at a specific offset inside it to be used as the backend for the -*state* variable set. Note that currently there is no support for on-disk -partition tables. Instead, an ofpart partition description must be used. You -have to make sure that this partition does not conflict with any other partition -in the partition table. - -.. code-block:: text - - backend_state_sd: part@100000 { - label = "state"; - reg = <0x100000 0x20000>; - }; +*state* node definition +^^^^^^^^^^^^^^^^^^^^^^^ -With this 'backend' definition it's possible to define the *state* variable set -content, its backend-type and *state* variable layout. +These storage types have integrated wear-levelling and can be addressed on the +byte level. The *raw* backend type is suitable for this situation. +We will explain the possible variants of referring to a backend below, +but an exemplary definition of the *state* layout and variable set will look +as follows: .. code-block:: text @@ -579,6 +571,88 @@ content, its backend-type and *state* variable layout. }; }; + +Backend definition +^^^^^^^^^^^^^^^^^^ + +SD/eMMC and ATA devices usually have an on-disk partition table (MBR or GPT), +which Barebox will parse when a block device is probed. +There are multiple options to refer to these partitions as the *state* backend +(i.e. the ``&backend_state_sd`` reference in the example above). + +Referencing the partition by GUID +""""""""""""""""""""""""""""""""" + +When using GPT, the backend reference may point directly to a block device's +device tree node. In this case Barebox will search for a GPT partition with Type +UUID ``4778ed65-bf42-45fa-9c5b-287a1dc4aab1``, and if that partition exists, +Barebox will use it as the *state* backend. + +Here is an abridged example: + +.. code-block:: text + + / { + soc { + bus@2100000 { + mmc1: mmc@2190000 { + // … MMC device definition … + }; + }; + + aliases { + state = &state_sd; + }; + + state_sd: state { + backend = <&mmc1>; + // … rest of definition as per above section + }; + }; + +This is the recommended approach for device tree enabled system with state +located on SD or eMMC. + +Referencing the partition by *partuuid* +""""""""""""""""""""""""""""""""""""""" + +For systems where block devices are not probed from device tree (e.g. with +storage on ATA or PCI buses), the *state* partition can be looked up globally +by specifying its *partuuid*. See the documentation for the :ref:`partuuid +device tree binding <devicetree_binding_mtd_partition>` for more details. + +The *partuuid* is expected to be unique across all block devices. + +Referencing the partition by offset +""""""""""""""""""""""""""""""""""" + +As a fallback it is still possible to refer to the *state* partition by +specifying its offset and size, like in the examples for NAND and NOR flash +above: + +.. code-block:: text + + &mmc1 { + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + […] + backend_state_sd: partition@100000 { + label = "state"; + reg = <0x100000 0x20000>; + }; + }; + }; + +.. note:: + + If the medium has an on-disk partition table, the device tree partition + must either be identical in start offset and size to the MBR/GPT partition + or it must reside in non-partitioned space. If this constraint is not + satisfied, barebox will emit an error message and refuse to register + the device tree partition. + SRAM #### @@ -684,9 +758,9 @@ Frontend -------- As frontend a *state* instance is a regular barebox device which has -device parameters for the *state* variables. With this the variables can +:ref:`device_parameters` for the *state* variables. With this the variables can be accessed like normal shell variables. The ``state`` command is used to save/restore a *state* variable set to the backend device. -After initializing the variable can be accessed with ``$state.foo``. -``state -s`` stores the *state* to the backend device. +After initializing the variable can be accessed with ``${state.foo}`` or +:ref:`command_setenv`. ``state -s`` stores the *state* to the backend device. diff --git a/Documentation/user/system-reset.rst b/Documentation/user/system-reset.rst index e76e3a23c1..bf7369d06f 100644 --- a/Documentation/user/system-reset.rst +++ b/Documentation/user/system-reset.rst @@ -31,7 +31,7 @@ But there are some drawbacks within this simple approach. * some SoC's boot behaviour gets parametrized by so called 'bootstrap pins'. These pins can have a different meaning at reset time and at run-time later on (multi purpose pins) but their correct values at reset time are very - important to boot the SoC sucessfully. If external devices are connected to + important to boot the SoC successfully. If external devices are connected to these multi purpose pins they can disturb the reset values, and so parametrizing the boot behaviour differently and hence crashing the SoC until the next real POR happens which also resets the external devices (and keep them away from the diff --git a/Documentation/user/usb.rst b/Documentation/user/usb.rst index 4c1b2925f2..7eb360d629 100644 --- a/Documentation/user/usb.rst +++ b/Documentation/user/usb.rst @@ -13,9 +13,9 @@ devices are not disconnected while barebox is running. USB Networking ^^^^^^^^^^^^^^ -barebox supports ASIX-compatible devices and the SMSC95xx. After -detection, the device shows up as eth0 and can be used like a regular network -device. +barebox supports r8152, ASIX-compatible devices and the SMSC95xx. After +detection, the device shows up as an extra network device (e.g. eth1) and +can be used like a regular network device. To use a USB network device together with the :ref:`command_ifup` command, add the following to ``/env/network/eth0-discover``: @@ -26,6 +26,9 @@ following to ``/env/network/eth0-discover``: usb +Alternatively, a ``detect -a`` (all) can be forced in ``ifup`` by setting +``global.net.ifup_force_detect=1``. + USB mass storage ^^^^^^^^^^^^^^^^ @@ -39,18 +42,21 @@ barebox supports several different USB gadget drivers: - Device Firmware Upgrade (DFU) - Android Fastboot +- USB mass storage - serial gadget The recommended way to use USB gadget is with the :ref:`command_usbgadget` command. While there are individual commands for :ref:`command_dfu` and :ref:`command_usbserial`, -the :ref:`command_usbgadget` commands supports registering composite gadgets. +the :ref:`command_usbgadget` commands supports registering composite gadgets, which +exports multiple functions at once. This happens in the "background" without impacting +use of the shell. Partition description ^^^^^^^^^^^^^^^^^^^^^ -The USB gadget commands for Android Fastboot and DFU take a partition description -which describes which barebox partitions are exported via USB. The partition -description is referred to as ``<desc>`` in the command help texts. It has +The USB gadget commands for Android Fastboot, DFU and the mass storage gadget +take a partition description which describes which barebox partitions are exported via USB. +The partition description is referred to as ``<desc>`` in the command help texts. It has the general form ``partition(name)flags,partition(name)flags,...``. The **partition** field is the partition as accessible in barebox. This can be a @@ -65,6 +71,8 @@ Several **flags** are supported, each denoted by a single character: * ``r`` Readback. The partition is allowed to be read back (DFU specific) * ``c`` The file shall be created if it doesn't exist. Needed when a regular file is exported. * ``u`` The partition is a MTD device and shall be flashed with a UBI image. +* ``o`` The partition is optional, i.e. if it is not available at initialization time, it is skipped + instead of aborting the initialization. This is currently only supported for fastboot. Example: @@ -72,6 +80,22 @@ Example: /dev/nand0.barebox.bb(barebox)sr,/kernel(kernel)rc +Board code authors are encouraged to provide a default environment containing +partitions with descriptive names. For boards where this is not specified, +there exist a number of **partition** specifiers for automatically generating entries: + +* ``block`` exports all registered block devices (e.g. eMMC and SD) +* ``auto`` currently equivalent to ``block``. May be extended to other flashable + devices, like EEPROMs, MTD or UBI volumes in future + +Example usage of exporting registered block devices, barebox update +handlers and a single file that is created on flashing: + +.. code-block:: sh + + detect -a # optional. Detects everything, so auto can register it + usbgadget -A auto,/tmp/fitimage(fitimage)c -b + DFU ^^^ @@ -144,12 +168,13 @@ The Fastboot gadget supports the following commands: ``fastboot flash`` additionally supports image types UBI and Barebox. For UBI Images and a MTD device as target, ubiformat is called. For a Barebox image with an available barebox update handler for the fastboot exported device, the -barebox_update is called. +barebox_update is called (exported as ``bbu-<update_handler_name>`` fastboot +partition). The barebox Fastboot gadget supports the following non standard extensions: - ``fastboot getvar all`` - Shows a list of all variables + Shows a list of all variables, including exported partitions - ``fastboot oem getenv <varname>`` Shows a barebox environment variable - ``fastboot oem setenv <varname>=<value>`` @@ -206,6 +231,16 @@ and initrd: fi timeout -k 5 3 fastboot -i 7531 oem exec -- bootm -o /devicetree -r /initrd /kernel +USB Mass storage gadget +^^^^^^^^^^^^^^^^^^^^^^^ + +Example exporting barebox block devices to a USB host: + +.. code-block:: sh + + usbgadget -S /dev/mmc0(emmc),/dev/mmc1(sd) + + USB Composite Multifunction Gadget ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -227,7 +262,7 @@ after creating the gadget. The gadget can be removed with ``usbgadget -d``. USB OTG support --------------- -barebox does not have USB OTG support. However, barebox supports some USB cores in +barebox does not have true USB OTG support. However, barebox supports some USB cores in both host and device mode. If these are specified for otg in the device tree (dr_mode = "otg";) barebox registers a OTG device which can be used to decide which mode shall be used. The device has a ``mode`` parameter which by default has the @@ -246,6 +281,21 @@ mode. Once a specific mode has been selected it can't be changed later anymore. musb-hdrc: 28/31 max ep, 16384/16384 memory barebox:/ +USB Type-C support +------------------ + +barebox can usually stay oblivious to the type of connector used. Sometimes though, +board code and user scripts may want to base their decisions on how a USB-C connector +is connected. Type C drivers can thus register with the Type C driver core to +export a number of device parameters: + +- ``$typec0.usb_role`` = { ``none``, ``device``, ``host`` } +- ``$typec0.pwr_role`` = { ``sink``, ``source`` } +- ``$typec0.accessory`` = { ``none``, ``audio``, ``debug`` } + +Currently, only the TUSB320 is supported, but it's straight-forward to port more +drivers from Linux. + USB Gadget autostart Support ---------------------------- @@ -264,9 +314,14 @@ USB Gadget autostart Options ``global.usbgadget.acm`` Boolean flag. If set to 1, CDC ACM function will be created. See :ref:`command_usbgadget` -a. (Default 0). +``global.system.partitions`` + Common function description for all of DFU, fastboot and USB mass storage + gadgets. Both Fastboot and DFU partitions also have dedicated override + variables for backwards-compatibility: + ``global.usbgadget.dfu_function`` Function description for DFU. See :ref:`command_usbgadget` -D [desc]. -``global.usbgadget.fastboot_function`` +``global.fastboot.partitions`` Function description for fastboot. See :ref:`command_usbgadget` -A [desc]. -``global.usbgadget.fastboot_bbu`` +``global.fastboot.bbu`` Export barebox update handlers. See :ref:`command_usbgadget` -b. (Default 0). diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst index 827683eaa0..565e6c11f8 100644 --- a/Documentation/user/user-manual.rst +++ b/Documentation/user/user-manual.rst @@ -36,6 +36,8 @@ Contents: optee debugging watchdog + reboot-mode + virtio * :ref:`search` * :ref:`genindex` diff --git a/Documentation/user/virtio.rst b/Documentation/user/virtio.rst new file mode 100644 index 0000000000..046e5dac82 --- /dev/null +++ b/Documentation/user/virtio.rst @@ -0,0 +1,88 @@ +.. + SPDX-License-Identifier: GPL-2.0+ + + Copyright (C) 2018, Bin Meng <bmeng.cn@gmail.com> + Copyright (C) 2021, Ahmad Fatoum + +.. _virtio_sect: + +VirtIO Support +============== + +This document describes the information about barebox support for VirtIO_ +devices, including supported boards, build instructions, driver details etc. + +What's VirtIO? +-------------- + +VirtIO is a virtualization standard for network and disk device drivers where +just the guest's device driver "knows" it is running in a virtual environment, +and cooperates with the hypervisor. This enables guests to get high performance +network and disk operations, and gives most of the performance benefits of +paravirtualization. In the barebox case, the guest is barebox itself, while the +virtual environment will normally be QEMU_ targets like ARM, MIPS, RISC-V or x86. + +Status +------ + +VirtIO can use various different buses, aka transports as described in the +spec. While VirtIO devices are commonly implemented as PCI devices on x86, +embedded devices models like ARM/RISC-V, which does not normally come with +PCI support might use simple memory mapped device (MMIO) instead of the PCI +device. The memory mapped virtio device behaviour is based on the PCI device +specification. Therefore most operations including device initialization, +queues configuration and buffer transfers are nearly identical. Both MMIO +and non-legacy PCI are supported in barebox. + +The VirtIO spec defines a lots of VirtIO device types, however at present only +block, network, console, input and RNG devices are supported. + +Build Instructions +------------------ + +Building barebox for QEMU targets is no different from others. +For example, we can do the following with the CROSS_COMPILE environment +variable being properly set to a working toolchain for ARM:: + + $ make multi_v7_defconfig + $ make + +Testing +------- + +The following QEMU command line is used to get barebox up and running with +a VirtIO console on ARM:: + + $ qemu-system-arm -m 256M -M virt -nographic \ + -kernel ./images/barebox-dt-2nd.img \ + -device virtio-serial-device \ + -chardev socket,path=/tmp/foo,server,nowait,id=foo \ + -device virtconsole,chardev=foo,name=console.foo + +To access the console socket, you can use ``socat /tmp/foo -``. + +Note the use of ``-kernel ./images/barebox-dt-2nd.img`` instead of +``-bios ./images/barebox-$BOARD.img``. ``-kernel`` will cause QEMU +to pass barebox a fixed-up device tree describing the ``virtio-mmio`` +rings. + +Except for the console, multiple instances of a VirtIO device can be created +by appending more '-device' parameters. For example to extend a MIPS +malta VM with one HWRNG and 2 block VirtIO PCI devices:: + + $ qemu-system-mips -m 256M -M malta -serial stdio \ + -bios ./images/barebox-qemu-malta.img -monitor null \ + -device virtio-rng-pci \ + -drive if=none,file=image1.hdimg,format=raw,id=hd0 \ + -device virtio-blk-pci,drive=hd0 \ + -drive if=none,file=image2.hdimg,format=raw,id=hd1 \ + -device virtio-blk-pci,drive=hd1 + +Note that barebox does not support non-transitional legacy Virt I/O devices. +Depending on QEMU version used, it may be required to add +``disable-legacy=on``, ``disable-modern=off`` or both, e.g.:: + + -device virtio-blk-pci,drive=hd1,disable-legacy=on,disable-modern=off + +.. _VirtIO: http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.pdf +.. _qemu: https://www.qemu.org diff --git a/Documentation/user/watchdog.rst b/Documentation/user/watchdog.rst index 02bd576a89..0220965598 100644 --- a/Documentation/user/watchdog.rst +++ b/Documentation/user/watchdog.rst @@ -10,6 +10,15 @@ the bootloader. For these scenarios barebox provides the watchdog framework with the following functionality and at least ``CONFIG_WATCHDOG`` should be enabled. +Disabling for development +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The shorthand command ``wd -x`` will disable all watchdogs. +If hardware (or driver) doesn't support turning off the watchdog, +an autpoller will be registered to periodically feed watchdogs. +This should only be needed for development. +See :ref:`boot-watchdog-timeout` for how to use the watchdog in the field. + Polling ~~~~~~~ @@ -57,6 +66,9 @@ measured in seconds: barebox@DPTechnics DPT-Module:/ devinfo wdog0 Parameters: autoping: 1 (type: bool) + priority: 100 (type: uint32) + running: 1 (type: enum) (values: "unknown", "1", "0") + seconds_to_expire: 7 (type: uint32) timeout_cur: 7 (type: uint32) timeout_max: 10 (type: uint32) @@ -67,6 +79,36 @@ Use barebox' environment to persist these changes between reboots: nv dev.wdog0.autoping=1 nv dev.wdog0.timeout_cur=7 +Watchdog State +~~~~~~~~~~~~~~ + +To check whether a watchdog is currently running, the ``running`` device +parameter can be consulted. Not all watchdog devices (or their drivers) +provide the information whether a watchdog was running prior to barebox. +In that case, the parameter will contain the value ``unknown``. + +Watchdogs started by barebox can be monitored using the +``seconds_to_expire`` parameter. A well-behaving system of watchdog +device, watchdog driver and clocksource should reset as soon as the +count down reaches zero. + +To manually start a watchdog, :ref:`command_wd` can be used. + +Default Watchdog +~~~~~~~~~~~~~~~~ + +barebox supports multiple concurrent watchdogs. The default watchdog used +with :ref:`command_wd`, ``boot.watchdog_timeout`` and :ref:`command_boot`'s +``-w`` option is the one with the highest positive priority. +If multiple watchdogs share the same priority, only one will be affected. + +The priority is initially set by drivers and can be overridden in the +device tree or via the ``priority`` device parameter. Normally, watchdogs +that have a wider effect should be given the higher priority (e.g. +PMIC watchdog resetting the board vs. SoC's watchdog resetting only itself). + +.. _boot-watchdog-timeout: + Boot Watchdog Timeout ~~~~~~~~~~~~~~~~~~~~~ @@ -85,7 +127,4 @@ or persistently by nv boot.watchdog_timeout=10 where the used value again is measured in seconds. - -On a system with multiple watchdogs, the watchdog with the highest positive -priority is the one affected by the ``boot.watchdog_timeout`` parameter. If -multiple watchdogs share the same priority, only one will be started. +Only the default watchdog will be started. |