diff options
Diffstat (limited to 'Documentation')
85 files changed, 3742 insertions, 535 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 5c36dc3ec5..e8b2851d25 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0-only + build commands html diff --git a/Documentation/boards/aarch64-qemu-virt.rst b/Documentation/boards/aarch64-qemu-virt.rst index e21791af16..8bf590a7a8 100644 --- a/Documentation/boards/aarch64-qemu-virt.rst +++ b/Documentation/boards/aarch64-qemu-virt.rst @@ -1,14 +1,18 @@ -Aarch64 -======= - Aarch64 Qemu virt ------------------ +================= + +Besides a number of physical ARM64 targets, barebox also supports the +``qemu-virt64`` board in the generic ``multi_v8_defconfig``:: + + make multi_v8_defconfig + make Running barebox on QEMU aarch64 virt machine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Usage:: + $ qemu-system-aarch64 -m 2048M \ -cpu cortex-a57 -machine virt \ -display none -serial stdio \ - -kernel ../barebox/barebox + -kernel ./images/barebox-dt-2nd.img diff --git a/Documentation/boards/arm-qemu-vexpress.rst b/Documentation/boards/arm-qemu-vexpress.rst index 010eae04a2..335af46990 100644 --- a/Documentation/boards/arm-qemu-vexpress.rst +++ b/Documentation/boards/arm-qemu-vexpress.rst @@ -7,6 +7,9 @@ ARM Qemu vexpress Running barebox on QEMU vexpress machine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Images for the vexpress platform are built as part of the +multi_v7_defconfig. + Usage:: $ qemu-system-arm -m 1024M \ diff --git a/Documentation/boards/at91.rst b/Documentation/boards/at91.rst index f25cb01bb1..961ef58d84 100644 --- a/Documentation/boards/at91.rst +++ b/Documentation/boards/at91.rst @@ -21,7 +21,32 @@ processor and then load and execute barebox. AT91 boards ----------- -The majority of the supported boards have a short entry here. +Newer boards can be built with the ``at91_multi_defconfig``: + +.. code-block:: sh + + make ARCH=arm at91_multi_defconfig + +The resulting images will be placed under ``images/``: + +:: + + barebox-at91sam9x5ek.img + barebox-at91sam9263ek.img + barebox-microchip-ksz9477-evb.img + barebox-microchip-ksz9477-evb-xload-mmc.img + barebox-microchip-sama5d3-eds.img + barebox-microchip-sama5d3-eds-xload-mmc.img + barebox-sama5d3-xplained.img + barebox-sama5d3-xplained-xload-mmc.img + barebox-sama5d27-som1-ek.img + barebox-sama5d27-som1-ek-xload-mmc.img + barebox-groboards-sama5d27-giantboard.img + barebox-groboards-sama5d27-giantboard-xload-mmc.img + barebox-skov-arm9cpu.img + +Older supported boards have yet to be migrated to multi-image and device tree. +The majority of these have a short entry here. For each board defconfig file(s) are noted but barebox may include additional defconfig files and may also include boards not included in the following. @@ -35,17 +60,7 @@ TODO ---- This is a list of AT91 specific TODO items, listed in no particular order. -* fix prototype for barebox_arm_reset_vector. Introduce the prototype: - -.. code-block:: c - - void __naked __bare_init barebox_arm_reset_vector(uint32_t r0, uint32_t r1, uint32_t r2) - - -This will unify the prototype for the reset vector for multi image and standalone images - * Update remaining boards to DT * Update remaing boards to support multi image boot -* Get bootstrap working in combination with multi image * Introduce defaultenv2 for all boards * Add pwm driver (required to support backlight) diff --git a/Documentation/boards/at91/microchip-ksz9477-evb.rst b/Documentation/boards/at91/microchip-ksz9477-evb.rst deleted file mode 100644 index 4c4c4aecbf..0000000000 --- a/Documentation/boards/at91/microchip-ksz9477-evb.rst +++ /dev/null @@ -1,11 +0,0 @@ -Microchip KSZ 9477 Evaluation board -=================================== - -This is an evaluation board for a switch that uses the at91sam9x5 CPU. -The board uses Device Tree and supports multi image. - -Building barebox: - -.. code-block:: sh - - make ARCH=arm microchip_ksz9477_evb_defconfig diff --git a/Documentation/boards/at91/microchip-sama5d3-xplained.rst b/Documentation/boards/at91/microchip-sama5d3-xplained.rst deleted file mode 100644 index e96111af72..0000000000 --- a/Documentation/boards/at91/microchip-sama5d3-xplained.rst +++ /dev/null @@ -1,8 +0,0 @@ -Atmel SAMA5D3_XPLAINED Evaluation Kit -===================================== - -Building barebox: - -.. code-block:: sh - - make ARCH=arm sama5d3_xplained_defconfig diff --git a/Documentation/boards/bcm2835.rst b/Documentation/boards/bcm2835.rst index e9ad1d4d57..f7ab723d63 100644 --- a/Documentation/boards/bcm2835.rst +++ b/Documentation/boards/bcm2835.rst @@ -4,25 +4,50 @@ Broadcom BCM283x Raspberry Pi ------------ +barebox has support for BCM283x-based Raspberry Pi single board computers. +Support is most extensive for BCM283[567], but barebox can also boot Linux +over SD or Ethernet on the Raspberry Pi 4. + 1. Prepare an SD or microSD card with a FAT filesystem of at least 30 MB in size. - 2. Download the `Raspberry Pi firmware`_ (120 MB), unzip it, and copy the + 2. Download the `Raspberry Pi firmware`_ (195 MB), unzip it, and copy the contents of the ``boot/`` folder to your card. - 3. Use ``make rpi_defconfig; make`` to build barebox. This will create the following images: + 3. Use ``make rpi_defconfig; make`` to build barebox for 32-bit boards or + ``make rpi_v8a_defconfig; make`` to build barebox for 64-bit. + + ``rpi_defconfig`` will build at least following images: - - ``images/barebox-raspberry-pi-1.img`` for the BCM2835/ARM1176JZF-S (Raspberry Pi 1) + - ``images/barebox-raspberry-pi-1.img`` for the BCM2835/ARM1176JZF-S (Raspberry Pi 1, Raspberry Pi Zero) - ``images/barebox-raspberry-pi-2.img`` for the BCM2836/CORTEX-A7 (Raspberry Pi 2) - - ``images/barebox-raspberry-pi-3.img`` for the BCM2837/CORTEX-A53 (Raspberry Pi 3, Raspberry Pi Zero) + - ``images/barebox-raspberry-pi-3.img`` for the BCM2837/CORTEX-A53 (Raspberry Pi 3) + - ``images/barebox-raspberry-pi-cm3.img`` for the BCM2837/CORTEX-A53 (Raspberry Pi CM3) + - ``images/barebox-raspberry-pi.img``, which is a super set of all the other images, + including Raspberry Pi 4 32-bit support. Copy the respective image for your model to your SD card and name it ``barebox.img``. + For 64-bit, only ``images/barebox-raspberry-pi.img`` will be created, which is usable + for both Raspberry Pi 3 and Raspberry Pi 4 in 64-bit mode. No support for the Raspberry + Pi 5 has been contributed yet. + + The ``images/barebox-raspberry-pi.img`` is expected to be the sole image for 32-bit + also in the future. It contains the device trees of all supported (and enabled) variants + and determines at runtime what board it runs on and does the right thing. + 4. Create a text file ``config.txt`` on the SD card with the following content:: kernel=barebox.img enable_uart=1 + If you want to use the mini-uart instead of the PL011, you may need to additionally set:: + + uart_2ndstage=1 + + This is required on boards, like the Raspberry Pi Zero W, that use the mini-uart as the + primary UART. It is needed on boards like the CM3 as well if the mini-uart is to be used. + (For more information, refer to the `documentation for config.txt`_.) 5. Connect to board's UART (115200 8N1); @@ -40,5 +65,5 @@ The original command-line from VideoCore device tree is available to the Barebox global linux.bootargs.vc="$global.vc.bootargs" -.. _Raspberry Pi firmware: https://codeload.github.com/raspberrypi/firmware/zip/80e1fbeb78f9df06701d28c0ed3a3060a3f557ef +.. _Raspberry Pi firmware: https://github.com/raspberrypi/firmware/archive/refs/tags/1.20220331.zip .. _documentation for config.txt: https://www.raspberrypi.org/documentation/configuration/config-txt/ diff --git a/Documentation/boards/efi.rst b/Documentation/boards/efi.rst index f04b1d3237..b12433014e 100644 --- a/Documentation/boards/efi.rst +++ b/Documentation/boards/efi.rst @@ -294,18 +294,19 @@ HOWTOs in the net, for example on http://tianocore.sourceforge.net/wiki/Using_ED git clone git://github.com/tianocore/edk2.git cd edk2 + git submodule update --init make -C BaseTools . edksetup.sh At least the following lines in ``Conf/target.txt`` should be edited:: - ACTIVE_PLATFORM = MdeModulePkg/MdeModulePkg.dsc + ACTIVE_PLATFORM = NetworkPkg/NetworkPkg.dsc TARGET_ARCH = X64 TOOL_CHAIN_TAG = GCC48 MAX_CONCURRENT_THREAD_NUMBER = 4 The actual build is started with invoking ``build``. After building -``Build/MdeModule/DEBUG_GCC48/X64/SnpDxe.efi`` should exist. +``Build/NetworkPkg/DEBUG_GCC48/X64/SnpDxe.efi`` should exist. **NOTE** As of this writing (July 2014) the following patch was needed to compile EDK2. diff --git a/Documentation/boards/emulated.rst b/Documentation/boards/emulated.rst new file mode 100644 index 0000000000..a67533613e --- /dev/null +++ b/Documentation/boards/emulated.rst @@ -0,0 +1,75 @@ +Emulated targets +================ + +Some targets barebox runs on are virtualized by emulators like QEMU, which +allows basic testing of barebox functionality without the actual hardware. + +Generic DT image +---------------- + +Supported for ARM and RISC-V. It generates a barebox image that can +be booted with the Linux kernel booting convention, which makes +it suitable to be passed as argument to the QEMU ``-kernel`` option +(as well as booted just like Linux from barebox or other bootloaders). + +The device tree can be passed externally via QEMU's ``-dtb`` option, but +also the QEMU internal device tree can be used. + +The latter can be very useful with :ref:`virtio_sect`, because QEMU will +fix up the virtio mmio regions into the device tree and barebox will +discover the devices automatically, analogously to what it does with +VirtIO over PCI. + +test/emulate.pl +--------------- + +The ``emulate.pl`` script shipped with barebox can be used to easily +start VMs. It reads a number of YAML files in ``test/$ARCH``, which +describe some virtualized targets that barebox is known to run on. + +Controlled by command line options, these targets are built with +tuxmake if available and loaded into the emulator for either interactive +use or for automated testing with Labgrid ``QEMUDriver``. + +.. _tuxmake: https://pypi.org/project/tuxmake/ +.. _Labgrid: https://labgrid.org + +Install dependencies for interactive use:: + + cpan YAML::XS # or use e.g. libyaml-libyaml-perl on Debian + pip3 install tuxmake # optional + +Example usage:: + + # Switch to barebox source directory + cd barebox + + # emulate x86 VM runnig the EFI payload from efi_defconfig + ARCH=x86 ./test/emulate.pl efi_defconfig + + # build all MIPS targets known to emulate.pl and exit + ARCH=mips ./test/emulate.pl --no-emulate + +The script can also be used with a precompiled barebox tree:: + + # Switch to build directory + export KBUILD_OUTPUT=build + + # run a barebox image built outside tuxmake on an ARM virt machine + ARCH=arm ./test/emulate.pl virt@multi_v7_defconfig --no-tuxmake + + # run tests instead of starting emulator interactively + ARCH=arm ./test/emulate.pl virt@multi_v7_defconfig --no-tuxmake --test + +``emulate.pl`` also has some knowledge on paravirtualized devices:: + + # Run target and pass a block device (here /dev/virtioblk0) + ARCH=riscv ./test/emulate.pl --blk=rootfs.ext4 rv64i_defconfig + +Needed command line options can be passed directly to the +emulator/``pytest`` as well by placing them behind ``--``:: + + # appends -device ? to the command line. Add -n to see the final result + ARCH=riscv ./test/emulate.pl rv64i_defconfig -- -device ? + +For a complete listing of options run ``./test/emulate.pl -h``. diff --git a/Documentation/boards/ibase-mi991af.rst b/Documentation/boards/ibase-mi991af.rst index a22e5fcf79..8e40a0d657 100644 --- a/Documentation/boards/ibase-mi991af.rst +++ b/Documentation/boards/ibase-mi991af.rst @@ -40,4 +40,4 @@ To continue please proceed with barebox :ref:`barebox_on_uefi` documentation. Links ----- - * https://www.ibase.com.tw/english/ProductDetail/EmbeddedComputing/MI991 + * https://www.ibase.com.tw/english/ProductDetail/EmbeddedComputing/MI991 diff --git a/Documentation/boards/imx.rst b/Documentation/boards/imx.rst index 8fe0a2828d..1324659983 100644 --- a/Documentation/boards/imx.rst +++ b/Documentation/boards/imx.rst @@ -21,7 +21,7 @@ The Internal Boot Mode is supported on: * i.MX53 * i.MX6 * i.MX7 -* i.MX8MQ +* i.MX8M With the Internal Boot Mode, the images contain a header which describes where the binary shall be loaded and started. These headers also contain @@ -64,8 +64,8 @@ of the image to the card, use: dd if=images/barebox-freescale-imx51-babbage.img of=/dev/sdd bs=1024 skip=1 seek=1 -Note that MaskROM on i.MX8 expects the image to start at the +33KiB mark, so the -following command has to be used instead: +Note that MaskROM on i.MX8M expects the image to start at the +33KiB mark, so +the following command has to be used instead: .. code-block:: sh @@ -83,6 +83,42 @@ The images can also always be started as second stage on the target: barebox@Board Name:/ bootm /mnt/tftp/barebox-freescale-imx51-babbage.img +BootROM Reboot mode codes (bmode) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For selected SoCs, barebox supports communicating an alternative boot medium +that the BootROM should select after a warm reset:: + + barebox@FSL i.MX8MM EVK board:/ devinfo gpr.reboot_mode + Driver: syscon-reboot-mode + Bus: platform + Parent: 30390000.reset-controller@30390000.of + Parameters: + next: normal (type: enum) (values: "normal", "serial") + prev: normal (type: enum) (values: "normal", "serial") + Device node: /soc@0/bus@30000000/reset-controller@30390000/reboot-mode + reboot-mode { + compatible = "barebox,syscon-reboot-mode"; + offset = <0x94 0x98>; + mask = <0xffffffff 0x40000000>; + mode-normal = <0x0 0x0>; + mode-serial = <0x10 0x40000000>; + }; + + barebox@FSL i.MX8MM EVK board:/ gpr.reboot_mode.next=serial reset -w + +The example above will cause barebox to jump back into serial download mode on +an i.MX8MM by writing 0x10 into the *SRC_GPR9* register (offset 0x30390094) and +0x40000000 into the *SRC_GPR10* register (offset 0x30390098), and then issuing a +warm :ref:`reset <command_reset>`. + +Different SoCs may have more possible reboot modes available. +Look for documentation of the *SRC_SBMR* and *SRC_GPR* registers in the +Reference Manual of your SoC; the values for the ``mode-*`` properties often +correspond directly to the boot fusemap settings. + +See the section on :ref:`Reboot modes<reboot_mode>` for general information. + High Assurance Boot ^^^^^^^^^^^^^^^^^^^ @@ -95,7 +131,7 @@ barebox supports generating signed images, signed USB images suitable for *imx-usb-loader* and encrypted images. In contrast to normal (unsigned) images booting signed images via -imx-usb-loader requires special images: +imx-usb-loader on i.MX6 (but not in i.MX8M) requires special images: DCD data is invalidated (DCD pointer set to zero), the image is then signed and afterwards the DCD pointer is set to the DCD data again (practically making the signature invalid). @@ -114,7 +150,7 @@ Unlike the typical ``imximg`` file extension the following ones are used for these cases: * ``simximg``: generate signed image -* ``usimximg``: generate signed USB image +* ``usimximg``: generate signed USB image (i.MX6-specific) * ``esimximg``: generate encrypted and signed image The imx-image tool is then automatically called with the appropriate flags @@ -132,16 +168,63 @@ keys/certificates are expected in these config variables (assuming HABv4): CONFIG_HABV4_IMG_CRT_PEM A CSF template is located in -``arch/arm/mach-imx/include/mach/habv4-imx6-gencsf.h`` which is preprocessed +``include/mach/imx/habv4-imx*-gencsf.h`` which is preprocessed by barebox. -It must be included in the board's flash header: +It must be included in the board's flash header, e.g. for i.MX6: .. code-block:: none - #include <mach/habv4-imx6-gencsf.h> + #include <mach/imx/habv4-imx6-gencsf.h> Analogous to HABv4 options and a template exist for HABv3. +To verify HAB working as intended, install the ``barebox-*-s.img`` onto the +boot medium and trigger a power-on reset. barebox will read the HAB log on +startup and report any errors it finds. A good unfused boot looks like this:: + + HABv4: Status: Operation completed successfully (0xf0) + HABv4: Config: Non-secure IC (0xf0) + HABv4: State: Non-secure state (0x66) + HABv4: No HAB Failure Events Found! + +To have the bootrom verify the barebox binary, the SRK hash needs to be burnt +into the fuses. As fuses can't be unburnt, the ``hab`` command should be used +instead of direct device access to not risk writing unrelated fuses:: + + barebox$ hab -p -s SRK_1_2_3_4_fuse.bin + +Afterwards, images signed with a different key will trigger errors at barebox +startup, but system will still be able to boot to shell. + +To have the BootROM refuse booting differently signed images, the ``SRK_LOCK`` +fuse needs to be burnt:: + + barebox$ hab -p -l + +On next startup, barebox will report that the system is now locked:: + + HABv4: Status: Operation completed successfully (0xf0) + HABv4: Config: Secure IC (0xcc) + HABv4: State: Trusted state (0x99) + HABv4: No HAB Failure Events Found! + +This can also be seen with the ``hab -i`` command:: + + Current SRK hash: <some non-zero value> + secure mode + +Similarly, on supported SoCs, the ``bootrom -l`` command will indicate that +device is closed. Example output after booting via ``imx-usb-loader``:: + + + [e0] Internal use + [11] Boot mode is Boot from Serial Download + [23] Secure config is Closed + [41] FUSE_SEL_VALUE Fuse is blown + [d0] Enters serial download processing + [a0] Image authentication result: PASS (0x000000f0) @3506438144 ticks + [00] End of list + Secure Boot on i.MX6 ~~~~~~~~~~~~~~~~~~~~ @@ -252,7 +335,7 @@ Header: +--------------------+--------------------------------------------------------------+ | ``loadaddr <adr>`` | The address the binary is uploaded to | +--------------------+--------------------------------------------------------------+ -| ``dcdofs <ofs>`` | The offset of the image header in the image. This should be: | +| ``ivtofs <ofs>`` | The offset of the image header in the image. This should be: | | | | | | * ``0x400``: MMC/SD, NAND, serial ROM, PATA, SATA | | | * ``0x1000``: NOR Flash | @@ -311,6 +394,86 @@ with only the image name as argument: scripts/imx/imx-usb-loader images/barebox-freescale-imx51-babbage.img +FlexSPI Boot +^^^^^^^^^^^^ + +FlexSPI boot is currently supported on: i.MX8MM, i.MX8MN and i.MX8MP. + +To generate FlexSPI/QSPI image(s) the board flash header file must specify: +``flexspi_ivtofs`` and ``flexspi_fcfbofs``. + +It is recommended to do this via the ``include/mach/imx/flexspi-imx8m*-cfg.h`` +header files. + +.. code-block:: none + + #include <mach/imx/flexspi-imx8mp-cfg.h> + +There are two different headers, one for the i.MX8MM and one for the i.MX8MP/N. +It's important to use the correct one because the BootROM expects the IVT and +flash configuration block (FCB) on different offsets. + +Barebox doesn't generate a separate FlexSPI image instead the same image used +for SD/MMC/USB is extended to support FlexSPI boot. This is done by adding a 2nd +IVT header and the required FCB at the required boot offsets. + +Barebox also support `High Assurance Boot`_ images for QSPI boot mediums. This +feature must be enabled via the ``CONFIG_HABV4_QSPI`` option. The below figures +show a fully featured MMC/SD/USB/FlexSPI image with enabled HAB support for the +i.MX8M family. + +i.MX8MM layout:: + + 0x0 +------------------------------------------+ + | Barebox Header | + header_gap +------------------------------------------+ + | FlexSPI Flash Configuration Block (FCFB) | + header_gap + 0x400 +------------------------------------------+ --- + | i.MX MMC/SD/USB IVT Header | | + | Boot Data +--. | + | CSF Pointer +--|--. | + header_gap + 0x1000 +------------------------------------------+ | | --- | + | i.MX FlexSPI IVT Header | | | | | Signed Area + | Boot Data +--+ | | | MMC/SD/ + | CSF Pointer +--|--|--. | Signed Area | USB + header_gap + 0x2000 +------------------------------------------+ | | | | FlexSPI | + | Barebox Prebootloader (PBL) |<-´ | | | | + | Piggydata Hash (SHA256) | | | | | + +------------------------------------------+ | | --- --- + | Command Sequence File (CSF) Slot-0 |<----´ | + +------------------------------------------+ | + | Command Sequence File (CSF) Slot-1 |<-------´ + +------------------------------------------+ --- + | Piggydata (Main Barebox Binary) | | Hashed Area + +------------------------------------------+ --- + +i.MX8MP/N layout:: + + 0x0 +------------------------------------------+ + | Barebox Header | + header_gap +------------------------------------------+ --- + | i.MX MMC/SD/USB IVT Header | | + | Boot Data +--. | + | CSF Pointer +--|--. | + header_gap + 0x400 +------------------------------------------+ | | | + | FlexSPI Flash Configuration Block (FCFB) | | | | Signed Area + header_gap + 0x1000 +------------------------------------------+ | | --- | MMC/SD/ + | i.MX FlexSPI IVT Header | | | | | USB + | Boot Data +--+ | | | + | CSF Pointer +--|--|--. | Signed Area | + header_gap + 0x2000 +------------------------------------------+ | | | | FlexSPI | + | Barebox Prebootloader (PBL) |<-´ | | | | + | Piggydata Hash (SHA256) | | | | | + +------------------------------------------+ | | --- --- + | Command Sequence File (CSF) Slot-0 |<----´ | + +------------------------------------------+ | + | Command Sequence File (CSF) Slot-1 |<-------´ + +------------------------------------------+ --- + | Piggydata (Main Barebox Binary) | | Hashed Area + +------------------------------------------+ --- + +At the moment ``header_gap`` is always 32K for all supported devices. + External Boot Mode ------------------ @@ -344,7 +507,7 @@ i.MX boards Not all supported boards have a description here. Many newer boards also do not have individual defconfig files, they are covered by ``imx_v7_defconfig`` -or ``imx_defconfig`` instead. +or ``multi_v5_v6_defconfig`` instead. .. toctree:: :glob: diff --git a/Documentation/boards/imx/karo-tx25.rst b/Documentation/boards/imx/karo-tx25.rst index 756c99d816..d8dcd16890 100644 --- a/Documentation/boards/imx/karo-tx25.rst +++ b/Documentation/boards/imx/karo-tx25.rst @@ -1,7 +1,7 @@ Ka-Ro TX25 ========== -Building the bootloader image for this target is covered by the ``imx_defconfig`` +Building the bootloader image for this target is covered by the ``multi_v5_v6_defconfig`` multiimage configuration if the ``System Type`` menu entry ``Ka-Ro TX25`` is enabled. diff --git a/Documentation/boards/imx/meerkat96.rst b/Documentation/boards/imx/meerkat96.rst new file mode 100644 index 0000000000..7456aa857b --- /dev/null +++ b/Documentation/boards/imx/meerkat96.rst @@ -0,0 +1,43 @@ +Meerkat 96 +========== + +The Meerkat96 is a single board computer based on an i.MX7D SoC by NXP, +featuring a dual core ARM Cortex-A7 at 1 GHz and a Cortex-M4 at 266MHz +and 512 MB DRAM. For further details on the board's features check the +manufacturers page at https://www.96boards.org/product/imx7-96 + +Serial console +-------------- + +UART6 of the i.MX7D is broken out to Pinheader J3, on the Silkscreen +the Pins are labeled with B (Ground), W (UART 6 TX) and G (UART 6 RX). +If you use the UART-To-USB-Converter provided with the board, you can +just connect the Black jumper to B, the White to W and the Green to G. + +The UART uses 3.3V levels. + +Building Barebox +---------------- + +To build Barebox for the meerkat96 board do the following: + +.. code-block:: sh + + make ARCH=arm CROSS_COMPILE=<ARM toolchain prefix> mrproper + make ARCH=arm CROSS_COMPILE=<ARM toolchain prefix> imx_v7_defconfig + make ARCH=arm CROSS_COMPILE=<ARM toolchain prefix> + +Bringup +------- + +flash the resulting barebox-meerkat96.img to an sdcard at address 0. + +Make sure the pmic is set to power-on state by setting the dipswitch +SW3 on the boards bottom side to 1-1 (i.e. all switches on, which is +the factory default). + +Schematics +---------- + +Schematics are available at https://github.com/96boards/documentation/blob/master/consumer/imx7-96/hardware-docs/files/iMX7-96-schematics.pdf + diff --git a/Documentation/boards/imx/nxp-imx8mm-evk.rst b/Documentation/boards/imx/nxp-imx8mm-evk.rst index c3cd35ae38..aa70419139 100644 --- a/Documentation/boards/imx/nxp-imx8mm-evk.rst +++ b/Documentation/boards/imx/nxp-imx8mm-evk.rst @@ -69,3 +69,32 @@ board for serial download mode as printed on the PCB. You can start barebox with the imx-usb-loader tool that comes with barebox like this: ./scripts/imx/imx-usb-loader images/barebox-nxp-imx8mm-evk.img + +Installing barebox +================== + +When the EVK is strapped to boot from eMMC, the i.MX8M bootrom will +consult the eMMC ext_csd register to determine whether to boot +from the active eMMC boot partition or from the user area. + +The same barebox image written to the start of the SD-Card can +be written to the start of the eMMC user area. Power-fail-safe +installation to the eMMC boot partition requires special handling: + + - The barebox image must be written to the inactive boot partition, + then afterwards, the newly written boot partition is activated + (This is controlled by the barebox ``mmcX.boot`` variable). + +The following steps are required to write the image to the QSPI NOR flash: + + - The 32KiB preamble MMC preamble must be stripped. + + - The QSPI NOR partition ``barebox`` must be erased before the stripped + image is written. The erase size depends on the stripped image size but + always start at offset 0. + + - Write the stripped barebox image to the QSPI NOR partition ``barebox`` + at offset 0. + +The ``barebox_update`` command takes care of this and need just be +supplied a barebox image as argument. diff --git a/Documentation/boards/imx/nxp-imx8mn-evk.rst b/Documentation/boards/imx/nxp-imx8mn-evk.rst new file mode 100644 index 0000000000..597db57eaf --- /dev/null +++ b/Documentation/boards/imx/nxp-imx8mn-evk.rst @@ -0,0 +1,96 @@ +NXP i.MX8MN EVK Evaluation Board +================================ + +Board comes with either: + +* 2GiB of LPDDR4 RAM +* 2GiB of DDR4 RAM + +barebox supports both variants with the same image. + +Downloading DDR PHY Firmware +---------------------------- + +As a part of DDR intialization routine NXP i.MX8MN EVK requires and +uses several binary firmware blobs that are distributed under a +separate EULA and cannot be included in Barebox. In order to obtain +them do the following:: + + wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.12.bin + chmod +x firmware-imx-8.12.bin + ./firmware-imx-8.12.bin + +Executing that file should produce a EULA acceptance dialog as well as +result in the following files: + +- lpddr4_pmu_train_1d_dmem.bin +- lpddr4_pmu_train_1d_imem.bin +- lpddr4_pmu_train_2d_dmem.bin +- lpddr4_pmu_train_2d_imem.bin +- ddr4_dmem_1d_201810.bin +- ddr4_imem_1d_201810.bin +- ddr4_dmem_2d_201810.bin +- ddr4_imem_2d_201810.bin + +As a last step of this process those files need to be placed in +"firmware/":: + + for f in lpddr4_pmu_train_1d_dmem.bin \ + lpddr4_pmu_train_1d_imem.bin \ + lpddr4_pmu_train_2d_dmem.bin \ + lpddr4_pmu_train_2d_imem.bin; \ + do \ + cp firmware-imx-8.12/firmware/ddr/synopsys/${f} \ + firmware/${f}; \ + done + + for f in ddr4_dmem_1d_201810.bin \ + ddr4_imem_1d_201810.bin \ + ddr4_dmem_2d_201810.bin \ + ddr4_imem_2d_201810.bin; \ + do \ + cp firmware-imx-8.12/firmware/ddr/synopsys/${f} \ + firmware/${f%_201810.bin}.bin; \ + done + +Build barebox +============= + + make imx_v8_defconfig + make + +Installing barebox +================== + +When the EVK is strapped to boot from eMMC, the i.MX8M bootrom will +consult the eMMC ext_csd register to determine whether to boot +from the active eMMC boot partition or from the user area. + +The same barebox image written to the start of the SD-Card can +be written to the start of the eMMC user area. Power-fail-safe +installation to the eMMC boot partition requires special handling: + + - The barebox image must be written to the inactive boot partition, + then afterwards, the newly written boot partition is activated + (This is controlled by the barebox ``mmcX.boot`` variable). + + - The barebox image includes a 32KiB preamble that allows the image + to be directly writable to the start of the SD-Card or eMMC user area. + Unlike older i.MX8M, the i.MX8MN BootROM expects the bootloader to not + start at an offset when booting from eMMC boot partitions, thus the first + 32KiB must be stripped. + +The following steps are required to write the image to the QSPI NOR flash: + + - Strip the 32KiB preamble, like it is done for the eMMC boot partition case + (see above). + + - The QSPI NOR partition ``barebox`` must be erased before the stripped + image is written. The erase size depends on the stripped image size but + always start at offset 0. + + - Write the stripped barebox image to the QSPI NOR partition ``barebox`` + at offset 0. + +The ``barebox_update`` command takes care of this and need just be +supplied a barebox image as argument. diff --git a/Documentation/boards/imx/nxp-imx8mp-evk.rst b/Documentation/boards/imx/nxp-imx8mp-evk.rst new file mode 100644 index 0000000000..da26339864 --- /dev/null +++ b/Documentation/boards/imx/nxp-imx8mp-evk.rst @@ -0,0 +1,104 @@ +NXP i.MX8MP-EVK board +===================== + +The board comes with: + +* 6GiB of LPDDR4 RAM +* 32GiB eMMC + +Not including booting via serial, the device can boot from either SD or eMMC. + +Downloading DDR PHY firmware +---------------------------- + +As a part of DDR intialization routine NXP i.MX8MP EVK requires and +uses several binary firmware blobs that are distributed under a +separate EULA and cannot be included in Barebox. In order to obtain +them do the following:: + + wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.7.bin + chmod +x firmware-imx-8.7.bin + ./firmware-imx-8.7.bin + +Executing that file should produce a EULA acceptance dialog as well as +result in the following files: + +- lpddr4_pmu_train_1d_dmem.bin +- lpddr4_pmu_train_1d_imem.bin +- lpddr4_pmu_train_2d_dmem.bin +- lpddr4_pmu_train_2d_imem.bin + +As a last step of this process those files need to be placed in +"firmware/":: + + for f in lpddr4_pmu_train_1d_dmem.bin \ + lpddr4_pmu_train_1d_imem.bin \ + lpddr4_pmu_train_2d_dmem.bin \ + lpddr4_pmu_train_2d_imem.bin; \ + do \ + cp firmware-imx-8.7/firmware/ddr/synopsys/${f} \ + firmware/${f}; \ + done + +Get and Build the Trusted Firmware A +------------------------------------ + +Get TF-A from https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ and +checkout version v2.7:: + + make PLAT=imx8mp bl31 + cp build/imx8mp/release/bl31.bin ${barebox_srctree}/firmware/imx8mp-bl31.bin + +.. warning:: It is important to use a version >= v2.7 else your system + might not boot. + +Build Barebox +------------- + +i.MX8MP-EVK support is contained in the imx_v8_defconfig to build it use:: + + make imx_v8_defconfig + make + +Boot Configuration +------------------ + +The NXP i.MX8MP-EVK board has four switches responsible for configuring +bootsource/boot mode. The settings for the different boot sources are +printed on the board. + +Installing barebox +================== + +When the EVK is strapped to boot from eMMC, the i.MX8M bootrom will +consult the eMMC ext_csd register to determine whether to boot +from the active eMMC boot partition or from the user area. + +The same barebox image written to the start of the SD-Card can +be written to the start of the eMMC user area. Power-fail-safe +installation to the eMMC boot partition requires special handling: + + - The barebox image must be written to the inactive boot partition, + then afterwards, the newly written boot partition is activated + (This is controlled by the barebox ``mmcX.boot`` variable). + + - The barebox image includes a 32KiB preamble that allows the image + to be directly writable to the start of the SD-Card or eMMC user area. + Unlike older i.MX8M, the i.MX8MP BootROM expects the bootloader to not + start at an offset when booting from eMMC boot partitions, thus the first + 32KiB must be stripped. + +The following steps are required to write the image to the QSPI NOR flash: + + - Strip the 32KiB preamble, like it is done for the eMMC boot partition case + (see above). + + - The QSPI NOR partition ``barebox`` must be erased before the stripped + image is written. The erase size depends on the stripped image size but + always start at offset 0. + + - Write the stripped barebox image to the QSPI NOR partition ``barebox`` + at offset 0. + +The ``barebox_update`` command takes care of this and need just be +supplied a barebox image as argument. diff --git a/Documentation/boards/imx/phytec-phycard-i.mx27.rst b/Documentation/boards/imx/phytec-phycard-i.mx27.rst index d5d3837132..af89b353a8 100644 --- a/Documentation/boards/imx/phytec-phycard-i.mx27.rst +++ b/Documentation/boards/imx/phytec-phycard-i.mx27.rst @@ -1,7 +1,7 @@ Phytec phyCARD-i.MX27 ===================== -Building the bootloader image for this target is covered by the ``imx_defconfig`` +Building the bootloader image for this target is covered by the ``multi_v5_v6_defconfig`` multiimage configuration if the ``System Type`` menu entry ``phyCard-i.MX27`` is enabled. diff --git a/Documentation/boards/imx/phytec-phycore-i.mx27.rst b/Documentation/boards/imx/phytec-phycore-i.mx27.rst index 4b40be781d..6132e7298a 100644 --- a/Documentation/boards/imx/phytec-phycore-i.mx27.rst +++ b/Documentation/boards/imx/phytec-phycore-i.mx27.rst @@ -1,7 +1,7 @@ Phytec phyCORE-i.MX27 ===================== -Building the bootloader image for this target is covered by the ``imx_defconfig`` +Building the bootloader image for this target is covered by the ``multi_v5_v6_defconfig`` multiimage configuration if the ``System Type`` menu entry ``phyCORE-i.MX27`` is enabled. diff --git a/Documentation/boards/imx/protonic-prt8mm.rst b/Documentation/boards/imx/protonic-prt8mm.rst new file mode 100644 index 0000000000..f8c8b2c88d --- /dev/null +++ b/Documentation/boards/imx/protonic-prt8mm.rst @@ -0,0 +1,10 @@ +Protonic Holland PRT8MM board +============================= + +This board is a low-cost 7inch touchscreen virtual terminal for agricultural applications. +HW specs: + +* SoC: i.MX8M mini +* RAM: 1GiB LPDDR4 +* eMMC: 16GiB +* Display: 7inch 800x480 with capacitive touchscreen. diff --git a/Documentation/boards/imx/variscite-dt8mcustomboard-imx8mp.rst b/Documentation/boards/imx/variscite-dt8mcustomboard-imx8mp.rst new file mode 100644 index 0000000000..0e986a1086 --- /dev/null +++ b/Documentation/boards/imx/variscite-dt8mcustomboard-imx8mp.rst @@ -0,0 +1,149 @@ +Variscite DT8MCustomBoard with DART-MX8M-PLUS SOM +================================================= + +This board is an eval-kit for the Variscite DART-MX8M-PLUS SOM. The latter is a +SOM based on the i.MX8M Plus processor. As seen in official Variscite documents there exist +several hardware revisions for this board. Currently only revision 3.0 could was tested +with Barebox. + +The Variscite DART-MX8M-PLUS SOM is available in different configurations. For a rough overview, +these are some of the possible options: + +* Processor: NXP i.MX8M Plus, either @1.6GHz or @1.8GHz +* 1 to 8 GiB LPDDR4 RAM +* 8 to 128 GiB eMMC +* (optional) GigE PHY on module +* (optional) Wifi + Bluetooth Chip on module + +Besides that the SOM offers a lot of interfaces. Among some of the interfaces that are +made available by the eval-board are: + +* USB3 +* GigE Ethernet +* PCIe +* SD-card slot +* HDMI + +More Information about the eval-board can be found at +https://www.variscite.com/product/single-board-computers/var-dt8mcustomboard/ + +More Information about the targeted SOM can be found at +https://www.variscite.com/product/system-on-module-som/cortex-a53-krait/dart-mx8m-plus-nxp-i-mx-8m-plus + +Providing necessary binary files +-------------------------------- + +Barebox requires some blobs to successfully bringup the system. These blobs +serve different use cases. Barebox's build system will look for these files +in the configured firmware directory (``firmware`` by default). The build +systems expects these files to have certain names. + +Hence the very first thing before building Barebox is to obtain these files and +placing them in the firmware folder. + +The DDR4 training files are part of a set of files that is provided by NXP. +They are provided under the terms of a proprietary EULA one has to agree to, +before getting access to the blobs. They are provided as self-extracting +archive. To get a hand on them, perform the following:: + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.10.bin + $ chmod u+x firmware-imx-8.10.bin + $ ./firmware-imx-8.10.bin + +Assuming that the downloaded executable was run from inside the toplevel directory of the Barebox repo, +the necessary DDR4 training files can simply be hardlinked (or copied):: + + $ ln firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_dmem_202006.bin firmware/lpddr4_pmu_train_1d_dmem.bin + $ ln firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_imem_202006.bin firmware/lpddr4_pmu_train_1d_imem.bin + $ ln firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_dmem_202006.bin firmware/lpddr4_pmu_train_2d_dmem.bin + $ ln firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_imem_202006.bin firmware/lpddr4_pmu_train_2d_imem.bin + +Another required binary is the Secure Monitor Firmware (BL31). This is build by some ARM Trusted Firmware project (ATF). +One fork is provided by NXP and can be downloaded from https://github.com/nxp-imx/imx-atf. Variscite does maintain it's +own fork of NXP's ATF project. This can be found at https://github.com/varigit/imx-atf/. + +Once the ATF has been built successfully, the resulting BL31 binary needs to be placed in the ``firmware`` directory +under the filename ``imx8mp-bl31.bin``. + +After those files are in place, one can proceed with the usual Barebox build routine. + +Compiling Barebox +----------------- + +A quick way to configure and compile Barebox for this board is by starting from +the `imx_v8_defconfig`:: + + export ARCH=arm + export CROSS_COMPILE=/path/to/your/toolchain/bin/aarch64-v8a-linux-gnu- + make imx_v8_defconfig + make + +With this procedure one might need some additional firmware files in place to +successfully build the Barebox images for all selected boards. A solution to this is +either to copy the necessary files to the `firmware` directory or simply run +`make menuconfig` and deselect the unwanted boards under "System Type". + +When the build succeeds, the Barebox image `barebox-variscite-imx8mp-dart-cb.img` +can be found in the `images` subdirectory. + +Boot Configuration +------------------ + +The DT8MCustomBoard allows the user to choose whether to proceed with the *internal* +or *external boot mode*. With this board, *internal boot mode* refers to booting +from the eMMC memory, while *external boot mode* refers to booting from an SD-card. + +The mode is selected with switch SW7, located below the buttons on the board. + +Set the switch to **ON** for the BootROM to perform an *internal boot*. Otherwise +set the switch to **OFF** to follow the *external boot* procedure. + +If in doubt, refer to the silk screen on the board, to select the correct switch +position. + +If the BootROM cannot find a valid bootloader image in the selected source, +it'll try several fallbacks until it finally ends in USB download mode or finds +a valid bootloader image to load. + +To load an image when the board is in USB download mode the imx-usb-loader tool +is required. To build this tool alongside the Barebox image, select it in the +config menu under "Host Tools". + +Starting Barebox +---------------- + +An easy solution to start Barebox bare metal is to use the *external boot* mode and +copy Barebox onto a SD-card. + +To copy the Barebox binary onto a SD-card, use the `dd` tool on linux:: + + dd if=images/barebox-variscite-imx8mp-dart-cb.img of=/dev/mmcblk0 bs=512 seek=1 skip=1 + +Next, you insert the SD-card into the eval board and select *external boot mode* on +switch SW7. + +When you power up the board, you should now see Barebox's output appearing on your +serial console. + +Currently Supported Features +---------------------------- + +The Barebox binary configured by the `variscite_imx8mp_dart_cb_defconfig` does currently +not support all possible features of the DT8MCustomBoard. Yet the binary does contain +everything necessary to boot an operating system on the i.MX8MP. + +Some of the currently supported features: + +* general i.MX8MP bringup, including DRAM initialisation +* working eMMC and SD-card support +* serial console on UART 1 - available through the micro-USB connector on the board +* working gigabit ethernet on the first port (labeled ETH, named `eth0` in Barebox and linux) +* working LED and GPIO support + +Some functionality that is currently missing or untested: + +* secondary ethernet interface (labeled ETH2) will currently not work +* secure boot (not tested) +* framebuffer support (missing driver) +* OP-TEE integration (not tested - early loading currently not supported by the startup code) +* running on other hardware revisions of the DT8MCustomBoard than v3.0 (not tested)
\ No newline at end of file diff --git a/Documentation/boards/imx/zii-imx8mq-dev/openocd.cfg b/Documentation/boards/imx/zii-imx8mq-dev/openocd.cfg index cc0bec6b74..fa25348757 100644 --- a/Documentation/boards/imx/zii-imx8mq-dev/openocd.cfg +++ b/Documentation/boards/imx/zii-imx8mq-dev/openocd.cfg @@ -71,15 +71,15 @@ proc ddr_init { } { proc start_barebox {} { # - # We have to place our image at MX8MQ_ATF_BL33_BASE_ADDR in order + # We have to place our image at MX8M_ATF_BL33_BASE_ADDR in order # to be able to initialize ATF firmware since that's where it # expects entry point to BL33 would be # - set MX8MQ_ATF_BL33_BASE_ADDR 0x40200000 + set MX8M_ATF_BL33_BASE_ADDR 0x40200000 echo "Bootstrap: Loading Barebox" - load_image images/start_zii_imx8mq_dev.pblb $MX8MQ_ATF_BL33_BASE_ADDR bin - echo [format "Bootstrap: Jumping to 0x%08x" $MX8MQ_ATF_BL33_BASE_ADDR] - resume $MX8MQ_ATF_BL33_BASE_ADDR + load_image images/start_zii_imx8mq_dev.pblb $MX8M_ATF_BL33_BASE_ADDR bin + echo [format "Bootstrap: Jumping to 0x%08x" $MX8M_ATF_BL33_BASE_ADDR] + resume $MX8M_ATF_BL33_BASE_ADDR } proc board_init { } { diff --git a/Documentation/boards/k3.rst b/Documentation/boards/k3.rst new file mode 100644 index 0000000000..f675c4510c --- /dev/null +++ b/Documentation/boards/k3.rst @@ -0,0 +1,29 @@ +Texas Instruments K3 +==================== + +K3 is for Keystone 3 and denotes a family of SoCs from Texas Instruments. From these +SoCs the AM62x is currently supported under barebox. The boot flow needs several images, +only the last stage is supported by barebox. To start up the help of U-Boot is still +needed. + +The board currently supported by barebox is the BeaglePlay board, see +https://www.beagleboard.org/boards/beagleplay. The following examples assume +this board is used. + +Building barebox +---------------- +.. code-block:: sh + + make ARCH=arm CROSS_COMPILE=<ARM toolchain prefix> multi_v8_defconfig + +Running barebox +--------------- + +barebox can be started from running U-Boot with: + +.. code-block:: sh + + dhcp 0x82000000 <serverip>:barebox-beagleplay.img; bootm 0x82000000 + +To start barebox from SD/eMMC replace the ``u-boot.img`` on a bootable SD/eMMC card +with the content of ``images/barebox-beagleplay-fit.img`` diff --git a/Documentation/boards/kvx.rst b/Documentation/boards/kvx.rst new file mode 100644 index 0000000000..0a1a6f7dda --- /dev/null +++ b/Documentation/boards/kvx.rst @@ -0,0 +1,98 @@ +KVX +=== + +The Kalray VLIW processor family (KVX) has the following features: + - 32/64 bits execution mode + - 6-issue VLIW architecture + - 64 x 64bits general purpose registers + - SIMD instructions + - little-endian + - deep learning co-processor + +Kalray kv3 core which is the third of the KVX family is embedded in Kalray +MPPA3-80 SoC currently used on K200 boards. + +This SoC contains 5 clusters which are each made of: + - 4MiB of on-chip memory + - 1 dedicated safety/security core (kv3 core). + - 16 PEs (Processing Elements) (kv3 cores). + - 16 Co-processors (one per PE) + - 2 x Crypto accelerators + +MPPA3-80 SoC contains the following features: + - 5 x Clusters + - 2 x 100G Ethernet controllers + - 8 x PCIe GEN4 controllers (Root Complex and Endpoint capable) + - 2 x USB 2.0 controllers + - 1 x Octal SPI-NOR flash controller + - 1 x eMMC controller + - 3 x Quad SPI controllers + - 6 x UART + - 5 x I2C controllers (3 x SMBus capable) + - 4 x CAN controller + - 1 x OTP memory + +The Kalray VLIW architecture barebox port allows to boot it as a second stage +bootloader (SSBL). It is loaded after the FSBL which initialize DDR and needed +peripherals. FSBL always start on the Security Core of Cluster 0 + +The FSBL can load elf files and pass them a device tree loaded from SPI NOR +flash. As such, barebox should be flashed as an elf file into the SSBL +partition. + +KVX boards +---------- + +.. toctree:: + :glob: + :maxdepth: 1 + + kvx/* + +Getting a toolchain +------------------- + +Pre-built toolchain are available from github ([#f1]_). In order to build one +from scratch, build scripts are available on github too ([#f2]_). +Once built or downloaded, a ``kvx-elf-`` toolchain will be available and should +be added to your ``PATH``. + +Building barebox +---------------- + +Currently, kvx port is provided with a defconfig named ``generic_defconfig``. +To build it, first generate the config and then run the build: + +.. code-block:: sh + + make ARCH=kvx O=$PWD/build defconfig + make ARCH=kvx O=$PWD/build all + +This will generate a ``barebox`` elf file. By default barebox for kvx is +compiled to be run at address 0x110000000. + +Booting barebox +--------------- + +``barebox`` elf file can be loaded using ``kvx-jtag-runner`` to execute the +image via JTAG on an existing board. + +Depending on your board and barebox version, you should see the following +message appearing on the serial console. + +.. code-block:: console + + barebox 2020.03.0-00126-ga74988bf5 #3 Wed Apr 15 11:31:28 CEST 2020 + + Board: KONIC 200 (K200) + malloc space: 0x110050fe0 -> 0x200000000 (size 3.7 GiB) + + Hit any to stop autoboot: 3 + barebox:/ + + +.. rubric:: References + +.. [#f1] `Toolchain releases <https://github.com/kalray/build-scripts/releases>`_ +.. [#f2] `Build scripts <https://github.com/kalray/build-scripts/>`_ + diff --git a/Documentation/boards/kvx/kalray-k200.rst b/Documentation/boards/kvx/kalray-k200.rst new file mode 100644 index 0000000000..9d97fa2550 --- /dev/null +++ b/Documentation/boards/kvx/kalray-k200.rst @@ -0,0 +1,11 @@ +Kalray K200 +=========== + +This board is based on a MPPA3-80 SoC. The board is shipped with: + + - 128MiB NOR flash Memory + - 8GiB DDR4 SDRAM + - 2 x 100G Ethernet controllers supporting 8 x 1G, 10 and 25G + - PCIe GEN4 X16 port + +See https://www.kalrayinc.com/portfolio/boards/ for more information. diff --git a/Documentation/boards/mips/dlink-dir-320.rst b/Documentation/boards/mips/dlink-dir-320.rst index 7595381f55..90de68a9c4 100644 --- a/Documentation/boards/mips/dlink-dir-320.rst +++ b/Documentation/boards/mips/dlink-dir-320.rst @@ -21,7 +21,7 @@ Running barebox Barebox can be started from CFE using tftp. You must setup tftp-server on host 192.168.0.1. -Put your barebox.bin to tftp-server directory +Put your barebox-dlink-dir-320.img to tftp-server directory (usual /tftpboot or /srv/tftp). Connect your DIR-320 to your tftp-server network via one of four <LAN> sockets. @@ -31,14 +31,14 @@ Next, setup network on DIR-320 and run barebox.bin, e.g.: .. code-block:: console CFE> ifconfig eth0 -addr=192.168.0.99 - CFE> boot -tftp -addr=a0800000 -raw 192.168.0.1:barebox.bin + CFE> boot -tftp -addr=a0800000 -raw 192.168.0.1:barebox-dlink-dir-320.img Links ----- - * http://www.dlink.com.au/products/?pid=768 - * http://wiki.openwrt.org/toh/d-link/dir-320 + * http://web.archive.org/web/20140301070636/http://www.dlink.com.au/products/?pid=768 + * https://openwrt.org/toh/d-link/dir-320 CFE links: diff --git a/Documentation/boards/mips/loongson_ls1b.rst b/Documentation/boards/mips/loongson_ls1b.rst index 8f475e6e24..ea7ed8d8d0 100644 --- a/Documentation/boards/mips/loongson_ls1b.rst +++ b/Documentation/boards/mips/loongson_ls1b.rst @@ -30,7 +30,7 @@ Running barebox 3. Wait ``Press <Enter> to execute loading image`` prompt and press the space key. - 4. Build barebox and upload ``zbarebox.bin`` via Ymodem to the board: + 4. Build barebox and upload ``images/barebox-loongson-ls1b.img`` via Ymodem to the board: .. code-block:: none diff --git a/Documentation/boards/mips/max9331.rst b/Documentation/boards/mips/max9331.rst new file mode 100644 index 0000000000..f7529f9874 --- /dev/null +++ b/Documentation/boards/mips/max9331.rst @@ -0,0 +1,144 @@ +OKUD MAX9331 +============== + +The USELESS Board seems useless + + * Atheros ar9331 SoC(MIPS24Kc, 400MHz, 32bit); + * 64 MiB SDRAM; + * 16 MiB NOR type SPI Flash Memory; + * 3.3V TTL UART; + * 4 GiB USB Nand Flash Disk; + * 3 RJ45 Ports; + * IEEE 802.11b/g; + * 3 User LEDs; + * 1 GPIO Button; + +The useless board always shiped with the lastest barebox and kernel. OpenWRT +is supported too. + +Perparing Hardware +------------------ + +solder the board in the back, use a TTL dongle connect to JP1. + +:: + + TP2 -- TP3 + TP1 -- TP4 + + +--|PWR|---|wan|---|lan1|---|lan2|-----|ANT|---+ + | | + | | + | | + | | + | | + | TP2 | + | O O TP1 | + | TP3 | + | O | + | TP4 O | + | o o o | + +----------------------------------------------+ + Tx Rx GND + + +Running barebox +--------------- + +Barebox can be program to the board with: + + * run by u-boot from tftp server + * run barebox from RAM or burn to flash by barebox + * run from spi flash + +Barebox can be started from U-Boot using tftp. +To convert barebox.bin to u-boot uImage format: + +.. code-block:: sh + + $ mkimage -A mips -O linux -T kernel -C none -a a0060000 -e a0060000 -n 'Barebox uImage' -d images/barebox-okud-max9331.img uImage + $ cp uImage /var/lib/tftpboot + +connect your board to your tftp-server network via Ethernet. +next, setup network on MAX9331 and run: + +.. code-block:: console + + hornet> set ipaddr 192.168.31.17 + hornet> set serverip 192.168.31.40 + hornet> tftpboot 0x81000000 uImage + +run from ram: + +.. code-block:: console + + hornet> bootm 0x81000000 + +or burn to flash, replace the 0x40000 to your uImage real size, + +.. code-block:: console + + hornet> erase 0x9f020000 +0x40000 + hornet> cp.b 0x81000000 0x9f020000 0x40000 + hornet> reset + +if your board preinstalled with barebox: + +run barebox from ram by barebox + +copy the image to tftp server folder + +.. code-block:: sh + + $ cp images/barebox-okud-max9331.img /var/lib/tftpboot/none-barebox-max9331 + +enable dhcp service on the network + +.. code-block:: console + + global net.server=10.1.1.72 + boot bnet + +if you want to make it valid next boot + +.. code-block:: console + + nv net.server=10.1.1.72 + boot bnet + +update barebox by barebox + +.. code-block:: console + + barebox_update /mnt/tftp/none-barebox-max9331 + +run from spi flash + +max9331 has 16MiB spi flash on board, layout is like this + +.. code-block:: text + + | boot0 | ... | barebox | ... | art | + +by default, the barebox bootloader is not located in the begginning of flash, +instead we have a so called program boot0, it is a very simple program, +it jump to 0x9f020000 where the first instruction of barebox. +This is usefull when debug with jtag or choosing different bootloaders. +or even boot kernel without bootloader. + +.. code-block:: asm + + lui ra, 0x9f02 + jr ra + nop + + b . + nop + +Links +----- + +See also + + * http://www.eeboard.com/wp-content/uploads/downloads/2013/08/AR9331.pdf + * http://squonk42.github.io/TL-WR703N/ diff --git a/Documentation/boards/mips/qemu-malta.rst b/Documentation/boards/mips/qemu-malta.rst index 2bb81350a1..44f671638d 100644 --- a/Documentation/boards/mips/qemu-malta.rst +++ b/Documentation/boards/mips/qemu-malta.rst @@ -9,32 +9,24 @@ QEMU run string: .. code-block:: sh qemu-system-mips -nodefaults -M malta -m 256 \ - -nographic -serial stdio -monitor null \ - -bios barebox-flash-image + -device VGA -serial stdio -monitor null \ + -bios ./images/barebox-qemu-malta.img Little-endian mode ------------------ -Running little-endian Malta is a bit tricky. In little-endian mode the 32bit words in the boot flash image are swapped, a neat trick which allows bi-endian firmware. -You have to swap words of ``zbarebox.bin`` image, e.g.: - -.. code-block:: sh - - echo arch/mips/pbl/zbarebox.bin \ - | cpio --create \ - | cpio --extract --swap --unconditional - -QEMU run string: +The barebox build generates a second ``./images/barebox-qemu-malta.img.swapped`` +image that can be used in this case, e.g.: .. code-block:: sh qemu-system-mipsel -nodefaults -M malta -m 256 \ - -nographic -serial stdio -monitor null \ - -bios barebox-flash-image + -device VGA -serial stdio -monitor null \ + -bios ./images/barebox-qemu-malta.img.swapped Using GXemul @@ -43,7 +35,7 @@ Using GXemul GXemul supports MIPS Malta except PCI stuff. You can use GXemul to run little-endian barebox (use gxemul-malta_defconfig). -N.B. There is no need to swap words in ``zbarebox.bin`` for little-endian GXemul! +N.B. There is no need to swap words in the barebox binary for little-endian GXemul! GXemul run string: diff --git a/Documentation/boards/openrisc.rst b/Documentation/boards/openrisc.rst index f9d67f9650..17b0aef4a6 100644 --- a/Documentation/boards/openrisc.rst +++ b/Documentation/boards/openrisc.rst @@ -1,6 +1,74 @@ OpenRISC ======== +Optaining an OpenRISC toolchain +------------------------------- + +Toolchain binaries can be obtained from openrisc.io or our github releases page. +Instructions for building the different toolchains can be found on openrisc.io +or Stafford's toolchain build and release scripts. + +See: + + * https://github.com/stffrdhrn/gcc/releases + * https://github.com/stffrdhrn/or1k-toolchain-build + * https://openrisc.io/software + +Example of downloading and installing a toolchain:: + + $ curl --remote-name --location \ + https://github.com/stffrdhrn/gcc/releases/download/or1k-10.0.0-20190723/or1k-elf-10.0.0-20190723.tar.xz + $ tar -xf or1k-elf-10.0.0-20190723.tar.xz + $ export PATH=$PATH:$PWD/or1k-elf/bin + +Running OpenRISC barebox on qemu +-------------------------------- + +Running barebox on qemu is similar to running linux on qemu see more details on +the qemu wiki site at https://wiki.qemu.org/Documentation/Platforms/OpenRISC + +Compile the qemu emulator:: + + $ git clone https://gitlab.com/qemu-project/qemu.git + $ cd qemu + $ mkdir build ; cd build + $ ../configure \ + --target-list="or1k-softmmu" \ + --enable-fdt \ + --disable-kvm \ + --disable-xen \ + --disable-xkbcommon \ + --enable-debug \ + --enable-debug-info + $ make + +Next compile barebox:: + + $ make ARCH=openrisc defconfig + ... + $ make ARCH=openrisc CROSS_COMPILE=or1k-elf- + +Run barebox:: + + $ <path to qemu source>/build/or1k-softmmu/qemu-system-or1k \ + -cpu or1200 \ + -M or1k-sim \ + -kernel /home/shorne/work/openrisc/barebox/barebox \ + -net nic -net tap,ifname=tap0,script=no,downscript=no \ + -serial mon:stdio -nographic -gdb tcp::10001 \ + -m 32 + + + barebox 2021.02.0-00120-g763c6fee7-dirty #14 Thu Mar 4 05:13:51 JST 2021 + + + Board: or1ksim + mdio_bus: miibus0: probed + malloc space: 0x01b80000 -> 0x01f7ffff (size 4 MiB) + + Hit any to stop autoboot: 3 + barebox@or1ksim:/ + or1ksim ------- diff --git a/Documentation/boards/riscv.rst b/Documentation/boards/riscv.rst index c7fa52aadb..990bd16a64 100644 --- a/Documentation/boards/riscv.rst +++ b/Documentation/boards/riscv.rst @@ -1,8 +1,107 @@ RISC-V ====== -Running RISC-V barebox on qemu ------------------------------- +QEMU Virt +--------- + +barebox supports both the qemu riscv32 and riscv64 ``-M virt`` boards:: + + make ARCH=riscv rv64i_defconfig + qemu-system-riscv64 -M virt -serial stdio -kernel build/images/barebox-dt-2nd.img + +For 32-bit builds use ``virt32_defconfig``. :ref:`virtio_sect` over MMIO is supported and +can be used for e.g. an extra console or to pass in a virtio-blk device:: + + qemu-system-riscv64 -M virt -serial stdio \ + -kernel ./images/barebox-dt-2nd.img \ + -device virtio-rng-device \ + -drive if=none,file=./images/barebox-dt-2nd.img,format=raw,id=hd0 \ + -device virtio-blk-device,drive=hd0 \ + -device virtio-serial-device \ + -chardev socket,path=/tmp/foo,server,nowait,id=foo \ + -device virtconsole,chardev=foo,name=console.foo + + barebox 2021.02.0 #27 Sun Mar 14 10:08:09 CET 2021 + + + Board: riscv-virtio,qemu + malloc space: 0x83dff820 -> 0x87bff03f (size 62 MiB) + + barebox@riscv-virtio,qemu:/ filetype /dev/virtioblk0 + /dev/virtioblk0: RISC-V Linux image (riscv-linux) + +Note that the ``board-dt-2nd.img`` uses the Linux RISC-V kernel image +format and boot protocol. It thus requires the device tree to be passed +from outside in ``a1`` and must be loaded at an offset as indicated in +the header for the initial stack to work. Using the ``-kernel`` option +in Qemu or booting from bootloaders that can properly boot Linux will +take care of this. + +TinyEMU +------- + +TinyEMU can emulate a qemu-virt like machine with a RISC-V 32-, 64- +and 128-bit CPU. It can run 32-bit barebox with this sample configuration: + +.. literalinclude:: riscv/barebox-virt32.cfg + +as well as 64-bit barebox with this configuration: + +.. literalinclude:: riscv/barebox-virt64.cfg + +``barebox-dt-2nd.img`` can be generated like with Qemu. Graphical +output and input are also supported. +To activate add:: + + display0: { device: "simplefb", width: 800, height: 600 }, + input_device: "virtio", + +into the config file. + +See https://barebox.org/demo/?graphic=1 for a live example. + +BeagleV +------- + +barebox has second-stage support for the BeagleV Starlight:: + + make ARCH=riscv rv64i_defconfig + make + +Thie resulting ``./images/barebox-beaglev-starlight.img`` can be used as payload +to opensbi:: + + git clone https://github.com/starfive-tech/opensbi + cd opensbi + export ARCH=riscv + export PLATFORM=starfive/vic7100 + export FW_PAYLOAD_PATH=$BAREBOX/build/images/barebox-beaglev-starlight.img + + make ARCH=riscv + ./fsz.sh ./build/platform/starfive/vic7100/firmware/fw_payload.bin fw_payload.bin.out + ls -l $OPENSBI/build/platform/starfive/vic7100/firmware/fw_payload.bin.out + +The resulting ``./platform/starfive/vic7100/firmware/fw_payload.bin.out`` can then +be flashed via Xmodem to the board:: + + picocom -b 115200 /dev/ttyUSB0 --send-cmd "sx -vv" --receive-cmd "rx -vv" + 0:update uboot + select the function: 0 + send file by xmodem + ^A^S./platform/starfive/vic7100/firmware/fw_payload.bin.out + +After reset, barebox should then boot to shell and attempt booting kernel ``Image`` +and device tree ``jh7100-starlight.dtb`` from the first root partition with the same +partition as rootfs. Note that while barebox does take over some initialization, +because of lack of Linux drivers, it doesn't yet do everything. If you experience +boot hangs, you may need to disable devices (or extend the starfive-pwrseq driver +to initialize it for you). + +Erizo +----- + +Running on qemu +~~~~~~~~~~~~~~~ Obtain RISC-V GCC/Newlib Toolchain, see https://github.com/riscv/riscv-tools/blob/master/README.md @@ -44,7 +143,7 @@ Next compile barebox:: Run barebox:: $ <path to riscv-qemu source>/riscv32-softmmu/qemu-system-riscv32 \ - -nographic -M erizo -bios <path to barebox sources >/barebox.bin \ + -nographic -M erizo -bios ./images/barebox-erizo-generic.img \ -serial stdio -monitor none -trace file=/dev/null Switch to console [cs0] @@ -59,8 +158,8 @@ Run barebox:: barebox:/ -Running RISC-V barebox on DE0-Nano FPGA board ---------------------------------------------- +Running on DE0-Nano FPGA board +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See https://github.com/open-design/riscv-soc-cores/ for instructions on DE0-Nano bitstream generation and loading. @@ -69,13 +168,13 @@ Connect to board's UART with your favorite serial communication software (e.g. minicom) and check 'nmon> ' prompt (nmon runs from onchip ROM). Next close your communication software and use ./scripts/nmon-loader -to load barebox image into board's DRAM, e.g. +to load barebox image into board's DRAM, e.g.:: # ./scripts/nmon-loader barebox.erizo.nmon /dev/ttyUSB0 115200 Wait several munutes for 'nmon> ' prompt. -Next, start barebox from DRAM: +Next, start barebox from DRAM:: nmon> g 80000000 Switch to console [cs0] @@ -89,3 +188,105 @@ Next, start barebox from DRAM: running /env/bin/init... /env/bin/init not found barebox:/ + +Allwinner D1 Nezha +------------------ + +Barebox has limited second-stage support for the Allwinner D1 Nezha (sun20i):: + + ARCH=riscv make rv64i_defconfig + ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu- make + +The resulting ``./images/barebox-allwinner-d1.img`` can be used as 2nd stage +image which gets called by opensbi:: + + git clone https://github.com/tekkamanninja/opensbi -b allwinner_d1 + cd opensbi + CROSS_COMPILE=riscv64-linux-gnu- PLATFORM=generic FW_PIC=y make + +The resulting ``./build/platform/generic/firmware/fw_dynamic.bin`` is loaded +by the 1st stage (spl) loader, which is basically a u-boot spl:: + + git clone https://github.com/smaeul/sun20i_d1_spl -b mainline + cd sun20i_d1_spl + CROSS_COMPILE=riscv64-linux-gnu- make p=sun20iw1p1 mmc + +The resulting ``./nboot/boot0_sdcard_sun20iw1p1.bin`` image used as 1st stage +bootloader which loads all necessary binaries: dtb, opensbi and barebox to the +dedicated places in DRAM. After loading it jumps to the opensbi image. The +initial dtb can be taken from u-boot:: + + git clone https://github.com/smaeul/u-boot.git -b d1-wip + cd u-boot + ARCH=riscv make nezha_defconfig + ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu- make + +Make will print two warnings at the end of this command but those can be ignored +since we only want the devicetree blob which can be found under ``./u-boot.dtb``. + +The final image is build by mkimage. It is some sort of a self-defined toc1 +format. So we need to compile the mkimage with the toc1 format support as +first:: + + cd u-boot + make tools-only + +The resulting ``tools/mkimage`` is used to build the toc1 image which is loaded +by the 1st stage bootloader from the mmc interface. To build the final toc1 image +we need to specify a toc1.cfg like:: + + [opensbi] + file = <ABSOLUT_PATH_TO>/opensbi/build/platform/generic/firmware/fw_dynamic.bin + addr = 0x40000000 + [dtb] + file = <ABSOLUT_PATH_TO>/u-boot/u-boot.dtb + addr = 0x44000000 + [u-boot] + file = <ABSOLUT_PATH_TO>/barebox/images/barebox-allwinner-d1.img + addr = 0x4a000000 + +Then we need to call:: + + mkimage -T sunxi_toc1 -d toc1.cfg boot.toc1 + +The last part is to place the 1st stage bootloader and the ``boot.toc1`` image +onto the correct places. So the ROM loader can find the 1st stage bootloader +and the 1st bootloader can find the ``boot.toc1`` image. This is done by:: + + dd if=boot0_sdcard_sun20iw1p1.bin of=/dev/sd<X> bs=512 seek=16 + dd if=boot.toc1 of=/dev/sd<X> bs=512 seek=32800 + +Now plug in the sdcard and power device and you will see:: + + [309]HELLO! BOOT0 is starting! + [312]BOOT0 commit : 882671f-dirty + [315]set pll start + [317]periph0 has been enabled + [320]set pll end + [322]board init ok + + ... + + OpenSBI v0.9-204-gc9024b5 + ____ _____ ____ _____ + / __ \ / ____| _ \_ _| + | | | |_ __ ___ _ __ | (___ | |_) || | + | | | | '_ \ / _ \ '_ \ \___ \| _ < | | + | |__| | |_) | __/ | | |____) | |_) || |_ + \____/| .__/ \___|_| |_|_____/|____/_____| + | | + |_| + + Platform Name : Allwinner D1 Nezha + Platform Features : medeleg + + ... + + barebox 2022.08.0-00262-g38678340903b #1 Tue Sep 13 12:54:29 CEST 2022 + + + Board: Allwinner D1 Nezha + + ... + + barebox@Allwinner D1 Nezha:/ diff --git a/Documentation/boards/riscv/barebox-virt32.cfg b/Documentation/boards/riscv/barebox-virt32.cfg new file mode 100644 index 0000000000..5f0eb34eee --- /dev/null +++ b/Documentation/boards/riscv/barebox-virt32.cfg @@ -0,0 +1,7 @@ +{ + version: 1, + machine: "riscv32", + memory_size: 256, + bios: "bbl32.bin", + kernel: "images/barebox-dt-2nd.img", +} diff --git a/Documentation/boards/riscv/barebox-virt64.cfg b/Documentation/boards/riscv/barebox-virt64.cfg new file mode 100644 index 0000000000..45e1cd8308 --- /dev/null +++ b/Documentation/boards/riscv/barebox-virt64.cfg @@ -0,0 +1,7 @@ +{ + version: 1, + machine: "riscv64", + memory_size: 256, + bios: "bbl64.bin", + kernel: "images/barebox-dt-2nd.img", +} diff --git a/Documentation/boards/rockchip.rst b/Documentation/boards/rockchip.rst index a5599c6d5f..583b4f1720 100644 --- a/Documentation/boards/rockchip.rst +++ b/Documentation/boards/rockchip.rst @@ -45,3 +45,76 @@ Instructions. * Run "rk-makebootable FlashData barebox-radxa-rock.bin rrboot.bin" * Insert SD card and run "dd if=rrboot.bin of=</dev/sdcard> bs=$((0x200)) seek=$((0x40))" * SD card is ready + +Rockchip RK356x +=============== + +Barebox features support for the Rockchip RK3566 and RK3568 SoCs, where the +RK3566 can be considered as reduced but largely identical version of the +RK3568. + +Supported Boards +---------------- + +- Rockchip RK3568 EVB +- Rockchip RK3568 Bananapi R2 Pro +- Pine64 Quartz64 Model A +- Radxa ROCK3 Model A +- Radxa CM3 (RK3566) IO Board + +The steps described in the following target the RK3568 and the RK3568 EVB but +generally apply to both SoCs and all boards. +Differences between the SoCs or boards are outlined where required. + +Building +-------- + +The build process needs three binary files which have to be copied from the +`rkbin https://github.com/rockchip-linux/rkbin` repository to the barebox source tree: + +.. code-block:: sh + + cp $RKBIN/bin/rk35/rk3568_bl31_v1.34.elf firmware/rk3568-bl31.bin + cp $RKBIN/bin/rk35/rk3568_bl32_v2.08.bin firmware/rk3568-op-tee.bin + cp $RKBIN/bin/rk35/rk3568_ddr_1560MHz_v1.13.bin arch/arm/boards/rockchip-rk3568-evb/sdram-init.bin + +With these barebox can be compiled as: + +.. code-block:: sh + + make ARCH=arm rockchip_v8_defconfig + make ARCH=arm + +**NOTE** I found the bl32 firmware non working for me as of 7d631e0d5b2d373b54d4533580d08fb9bd2eaad4 in the rkbin repository. + +**NOTE** The RK3566 and RK3568 seem to share the bl31 and bl32 firmware files, +whereas the memory initialization blob is different. + +Creating a bootable SD card +--------------------------- + +A bootable SD card can be created with: + +.. code-block:: sh + + dd if=images/barebox-rk3568-evb.img of=/dev/sdx bs=1024 seek=32 + +The barebox image is written to the raw device, so make sure the partitioning +doesn't conflict with the are barebox is written to. Starting the first +partition at offset 8MiB is a safe bet. + +USB bootstrapping +----------------- + +The RK3568 can be bootstrapped via USB for which the rk-usb-loader tool in the barebox +repository can be used. The tool takes the same images as written on SD cards: + +.. code-block:: sh + + ./scripts/rk-usb-loader images/barebox-rk3568-evb.img + +Note that the boot order of the RK3568 is not configurable. The SoC will only enter USB +MaskROM mode when no other bootsource contains a valid bootloader. This means to use USB +you have to make all other bootsources invalid by removing SD cards and shortcircuiting +eMMCs. The RK3568 EVB has a pushbutton to disable the eMMC. +On the Quartz64 boards, remove the eMMC module if present. diff --git a/Documentation/boards/s3c/Digi-a9m2440.rst b/Documentation/boards/s3c/Digi-a9m2440.rst deleted file mode 100644 index 32d58b9a04..0000000000 --- a/Documentation/boards/s3c/Digi-a9m2440.rst +++ /dev/null @@ -1,93 +0,0 @@ -DIGI a9m2440 -============ - -This CPU card is based on a Samsung S3C2440 CPU. The card is shipped with: - - * S3C2440\@400 MHz or 533 MHz (ARM920T/ARMv4T) - * 16.9344 MHz crystal reference - * SDRAM 32/64/128 MiB - - * Samsung K4M563233E-EE1H (one or two devices for 32 MiB or 64 MiB) - - * 2M x 32bit x 4 Banks Mobile SDRAM - * CL2\@100 MHz (CAS/RAS delay 19ns) - * 105 MHz max - * column address size is 9 bits - * Row cycle time: 69ns - - * Samsung K4M513233C-DG75 (one or two devices for 64 MiB or 128 MiB) - - * 4M x 32bit x 4 Banks Mobile SDRAM - * CL2\@100MHz (CAS/RAS delay 18ns) - * 111 MHz max - * column address size is 9 bits - * Row cycle time: 63ns - - * 64ms refresh period (4k) - * 90 pin FBGA - * 32 bit data bits - * Extended temperature range (-25°C...85°C) - - * NAND Flash 32/64/128 MiB - - * Samsung KM29U512T (NAND01GW3A0AN6) - - * 64 MiB 3,3V 8-bit - * ID: 0xEC, 0x76, 0x??, 0xBD - - * Samsung KM29U256T - - * 32 MiB 3,3V 8-bit - * ID: 0xEC, 0x75, 0x??, 0xBD - - * ST Micro - - * 128 MiB 3,3V 8-bit - * ID: 0x20, 0x79 - - * 30ns/40ns/20ns - - * I2C interface, 100 KHz and 400 KHz - - * Real Time Clock - - * Dallas DS1337 - * address 0x68 - - * EEPROM - - * ST M24LC64 - * address 0x50 - * 16bit addressing - - * LCD interface - * Touch Screen interface - * Camera interface - * I2S interface - * AC97 Audio-CODEC interface - * SD card interface - * 3 serial RS232 interfaces - * Host and device USB interface, USB1.1 compliant - * Ethernet interface - - * 10Mbps, Cirrus Logic, CS8900A (on the CPU card) - - * SPI interface - * JTAG interface - -How to get the binary image ---------------------------- - -Configure with the default configuration: - -.. code-block:: sh - - make ARCH=arm a9m2440_defconfig - -Build the binary image: - -.. code-block:: sh - - make ARCH=arm CROSS_COMPILE=armv4compiler - -**NOTE:** replace the armv4compiler with your ARM v4 cross compiler. diff --git a/Documentation/boards/samsung.rst b/Documentation/boards/samsung.rst deleted file mode 100644 index f6f341301d..0000000000 --- a/Documentation/boards/samsung.rst +++ /dev/null @@ -1,8 +0,0 @@ -Samsung S3C/S5P -=============== - -.. toctree:: - :glob: - :maxdepth: 1 - - s3c/* diff --git a/Documentation/boards/sandbox.rst b/Documentation/boards/sandbox.rst index 8b00093fb9..e9e5183653 100644 --- a/Documentation/boards/sandbox.rst +++ b/Documentation/boards/sandbox.rst @@ -17,7 +17,7 @@ The barebox sandbox can be built with the host compiler: Running the sandbox ------------------- -Once you compile barebox for the sandbox, you can run it with:: +Once you compile barebox for the sandbox, you can run it with: .. code-block:: console @@ -34,6 +34,20 @@ Available sandbox invocation options include: Map a <file> to barebox. This option can be given multiple times. The <file>s will show up as ``/dev/fd0`` ... ``/dev/fdX`` in the barebox simulator. + How the file is mapped in barebox can be controlled by a number of flags: + + * ``,ro``: The host file is mapped read-only + + * ``,blkdev``: The host file is to be mapped as block device. This is the + default when passing block devices from the host. The file's size must + be a multiple of the barebox sector size of 512 bytes. + + * ``,cdev``: The host file is mapped as character device. This is the default, + unless the the host file is a block device. + + Multiple options can be appended if they don't clash. Literal commas within the + file path can be escaped with a backslash. Example: ``-i './0\,0.hdimg,blkdev,ro'``. + ``-e <file>`` Map <file> to barebox. With this option <file>s are mapped as diff --git a/Documentation/boards/socfpga.rst b/Documentation/boards/socfpga.rst index 19d6060300..7e7f0619ea 100644 --- a/Documentation/boards/socfpga.rst +++ b/Documentation/boards/socfpga.rst @@ -121,7 +121,7 @@ Now run the command: .. code-block:: sh - scripts/socfpga_import_preloader <EMBEDDED_SDK> <ISW_HANDOFF> <BOARD_DIRECTORY> + scripts/socfpga_import_preloader -e <EMBEDDED_SDK> -i <ISW_HANDOFF> -b <BOARD_DIRECTORY> where `<SPL_GENERATED_DIR>` is the directory where the bsp-editor generated the files, `<ISW_HANDOFF>` is the directory where Quartus generated the handoff files, and diff --git a/Documentation/boards/stm32mp.rst b/Documentation/boards/stm32mp.rst index de793ab3c9..813117a04f 100644 --- a/Documentation/boards/stm32mp.rst +++ b/Documentation/boards/stm32mp.rst @@ -5,37 +5,87 @@ The STM32MP is a line of 32-bit ARM SoCs. They reuse peripherals of the STM32 line of microcontrollers and can have a STM32 MCU embedded as co-processor as well. -The boot process of the STM32MP SoC is a two step process. +The boot process of the STM32MP1 SoC is a two step process. The first stage boot loader (FSBL) is loaded by the ROM code into the built-in SYSRAM and executed. The FSBL sets up the SDRAM, install a secure monitor and then the second stage boot loader (SSBL) is loaded into DRAM. -When building barebox, the resulting ``barebox-${board}.img`` file has the STM32 +When building barebox, the resulting ``barebox-${board}.stm32`` file has the STM32 header preprended, so it can be loaded directly as SSBL by the ARM TF-A (https://github.com/ARM-software/arm-trusted-firmware). Each entry point has a -header-less image ending in ``*.pblb`` as well. +header-less image ending in ``*.pblb`` as well. Additionally, there is +a ``barebox-stm32mp-generic.img``, which is a header-less image for +use as part of a Firmware Image Package (FIP). -Use of barebox as FSBL is not supported. +barebox images are meant to be loaded by the ARM TF-A +(https://github.com/ARM-software/arm-trusted-firmware). FIP images are +mandatory for STM32MP1 since TF-A v2.7. + +Use of barebox as FSBL is not implemented. Building barebox ---------------- -With multi-image and device trees, it's expected to have ``stm32mp_defconfig`` -as sole defconfig for all STM32MP boards:: +There's a single ``stm32mp_defconfig`` for all STM32MP boards:: - make ARCH=arm stm32mp_defconfig + export ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- + make stm32mp_defconfig + make -The resulting images will be placed under ``images/``: +The resulting images will be placed under ``images/``:: -:: + barebox-stm32mp-generic-bl33.img + barebox-stm32mp13xx-dk.stm32 + barebox-stm32mp15xx-dkx.stm32 + barebox-stm32mp15x-ev1.stm32 + barebox-stm32mp157c-lxa-mc1.stm32 + barebox-prtt1a.stm32 + barebox-prtt1s.stm32 + barebox-prtt1c.stm32 + barebox-stm32mp157c-seeed-odyssey.stm32 + barebox-dt-2nd.img - barebox-stm32mp157c-dk2.img +In the above output, images with a ``.stm32`` extension feature the (legacy) +stm32image header. ``barebox-dt-2nd.img`` and ``barebox-stm32mp-generic-bl33.img`` +are board-generic barebox images that receive an external device tree. +.. _stm32mp_fip: -Flashing barebox ----------------- +Flashing barebox (FIP) +---------------------- + +After building barebox in ``$BAREBOX_BUILDDIR``, change directory to ARM +Trusted Firmware to build a FIP image. Example building STM32MP157C-DK2 +with SP_min (no OP-TEE): + +.. code:: bash + + make CROSS_COMPILE=arm-none-eabi- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 \ + STM32MP_EMMC=1 STM32MP_EMMC_BOOT=1 STM32MP_SDMMC=1 STM32MP_SPI_NOR=1 \ + AARCH32_SP=sp_min \ + DTB_FILE_NAME=stm32mp157c-dk2.dtb \ + BL33=$BAREBOX_BUILDDIR/images/barebox-stm32mp-generic-bl33.img \ + BL33_CFG=$BAREBOX_BUILDDIR/arch/arm/dts/stm32mp157c-dk2.dtb \ + fip + +For different boards, adjust ``DTB_FILENAME`` and ``BL33_CFG`` as appropriate. + +If OP-TEE is used, ensure ``CONFIG_OPTEE_SIZE`` is set appropriately, so +early barebox code does not attempt accessing secure memory. + +barebox can also be patched into an existing FIP image with ``fiptool``: + +.. code:: bash -An appropriate image for a SD-Card can be generated with following + fiptool update mmcblk0p3 \ + --nt-fw $BAREBOX_BUILDDIR/images/barebox-stm32mp-generic-bl33.img \ + --hw-config $BAREBOX_BUILDDIR/arch/arm/dts/stm32mp135f-dk.dtb + +Flashing barebox (legacy stm32image) +------------------------------------ + +After building ARM Trusted Firmware with ``STM32MP_USE_STM32IMAGE=1``, +an appropriate image for a SD-Card can be generated with following ``genimage(1)`` config:: image @STM32MP_BOARD@.img { @@ -52,7 +102,7 @@ An appropriate image for a SD-Card can be generated with following size = 256K } partition ssbl { - image = "barebox-@STM32MP_BOARD@.img" + image = "barebox-@STM32MP_BOARD@.stm32" size = 1M } partition barebox-environment { @@ -62,11 +112,11 @@ An appropriate image for a SD-Card can be generated with following } For eMMC, the boot partitions are used as the FSBL partitions and so the user -partitions may look like this: +partitions may look like this:: image @STM32MP_BOARD@.img { partition ssbl { - image = "barebox-@STM32MP_BOARD@.img" + image = "barebox-@STM32MP_BOARD@.stm32" size = 1M } partition barebox-environment { @@ -78,11 +128,84 @@ partitions may look like this: The fsbl1 and fsbl2 can be flashed by writing to barebox ``/dev/mmcX.boot0`` and ``/dev/mmcX.boot1`` respectively or from a booted operating system. +Additionally, the eMMC's ``ext_csd`` register must be modified to activate the +boot acknowledge signal (``BOOT_ACK``) and to select a boot partition. + +Assuming ``CONFIG_CMD_MMC_EXTCSD`` is enabled and the board shall boot from +``/dev/mmc1.boot1``:: + + mmc_extcsd /dev/mmc1 -i 179 -v 0x50 + +The STM32MP1 BootROM does *not* support booting from eMMC without fast boot +acknowledge. + +USB Bootstrap (DFU) +------------------- + +The STM32MP1 can be strapped to boot from USB. After Power-On reset, it +should be detectable as ``STMicroelectronics STM Device in DFU Mode`` +and can be uploaded to with ``dfu-util(1)``:: + + dfu-util --alt 1 -D tf-a-stm32mp157c-my-board.stm32 + dfu-util --alt 3 -D bl3-firmware.fip + dfu-util --alt 0 -e + +The first command will talk to the BootROM and upload the first stage +bootloader (ARM Trusted Firmware-A) into on-chip SRAM. + +When compiled with ``STM32MP_USB_PROGRAMMER=1``, TF-A v2.6 or higher +will seamlessly continue operation of the DFU gadget. The second +command will talk to TF-A to upload a Firmware Image Package, which +is a format bundling further firmware including barebox. + +The final command will instruct TF-A to boot the loaded images. +This all happens in volatile memory. To persist images, use +normal barebox functionality like creating a DFU-gadget in barebox, +Fastboot/USB mass storage ... etc. + +The FIP image containing barebox can be generated as described in +:ref:`stm32mp_fip`. Upstream TF-A doesn't support DFU for +SSBLs using the legacy stm32image format. + +DFU mode can be forced via :ref:`reboot_mode` from a booted system with:: + + tamp.reboot_mode.next=serial reset -w + Boot source selection --------------------- -The STM32MP BootROM samples three boot pins at reset. Usually BOOT1 is -pulled down and BOOT0 and BOOT2 are connected to a 2P DIP switch:: +The STM32MP BootROM samples three boot pins at reset. On official +eval kit, they are either connected to a 3P DIP switch or 2P (with +BOOT1 pulled down). + +EV-1 +^^^^ +SW1 on the DK boards sets boot mode as follows:: + + +-------+ + | --- | + BOOT2 | O-- | + BOOT1 | O --O | + BOOT0 | N O-- | <---- SD-Card + +-------+ + + +-------+ + | --- | + BOOT2 | --O | + BOOT1 | O O-- | + BOOT0 | N --O | <---- eMMC + +-------+ + + +-------+ + | --- | + BOOT2 | --O | + BOOT1 | O --O | + BOOT0 | N --O | <---- DFU on UART and USB OTG + +-------+ + +DK-1/DK-2 +^^^^^^^^^ +Boot mode on the DK board is set as follows:: +-------+ BOOT2 | O O-- | diff --git a/Documentation/boards/x86.rst b/Documentation/boards/x86.rst deleted file mode 100644 index 4514a766a2..0000000000 --- a/Documentation/boards/x86.rst +++ /dev/null @@ -1,148 +0,0 @@ -x86 -=== - -Features --------- - -barebox can act as a bootloader for PC based systems. In this case a special -binary layout will be created to be able to store it on some media the PC -BIOS can boot from. It can boot Linux kernels stored also on the same boot -media and be configured at runtime, with the possibility to store the changed -configuration on the boot media. - -Restrictions ------------- - -Due to some BIOS and barebox restrictions the boot media must be -prepared in some special way: - - * barebox must be stored in the MBR (Master Boot Record) of the boot - media. Currently its not possible to store and boot it in one of - the partition sectors to use it as a second stage loader). This is - no eternal restriction. It only needs further effort to add this - feature. - * barebox currently cannot run a chained boot loader. Also, this is - no external restriction, only further effort needed. - * barebox comes with limited filesystem support. There is currently - no support for the most common and popular filesystems used in the - \*NIX world. This restricts locations where to store a kernel and - other runtime information - * barebox must be stored to the first n sectors of the boot media. - To ensure this does not collide with partitions on the boot media, - the first partition must start at a sector behind the ones barebox - occupies. - * barebox handles its runtime configuration in a special way: It - stores it in a binary way into some reserved sectors ("persistant - storage"). - -Boot Preparations ------------------ - -To store the barebox image to a boot media, it comes with the tool -setupmbr in the directory scripts/setupmbr/ . To be able to use it on -the boot media of your choice, some preparations are required. - -Keep Sectors free ------------------ - -Build the barebox image and check its size. At least this amount of -sectors must be kept free after the MBR prior the first partition. Do this -simple calulation: - -.. code-block:: none - - sectors = (size of barebox image + 511) / 512 - -To be able to store the runtime configuration, further free sectors are -required. Its up to you and your requirements, how large this persistant -storage must be. If you need 16 kiB for this purpose, you need to keep -additional 32 sectors free. - -For this example we are reserving 300 sectors for the barebox image and -additionaly 32 sectors for the persistant storage. So, the first partition on -the boot media must start at sector 333 or later. - -Run the fdisk tool to setup such a partition table: - -.. code-block:: none - - [jb@host]~> fdisk /dev/sda - Command (m for help): p - - Disk /dev/sda: 20.7 MB, 212680704 bytes - 16 heads, 63 sectors/track, 406 cylinders - Units = cylinders of 1008 * 512 = 516096 bytes - - Device Boot Start End Blocks Id System - -Change the used units to sectors for easier handling. - -.. code-block:: none - - Command (m for help): u - Changing display/entry units to sectors - - Command (m for help): p - - Disk /dev/sda: 20.7 MB, 212680704 bytes - 16 heads, 63 sectors/track, 406 cylinders, total 409248 sectors - Units = sectors of 1 * 512 = 512 bytes - - Device Boot Start End Blocks Id System - -Now its possible to create the first partition with the required offset: - -.. code-block:: none - - Command (m for help): n - Command action - e extended - p primary partition (1-4) - p - Partition number (1-4): 1 - First sector (63-409247, default 63): 333 - Last sector or +size or +sizeM or +sizeK (333-409247, default 409247): +18M - Command (m for help): p - - Disk /dev/sda: 20.7 MB, 212680704 bytes - 16 heads, 63 sectors/track, 406 cylinders, total 409248 sectors - Units = sectors of 1 * 512 = 512 bytes - - Device Boot Start End Blocks Id System - /dev/sda 333 35489 17578+ 83 Linux - -That's all. Do whatever is required now with the new partition (formatting -and populating the root filesystem for example) to make it useful. - -In the next step, barebox gets installed to this boot media:: - - [jb@host]~> scripts/setupmbr/setupmbr -s 32 -m ./barebox -d /dev/sda - -This command writes the barebox image file './barebox' onto the device - /dev/sda. - -The -s option will keep the persistant storage sectors free and untouched -and set flags in the MBR to forward its existance, size and location to -barebox at runtime. setupmbr also does not change the partition table. - -The barebox image gets stored on the boot media like this:: - - sector 0 1 33 333 - |---|-------------|--------------- ~~~ ------------|-------------- - MBR persistant barebox first - storage main image partition - -If the -s option is omitted, the "persistant storage" part simply does -not exist: - -.. code-block:: none - - sector 0 1 333 - |---|--------------- ~~~ ------------|-------------- - MBR barebox first - main image partition - -**NOTE:** the ``setupmbr`` tool is also working on real image file than on device -nodes only. So, there is no restriction what kind of file will be -modified. - diff --git a/Documentation/boards/zynqmp.rst b/Documentation/boards/zynqmp.rst new file mode 100644 index 0000000000..86078d496e --- /dev/null +++ b/Documentation/boards/zynqmp.rst @@ -0,0 +1,40 @@ +Xilinx ZynqMP Ultrascale+ +========================= + +Barebox has support as a second stage boot loader for the Xilinx ZynqMP +Ultrascale+. + +Image creation +-------------- + +Currently, Barebox only supports booting as a second stage boot loader from an +SD-card. It relies on the FSBL_ to initialize the base system including sdram +setup and pin muxing. + +The ZynqMP defconfig supports the ZCU102/104/106 reference board. Use it to build the +Barebox image:: + + make ARCH=arm64 zynqmp_defconfig + make ARCH=arm64 + +.. note:: The resulting image ``images/barebox-zynqmp-zcuX.img`` is **not** an image + that can directly be booted on the ZynqMP. + +For a bootable BOOT.BIN image, you also need to build the FSBL_ and a ZynqMP +TF-A. Prepare these separately using the respective instructions. + +Use bootgen_ or ``mkimage -T zynqmpbif`` from the U-boot tools to build the +final BOOT.BIN image that can be loaded by the ROM code. Check the +instructions for these tools how to prepare the BOOT.BIN image. + +Create a FAT partition as the first partition of the SD card and copy the +produced BOOT.BIN into this partition. + +.. _FSBL: https://github.com/Xilinx/embeddedsw/ +.. _bootgen: https://github.com/Xilinx/bootgen + +Booting Barebox +--------------- + +The FSBL loads the TF-A and Barebox, jumps to the TF-A, which will then return +to Barebox. Afterwards, you can use Barebox as usual. diff --git a/Documentation/conf.py b/Documentation/conf.py index bcd8633c91..5fb8b07c38 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -44,7 +44,7 @@ master_doc = 'index' # General information about the project. project = u'barebox' -copyright = u'2014, The barebox project' +copyright = u'2014–2022, The barebox project' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/Documentation/devel/background-execution.rst b/Documentation/devel/background-execution.rst new file mode 100644 index 0000000000..d379593efb --- /dev/null +++ b/Documentation/devel/background-execution.rst @@ -0,0 +1,142 @@ +Background execution in barebox +=============================== + +barebox does not use interrupts to avoid the associated increase in complexity. +Nevertheless it is sometimes desired to execute code "in the background", +like for example polling for completion of transfers or to regularly blink a +heartbeat LED. For these scenarios barebox offers the techniques described below. + +Pollers +------- + +Pollers are a way in barebox to frequently execute code in the background. +They don't run within their own threads, but instead they are executed +whenever ``is_timeout()`` is called. +This has a few implications. First of all, pollers are not executed when +``is_timeout()`` is not called. For this and other reasons, loops polling for +hardware events should always use a timeout, which is best implemented with +``is_timeout()``. Another thing to remember is that pollers can be executed +anywhere in the middle of other device accesses whenever ``is_timeout()`` is +called. Care must be taken that a poller doesn't access the very same device +again itself. See "slices" below on how devices can safely be accessed from +pollers. Some operations are entirely forbidden from pollers. For example it is +forbidden to access the virtual filesystem, as this could trigger arbitrary +device accesses. The macro ``assert_command_context()`` is added to those +places to make sure they are not called in the wrong context. The poller +interface is declared in ``include/poller.h``. ``poller_register()`` is used +to register a poller. The ``struct poller_struct`` passed to +``poller_register()`` needs to have the ``poller_struct.func()`` member +populated with the function that shall be called. From the moment a poller is +registered ``poller_struct.func()`` will be called regularly as long as someone +calls ``is_timeout()``. A special poller can be registered with +``poller_async_register()``. A poller registered this way won't be called right +away, instead running it can be triggered by calling ``poller_call_async()``. +This will execute the poller after the ``@delay_ns`` argument. +``poller_call_async()`` may also be called from with the poller, so with this +it's possible to run a poller regularly with configurable delays. + +Pollers are limited in the things they can do. Poller code must always be +prepared for the case that the resources it accesses are currently busy and +handle this gracefully by trying again later. Most places in barebox either do +not test for resources being busy or return with an error if they are busy. +Calling into the filesystem potentially uses arbitrary other devices, so +doing this from pollers is forbidden. For the same reason it is forbidden +to execute barebox commands from pollers. + +Workqueues +---------- + +Sometimes code wants to access files from poller context or even wants to +execute barebox commands from poller context. The fastboot implementation is an +example for such a case. The fastboot commands come in via USB or network and +the completion and packet receive handlers are executed in poller context. Here +workqueues come into play. They allow to queue work items from poller context. +These work items are executed later at the point where the shell fetches its +next command. At this point we implicitly know that it's allowed to execute +commands or to access the filesystem, because otherwise the shell could not do +it. This means that execution of the next shell command will be delayed until +all work items are being done. Likewise the work items will only be executed +when the current shell command has finished. + +The workqueue interface is declared in ``include/work.h``. + +``wq_register()`` is the first step to use the workqueue interface. +``wq_register()`` registers a workqueue to which work items can be attached. +Before registering a workqueue a ``struct work_queue`` has to be populated with +two function callbacks. ``work_queue.fn()`` is the callback that actually does +the work once it is scheduled. ``work_queue.cancel()`` is a callback which is +executed when the pending work shall be cancelled. This is primarily for +freeing the memory associated to a work item. ``wq_queue_work()`` is for +actually queueing a work item on a work queue. This can be called from poller +code. Usually a work item is allocated by the poller and then freed either in +``work_queue.fn()`` or in ``work_queue.cancel()``. + +bthreads +-------- + +barebox threads are co-operative green threads, which are scheduled for the +same context as workqueues: Before the shell executes the next command. +This means that bthreads can be used to implement workqueues, but not pollers. + +The bthread interface is declared in ``include/bthread.h``. +``bthread_create()`` is used to allocate a bthread control block along with +its stack. ``bthread_wake()`` can be used to add it into the run queue. +From this moment on and until the thread terminates, the thread will be +switched to regularly as long as the shell processes commands. + +bthreads are allowed to call ``is_timeout()``, which will eventually +arrange for other threads to execute. This allowed implementing a Linux-like +completion API on top, which can be useful for porting threaded kernel code. + +Slices +------ + +Slices are a way to check if a device is currently busy and thus may not be +called into currently. Pollers wanting to access a device must call +``slice_busy()`` on the slice provided by the device before calling into it. +When the slice is acquired (which can only happen inside a poller) the poller +can't continue at this moment and must try again next time it is executed. +Drivers whose devices provide a slice must call ``slice_acquire()`` before +accessing the device and ``slice_release()`` afterwards. Slices can have +dependencies to other slices, for example a USB network controller uses the +corresponding USB host controller. A dependency can be expressed with +``slice_depends_on()``. With this the USB network controller can add a +dependency from the network device it provides itself to the USB host +controller it depends on. With this ``slice_busy()`` on the network device +will return ``true`` when the USB host controller is busy. + +The usual pattern for using slices is that the device driver for a device +calls ``slice_acquire()`` when entering the driver and ``slice_release()`` +before leaving the driver. The driver also provides a function returning +the slice for a device, for example the ethernet support code provides +``struct slice *eth_device_slice(struct eth_device *edev)``. Poller code +which wants to use the ethernet device checks for the availability doing +``slice_busy(eth_device_slice(edev))`` before accessing the ethernet +device. When the slice is not busy the poller can continue with accessing +that device. Otherwise the poller must return and try again next time it +is called. + +Limitations +----------- + +What barebox does is best described as cooperative multitasking. As pollers +can't be interrupted, it will directly affect the user experience when they +take too long. When barebox reacts sluggishly to key presses, then probably +pollers take too long to execute. A first test if this is the case can +be done by executing ``poller -t`` on the command line. This command will print +how many times we can execute all registered pollers in one second. When this +number is too low then pollers are guilty responsible. Workqueues help to run +schedule/execute longer running code, but during the time while workqueues are +executed nothing else happens. This means that when fastboot flashes an image +in a workqueue then barebox won't react to any key presses on the command line. +The usage of the interfaces described in this document is not yet very +widespread in barebox. The interfaces are used in the places where we need +them, but there are other places which do not use them but should. For example +using a LED driven by a I2C GPIO exander used as hearbeat LED won't work +properly currently. Consider the I2C driver accesses an unrelated I2C device, +like an EEPROM. After having initiated the transfer the driver polls for the +transfer being completed using a ``is_timeout()`` loop. The call to +``is_timeout()`` then calls into the registered pollers from which one accesses +the same I2C bus whose driver is just polling for completion of another +transfer. With this the I2C driver is in an undefined state and will likely not +work anymore. diff --git a/Documentation/devel/devel.rst b/Documentation/devel/devel.rst new file mode 100644 index 0000000000..39070074ca --- /dev/null +++ b/Documentation/devel/devel.rst @@ -0,0 +1,16 @@ +.. highlight:: console + +barebox programming +=================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + porting + background-execution + project-ideas + +* :ref:`search` +* :ref:`genindex` diff --git a/Documentation/devel/porting.rst b/Documentation/devel/porting.rst new file mode 100644 index 0000000000..e63de12590 --- /dev/null +++ b/Documentation/devel/porting.rst @@ -0,0 +1,566 @@ +########################## +The barebox Porter's Guide +########################## + +While barebox puts much emphasis on portability, running on bare-metal +means that there is always machine-specific glue that needs to be provided. +This guide shows places where the glue needs to be applied and how to go +about porting barebox to new hardware. + +.. note:: + This guide is written with mainly ARM and RISC-V barebox in mind. + Other architectures may differ. + +************ +Introduction +************ + +Your usual barebox binary consists of two parts. A prebootloader doing +the bare minimum initialization and then the proper barebox binary. + +barebox proper +============== + +This is the main part of barebox and, like a multi-platform Linux kernel, +is platform-agnostic: The program starts, registers its drivers and tries +to match the drivers with the devices it discovers at runtime. +It initializes file systems and common management facilities and finally +starts an init process. barebox knows no privilege separation and the +init process is built into barebox. +The default init is the :ref:`Hush`, but can be overridden if required. + +For such a platform-agnostic program to work, it must receive external +input about what kind of devices are available: For example, is there a +timer? At what address and how often does it tick? For most barebox +architectures this hardware description is provided in the form +of a flattened device tree (FDT). As part of barebox' initialization +procedure, it unflattens (parses) the device tree and starts probing +(matching) the devices described within with the drivers that are being +registered. + +The device tree can also describe the RAM available in the system. As +walking the device tree itself consumes RAM, barebox proper needs to +be passed information about an initial memory region for use as stack +and for dynamic allocations. When barebox has probed the memory banks, +the whole memory will become available. + +As result of this design, the same barebox proper binary can be reused for +many different boards. Unlike Linux, which can expect a bootloader to pass +it the device tree, barebox *is* the bootloader. For this reason, barebox +proper is prefixed with what is called a prebootloader (PBL). The PBL +handles the low-level details that need to happen before invoking barebox +proper. + +Prebootloader (PBL) +=================== + +The :ref:`prebootloader <pbl>` is a small chunk of code whose objective is +to prepare the environment for barebox proper to execute. This means: + + - Setting up a stack + - Determining a memory region for initial allocations + - Provide the device tree + - Jump to barebox proper + +The prebootloader often runs from a constrained medium like a small +(tens of KiB) on-chip SRAM or sometimes even directly from flash. + +If the size constraints allow, the PBL will contain the barebox proper +binary in compressed form. After ensuring any external DRAM can be +addressed, it will unpack barebox proper there and call it with the +necessary arguments: an initial memory region and the FDT. + +If this is not feasible, the PBL will contain drivers to chain load +barebox proper from the storage medium. As this is usually the same +storage medium the PBL itself was loaded from, shortcuts can often +be taken: e.g. a SD-Card could already be in the correct mode, so the +PBL driver can just read the blocks without having to reinitialize +the SD-card. + +barebox images +============== + +In a typical build, the barebox build process generates multiple images +(:ref:`multi_image`). All enabled PBLs are each linked with the same +barebox proper binary and then the resulting images are processed to be +in the format expected by the loader. + +The loader is often a BootROM, but maybe another first stage bootloader +or a hardware debugger. + +Let us now put these new concepts into practice. We will start by adding +a new board for a platform, for which similar boards already exist. +Then we'll look at adding a new SoC, then a new SoC family and finally +a new architecture. + +********************** +Porting to a new board +********************** + +.. note:: + Parts of this guide are taken from this ELC-E 2020 talk: + https://www.youtube.com/watch?v=Oj7lKbFtyM0 + +Chances are there's already a supported board similar to yours, e.g. +an evaluation kit from the vendor. Take a look at ``arch/$ARCH/boards/`` +and do likewise for you board. The main steps would be: + +Entry point +=========== + +The PBL's entry point is the first of your code that's run. What happens +there depends on the previously running code. If a previous stage has already +initialized the DRAM, the only thing you need to do is to set up a stack and +call the common PBL code with a memory region and your device tree blob:: + + #include <asm/barebox-arm.h> + #include <console.h> + + ENTRY_FUNCTION_WITHSTACK(start_my_board, MY_STACK_TOP, r0, r1, r2) + { + extern char __dtb_my_board_start[]; + void *fdt; + + relocate_to_current_adr(); + setup_c(); + + pbl_set_putc(my_serial_putc, (void *)BASE_ADDR); + + barebox_arm_entry(0x80000000, SZ_256M, __dtb_my_board_start); + } + +Lets look at this line by line: + +``ENTRY_FUNCTION_WITHSTACK(start_my_board, MY_STACK_TOP, r0, r1, r2)`` + The entry point is special: It needs to be located at the beginning of the + image, it does not return and may run before a stack is set up. + To make it possible to write this entry point in C, the macro places + a machine code prologue that uses ``MY_STACK_TOP`` as the initial stack + pointer. If the stack is already set up, you may pass 0 here. + + Additionally, the macro passes along a number of registers, in case the + Boot ROM has placed something interesting there. + +``extern char __dtb_my_board_start[];`` + When a device tree is built as part of the PBL, ``__dtb_*_start`` and + ``__dtb_*_end`` will be defined for it by the build system; + its name is determined by the name of the device tree source file. + Declare the start variable, so you can pass along the address of the device + tree. + +``relocate_to_current_adr();`` + Machine code contains a mixture of relative and absolute addressing. + Because the PBL doesn't know in advance which address it's loaded to, + the link address of global variables may not be correct. To correct + them a runtime offset needs to be added, so they point at the + correct location. This procedure is called relocation and is achieved + by this function. Note that this is self-modifying code, so it's not + safe to call this when executing in-place from flash or ROM. + +``setup_c();`` + As a size optimization, zero-initialized variables of static storage + duration are not written to the executable. Instead only the region + where they should be located is described and at runtime that region + is zeroed. This is what ``setup_c()`` does. + +``pbl_set_putc(my_serial_putc, (void *)BASE_ADDR);`` + Now that we have a C environment set up, lets set our first global + variable. ``pbl_set_putc`` saves a pointer to a function + (``my_serial_putc``) that is called by the ``pr_*`` functions to output a + single character. This can be used for the early PBL console to output + messages even before any drivers are initialized. + The second parameter (UART register base address in this instance) is passed + as a user parameter when the provided function is called. + +``barebox_arm_entry(...)`` + This will compute a new stack top from the supplied memory + region, uncompress barebox proper and pass along its arguments. + +Looking at other boards you might see some different patterns: + +``*_cpu_lowlevel_init();`` + Often some common initialization and quirk handling + needs to be done at start. If a board similar to yours does this, you probably + want to do likewise. + +``__naked`` + All functions called before stack is correctly initialized must be + marked with this attribute. Otherwise, function prologue and epilogue may access + the uninitialized stack. Note that even with ``__naked``, the compiler may still + spill excess local C variables used in a naked function to the stack before it + was initialized. A naked function should thus preferably only contain inline + assembly, set up a stack and jump directly after to a ``noinline`` non naked + function where the stack is then normally usable. This pattern is often seen + together with ``ENTRY_FUNCTION``. Modern boards better avoid this footgun + by using ``ENTRY_FUNCTION_WITHSTACK``, which will take care to initialize the + stack beforehand. If either a barebox assembly entry point, + ``ENTRY_FUNCTION_WITHSTACK`` or earlier firmware has set up the stack, there is + no reason to use ``__naked``, just use ``ENTRY_FUNCTION_WITHSTACK`` with a zero + stack top. + +``noinline`` + Compiler code inlining is oblivious to stack manipulation in + inline assembly. If you want to ensure a new function has its own stack frame + (e.g. after setting up the stack in a ``__naked`` function), you must jump to + a ``__noreturn noinline`` function. This is already handled by + ``ENTRY_FUNCTION_WITHSTACK``. + +``arm_setup_stack`` + For 32-bit ARM, ``arm_setup_stack`` initializes the stack + top when called from a naked C function, which allowed to write the entry point + directly in C. Modern code should use ``ENTRY_FUNCTION_WITHSTACK`` instead. + Note that in both cases the stack pointer will be decremented before pushing values. + Avoid interleaving with C-code. See ``__naked`` above for more details. + +``__dtb_z_my_board_start[];`` + Because the PBL normally doesn't parse anything out + of the device tree blob, boards can benefit from keeping the device tree blob + compressed and only unpack it in barebox proper. Such compressed device trees + are prefixed with ``__dtb_z_``. It's usually a good idea to use this. + +``imx6q_barebox_entry(...);`` + Sometimes it's possible to query the memory + controller for the size of RAM. If there are SoC-specific helpers to achieve + this, you should use them. + +``get_runtime_offset()/global_variable_offset()`` + This functions return the difference + between the link and load address. This is zero after relocation, but the + function can be useful to pass along the correct address of a variable when + relocation has not yet occurred. If you need to use this for anything more + then passing along the FDT address, you should reconsider and probably rather + call ``relocate_to_current_adr();``. + +``*_start_image(...)/*_load_image(...)/*_xload_*(...)`` + If the SRAM couldn't fit both PBL and the compressed barebox proper, PBL + will need to chainload full barebox binary from the boot medium. + +Repeating previous advice: The specifics about how different SoCs handle +things can vary widely. You're best served by mimicking a similar recently +added board if one exists. If there's none, continue reading the following +sections. + +Board code +========== + +If you need board-specific setup that's not covered by any upstream device +tree binding, you can write a driver that matches against your board's +``/compatible``:: + + static int my_board_probe(struct device *dev) + { + /* Do some board-specific setup */ + return 0; + } + + static const struct of_device_id my_board_of_match[] = { + { .compatible = "my,cool-board" }, + { /* sentinel */ }, + }; + + static struct driver my_board_driver = { + .name = "board-mine", + .probe = my_board_probe, + .of_compatible = my_board_of_match, + }; + device_platform_driver(my_board_driver); + +Keep what you do here to a minimum. Many thing traditionally done here +should rather happen in the respective drivers (e.g. PHY fixups). + +Device-Tree +=========== + +barebox regularly synchronizes its ``/dts/src`` directory with the +upstream device trees in Linux. If your device tree happens to already +be there you can just include it:: + + #include <arm/st/stm32mp157c-odyssey.dts> + #include "stm32mp151.dtsi" + + / { + chosen { + environment-emmc { + compatible = "barebox,environment"; + device-path = &sdmmc2, "partname:barebox-environment"; + }; + }; + }; + + &phy0 { + reset-gpios = <&gpiog 0 GPIO_ACTIVE_LOW>; + }; + +Here, the upstream device tree is included, then a barebox-specific +SoC device tree ``"stm32mp151.dtsi"`` customizes it. The device tree +adds some barebox-specific info like the environment used for storing +persistent data during development. If the upstream device tree lacks +some info which are necessary for barebox there can be added here +as well. Refer to :ref:`bareboxdt` for more information. + +Boilerplate +=========== + +A number of places need to be informed about the new board: + + - Either ``arch/$ARCH/Kconfig`` or ``arch/$ARCH/mach-$platform/Kconfig`` + needs to define a Kconfig symbol for the new board + - ``arch/$ARCH/boards/Makefile`` needs to be told which directory the board + code resides in + - ``arch/$ARCH/dts/Makefile`` needs to be told the name of the device tree + to be built + - ``images/Makefile.$platform`` needs to be told the name of the entry point(s) + for the board + +Example:: + + --- /dev/null + +++ b/arch/arm/boards/seeed-odyssey/Makefile + +lwl-y += lowlevel.o + +obj-y += board.o + + --- a/arch/arm/mach-stm32mp/Kconfig + +++ b/arch/arm/mach-stm32mp/Kconfig + +config MACH_SEEED_ODYSSEY + + select ARCH_STM32MP157 + + bool "Seeed Studio Odyssey" + + --- a/arch/arm/boards/Makefile + +++ b/arch/arm/boards/Makefile + +obj-$(CONFIG_MACH_SEEED_ODYSSEY) += seeed-odyssey/ + + --- a/arch/arm/dts/Makefile + +++ b/arch/arm/dts/Makefile + +lwl-$(CONFIG_MACH_SEEED_ODYSSEY) += stm32mp157c-odyssey.dtb.o + + --- a/images/Makefile.stm32mp + +++ b/images/Makefile.stm32mp + $(obj)/%.stm32: $(obj)/% FORCE + $(call if_changed,stm32_image) + + STM32MP1_OPTS = -a 0xc0100000 -e 0xc0100000 -v1 + + +pblb-$(CONFIG_MACH_SEEED_ODYSSEY) += start_stm32mp157c_seeed_odyssey + +FILE_barebox-stm32mp157c-seeed-odyssey.img = start_stm32mp157c_seeed_odyssey.pblb.stm32 + +OPTS_start_stm32mp157c_seeed_odyssey.pblb.stm32 = $(STM32MP1_OPTS) + +image-$(CONFIG_MACH_SEEED_ODYSSEY) += barebox-stm32mp157c-seeed-odyssey.img + +******************** +Porting to a new SoC +******************** + +So, barebox supports the SoC's family, but not this particular SoC. +For example, the new fancy network controller is lacking support. + +.. note:: + If your new SoC requires early boot drivers, like e.g. memory + controller setup. Refer to the next section. + +Often drivers can be ported from other projects. Candidates are +the Linux kernel, the bootloader maintained by the vendor or other +projects like Das U-Boot, Zephyr or EDK. + +Porting from Linux is often straight-forward, because barebox +imports many facilities from Linux. A key difference is that +barebox does not utilize interrupts, so kernel code employing them +needs to be modified into polling for status change instead. +In this case, porting from U-Boot may be easier if a driver already +exists. Usually, ported drivers will be a mixture of both if they're +not written from scratch. + +Drivers should probe from device tree and use the same bindings +like the Linux kernel. If there's no upstream binding, the barebox +binding should be documented and prefixed with ``barebox,``. + +Considerations when writing Linux drivers also apply to barebox: + + * Avoid use of ``#ifdef HARDWARE``. Multi-image code should detect at + runtime what hardware it is, preferably through the device tree + + * Don't use ``__weak`` symbols for ad-hoc plugging in of code. They + make code harder to reason about and clash with multi-image. + + * Write drivers so they can be instantiated more than once + + * Modularize. Describe inter-driver dependency in the device tree + +Miscellaneous Linux porting advice: + + * Branches dependent on ``system_state``: Take the ``SYSTEM_BOOTING`` branch + * ``usleep`` and co.: use ``[mud]elay`` + * ``jiffies``: use ``get_time_ns()`` + * ``time_before``: use ``!is_timeout()`` + * ``clk_prepare``: is for the non-atomic code preparing for clk enablement. Merge it into ``clk_enable`` + +*************************** +Porting to a new SoC family +*************************** + +Extending support to a new SoC family can involve a number of things: + +New header format +================= + +Your loader may require a specific header or format. If the header is meant +to be executable, it should be written in assembly. +If the C compiler for that platform supports ``__attribute__((naked))``, it +can be written in inline assembly inside such a naked function. See for +example ``__barebox_arm_head`` for ARM32 or ``__barebox_riscv_header`` for RISC-V. + +For platforms, without naked function support, inline assembly may not be used +and the entry point should be written in a dedicated assembly file. +This is the case with ARM64, see for example ``__barebox_arm64_head`` and the +``ENTRY_PROC`` macro. + +Another way, which is often used for non-executable headers with extra +meta-information like a checksum, is adding a new tool to ``scripts/`` +and have it run as part the image build process. ``images/`` contains +various examples. + +Memory controller setup +======================= + +If you've an external DRAM controller, you will need to configure it. +This may involve enabling clocks and PLLs. This should all happen +in the PBL entry point. + +Chainloading +============ + +If the whole barebox image couldn't be loaded initially due to size +constraints, the prebootloader must arrange for chainloading the full +barebox image. + +One good way to go about it is to check whether the program counter +is in DRAM or SRAM. If in DRAM, we can assume that the image was loaded +in full and we can just go into the common PBL entry and extract barebox +proper. If in SRAM, we'll need to load the remainder from the boot medium. + +This loading requires the PBL to have a driver for the boot medium as +well as its prerequisites like clocks, resets or pin multiplexers. + +Examples for this are the i.MX xload functions. Some BootROMs boot from +a FAT file system. There is vfat support in the PBL. Refer to the sama5d2 +board support for an example. + +Core drivers +============ + +barebox contains some stop-gap alternatives that can be used before +dedicated drivers are available: + + * Clocksource: barebox often needs to delay for a specific time. + ``CLOCKSOURCE_DUMMY_RATE`` can be used as a stop-gap solution + during initial bring up. + + * Console driver: serial output is very useful for debugging. Stop-gap + solution can be ``DEBUG_LL`` console + +***************************** +Porting to a new architecture +***************************** + +Makefile +======== + +``arch/$ARCH/Makefile`` defines how barebox is built for the +architecture. Among other things, it configures which compiler +and linker flags to use and which directories Kbuild should +descend into. + +Kconfig +======= + +``arch/$ARCH/Kconfig`` defines the architecture's main Kconfig symbol, +the supported subarchitectures as well as other architecture specific +options. New architectures should select ``OFTREE`` and ``OFDEVICE`` +as well as ``HAVE_PBL_IMAGE`` and ``HAVE_PBL_MULTI_IMAGES``. + +Header files +============ + +Your architecture needs to implement following headers: + + - ``<asm/bitops.h>`` + Defines optimized bit operations if available + - ``<asm/bitsperlong.h>`` + ``sizeof(long)`` Should be the size of your pointer + - ``<asm/byteorder.h>`` + If the compiler defines a macro to indicate endianness, + use it here. + - ``<asm/elf.h>`` + If using ELF relocation entries + - ``<asm/dma.h>`` + Only if ``HAS_DMA`` is selected by the architecture. + - ``<asm/io.h>`` + Defines I/O memory and port accessors + - ``<asm/mmu.h>`` + - ``<asm/string.h>`` + - ``<asm/swab.h>`` + - ``<asm/types.h>`` + - ``<asm/unaligned.h>`` + Defines accessors for unaligned access + - ``<asm/setjmp.h>`` + Must define ``setjmp``, ``longjmp`` and ``initjmp``. + ``setjmp`` and ``longjmp`` can be taken out of libc. As barebox + does no floating point operations, saving/restoring these + registers can be dropped. ``initjmp`` is like ``setjmp``, but + only needs to store 2 values in the ``jmpbuf``: + new stack top and address ``longjmp`` should branch to + +Most of these headers can be implemented by referring to the +respective ``<asm-generic/*.h>`` versions. + +Relocation +========== + +Because there might be no single memory region that works for all +images in a multi-image build, barebox needs to be relocatable. +This can be done by implementing three functions: + + - ``get_runtime_offset()``: This function should return the + difference between the link and load address. One easy way + to implement this is to force the link address to ``0`` and to + determine the load address of the barebox ``_text`` section. + + - ``relocate_to_current_adr()``: This function walks through + the relocation entries and fixes them up by the runtime + offset. After this is done ``get_runtime_offset()`` should + return `0` as ``_text`` should also be fixed up by it. + + - ``relocate_to_adr()``: This function copies the running barebox + to a new location in RAM, then does ``relocate_to_current_adr()`` + and resumes execution at the new location. This can be omitted + if barebox won't initially execute out of ROM. + + - ``relocate_to_adr_full()``: This function does what + ``relocate_to_adr()`` does and in addition moves the piggy data + (the usually compressed barebox appended to the prebootloader). + +Of course, for these functions to work. The linker script needs +to ensure that the ELF relocation records are included in the +final image and define start and end markers so code can iterate +over them. + +To ease debugging, even when relocation has no yet happened, +barebox supports ``DEBUG_LL``, which acts similarly to the +PBL console, but does not require relocation. This is incompatible +with multi-image, so this should only be considered while debugging. + +Linker scripts +============== + +You'll need two linker scripts, one for barebox proper and the +other for the PBL. Refer to the ARM and/or RISC-V linker scripts +for an example. + +Generic DT image +================ + +It's a good idea to have the architecture generate an image that +looks like and can be booted just like a Linux kernel. This allows +easy testing with QEMU or booting from barebox or other bootloaders. +Refer to ``BOARD_GENERIC_DT`` for examples. If not possible, the +(sub-)architecture making use of the image should +``register_image_handler`` that can chain-boot the format from +a running barebox. This allows for quick debugging iterations. diff --git a/Documentation/devel/project-ideas.rst b/Documentation/devel/project-ideas.rst new file mode 100644 index 0000000000..4127b2556b --- /dev/null +++ b/Documentation/devel/project-ideas.rst @@ -0,0 +1,200 @@ +##################### +barebox Project Ideas +##################### + +This section collects ideas to improve barebox and should serve as a pool +of ideas for people who want to enter the field of firmware development +but need some guidance what to work on. + +These tasks can be adopted as part of programs like Google Summer of Code +or by motivated individuals outside such programs. + +If you find a project interesting and would like to work on it, reach out +to the :ref:`mailing list <feedback>` and we can together +try to figure out whether you are a good match for the project. + +For GSoC, following barebox developers are mentoring: + + - Ahmad Fatoum (IRC: ``a3f``) + - Sascha Hauer (IRC: ``_sha_``) + - Rouven Czerwinski (IRC: ``Emantor``) + +This list can be edited and extended by sending patches to the mailing list. +Other interesting ideas: Support for new file systems (EROFS, extfat, btrfs), +improvements for barebox-efi (e.g. as a coreboot payload), ... etc. + +Ideas listed below should contain a title, description, expected outcomes, +skills (and HW if any) required and a difficulty rating. +Projects are meant to be about 175 hours of effort, unless otherwise noted. + +Address static analyzer feedback for barebox +============================================ + +Skills: C. Difficulty: Lowest + +barebox is automatically tested using Synopsys' free "Coverity Scan" service. +The static analyzer has so far identified 191 possible defects at +https://scan.coverity.com/projects/barebox + +There is a number of false positives there, but it already helped us +find actual regressions, e.g. 610720857348 ("fs: ext4: fix bogus behavior +on failure to read ext4 block"). + +To make this service more useful, the project would involve categorizing +reported issues and handling them as appropriate: Mark them as not applicable +if false positive or provide patches to fix real issues. + +Expected outcome is that barebox is coverity-clean. + +This project does not require dedicated hardware. QEMU or barebox built +to run under Linux (sandbox) may be used. + +Update barebox networking stack for IPv6 support +================================================ + +Skills: C, Networking. Difficulty: Medium + +The barebox network stack is mainly used for TFTP and NFSv3 (over UDP) boot. +Most embedded systems barebox runs on aren't deployed to IPv6 networks yet, +so it's the right time now to future-proof and learn more about networking +internals. One major complication with IPv6 support is neighbor discovery +protocols that require networking to be possible "in the background". +barebox' recent improvements of resource sharing and cooperative scheduling +makes it possible to integrate an IPv6 stack, e.g. lwIP. + +There are also community patches to integrate a TCP stack into barebox. +These can be evaluated as time allows. + +Expected outcome is that barebox can TFTP/NFS boot over IPv6. + +This project does not require dedicated hardware. QEMU or barebox built +to run under Linux (sandbox) may be used. + +Improving barebox test coverage +=============================== + +Skills: C. Difficulty: Lowest + +barebox is normally tested end-to-end as part of a deployed system. +More selftests/emulated tests would reduce the round trip time for testing +and thus enable more widely tested patches. A framework has been recently +merged to enable this: + + * Selftest similar to the kernel can be registered and run. These + directly interface with C-Code. + * Labgrid tests: These boot barebox in a virtual machine or on real + hardware and use the shell to test barebox behaviors. + +This project will focus on improving the testing coverage by writing more +tests for barebox functionality and by fuzzing the parsers available in +barebox, with special consideration to the FIT parser, which is used in +secure booting setups. + +Expected outcome is a richer test suite for barebox and an automated +setup for fuzzing security-critical parsers. + +This project does not require dedicated hardware. QEMU or barebox built +to run under Linux (sandbox) may be used. + +Porting barebox to new hardware +=============================== + +Skills: C, low-level affinity. Difficulty: Medium + +While Linux and Linux userspace can be quite generic with respect to the +hardware it runs on, the bucket needs to stop somewhere: barebox needs +detailed knowledge of the hardware to initialize it and to pass this +along information to Linux. In this project, familiarity with barebox +and a new unsupported SoC will be established with the goal of porting +barebox to run on it. Prospective developers can suggest suitable +hardware (boards/SoCs) they are interested in. Preference is for +hardware, which is generally available and has more open documentation. + +The goal is to have enough support to run barebox on the board, set up +RAM and load a kernel from non-volatile storage and boot it. + +If time allows (because most drivers are already available in barebox), +new drivers can be ported to enable not only running Linux on the board, +but bareDOOM as well. + +Expected outcome is upstreamed barebox drivers and board support to +enable running on previously unsupported hardware. + +This project requires embedded hardware with preferably an ARM SoC, as +these have the widest barebox support, but other architectures are ok +as well. + +Improve barebox RISC-V support +============================== + +Skills: C, RISC-V interest, low-level affinity. Difficulty: Medium + +barebox supports a number of both soft and hardRISC-V targets, +e.g.: BeagleV, HiFive, LiteX and the QEMU/TinyEMU Virt machine. + +Unlike e.g. ARM and MIPS, RISC-V support is still in its formative +stage, so much opportunity in implementing the gritty details: + + - Physical memory protection in M-Mode to trap access violations + - MMU support in S-Mode to trap access violations + - Improve barebox support for multiple harts (hardware threads) + +Expected outcome is better RISC-V support: Access violations are +trapped in both S- and M-Mode. Virtual memory is implemented and +Linux can be booted on multiple harts. + +This project does not require dedicated hardware. QEMU can be used. + +Improve barebox I/O performance +=============================== + +Skills: C, low-level affinity. Difficulty: Medium + +On a normal modern system, booting may involve mounting and traversing +a file system, which employs caching for directory entries and sits +on top of a block device which caches blocks previously read from the +hardware driver, often by means of DMA. There are a number of improvements +possible to increase throughput of barebox I/O: + + - More efficient erase: Communication protocols like Android Fastboot + encode large blocks of zeros specially. MMCs with erase-to-zero + capability could perform such erases in the background instead + of having to write big chunks of zeros. + - Block layer block sizes: There is a fixed block size used for + caching, which is meant to be a good compromise for read + and write performance. This may not be optimal for all devices + and can be revisited. + +Expected outcome is faster read/write/erasure of MMC block devices. + +This project requires embedded hardware with SD/eMMC that is supported +by a barebox media card interface (MCI) driver. + +Improve JSBarebox, the barebox web demo +======================================= + +Skills: C (Basics), Javascript/Web-assembly, Browser-Profiling. Difficulty: Medium + +While Linux and Linux userspace can be quite generic with respect to the +hardware it runs on, the bucket needs to stop somewhere: barebox needs +detailed knowledge of the hardware to initialize it and to pass this +along information to Linux. JSBarebox removes the hurdle of porting +barebox to a new board, for new users who are only interested in +trying it out: The browser runs Tinyemu, a virtual machine in which +barebox executes as if on real hardware and the user can manipulate the +(virtual) hardware from the barebox shell and learn about barebox +conveniences: barebox.org/demo/ + +The project is about streamlining this demo: CPU usage currently is +quite high and teaching barebox to idle the CPU (as we do on sandbox) +didn't help. This needs to be analyzed with the profiling tools +provided with modern browsers. The remainder of the project can then +focus on improving the tutorial inside the demo. e.g. by adding new +peripherals to the virtual machine. + +Expected outcome is snappier and less CPU-intensive barebox demo. +TinyEMU is extended, so the RISC-V machine is more like real +hardware and tutorial is extended to make use of the new pripherals. + +This project does not require dedicated hardware. The development +machine need only support a recent browser. diff --git a/Documentation/devicetree/bindings/barebox/aliases.rst b/Documentation/devicetree/bindings/barebox/aliases.rst new file mode 100644 index 0000000000..2848a88f15 --- /dev/null +++ b/Documentation/devicetree/bindings/barebox/aliases.rst @@ -0,0 +1,42 @@ +barebox DT aliases +================== + +barebox can use the properties in the ``/aliases`` node to arrive +at deterministic names for devices, e.g.: + +.. code-block:: none + + / { + aliases { + mmc0 = &sdhci; + wdog0 = &iwdg; + }; + }; + +will assign the MMC device created from probing the node at ``&sdhci`` +the name ``/dev/mmc0``. Similarly, the watchdog device created from +probing the node at ``&iwdg`` will be named ``wdog0``. + +By default, barebox will assume the aliases in the DT to align with +the bootsource communicated by the firmware. If this is not the case, +a device tree override is possible via a +``/chosen/barebox,bootsource-${bootsource}${bootsource_instance}`` +property: + +.. code-block:: none + + / { + aliases { + mmc0 = &sdmmc0; + mmc1 = &sdhci; + }; + + chosen { + barebox,bootsource-mmc0 = &sdhci; + barebox,bootsource-mmc1 = &sdmmc0; + }; + }; + +This will ensure that when booting from MMC, ``/dev/mmc${bootsource_instance}`` +will point at the correct boot device, despite bootrom and board DT alias +order being different. diff --git a/Documentation/devicetree/bindings/barebox/barebox,environment.rst b/Documentation/devicetree/bindings/barebox/barebox,environment.rst index 918efd15f5..67d1173b2f 100644 --- a/Documentation/devicetree/bindings/barebox/barebox,environment.rst +++ b/Documentation/devicetree/bindings/barebox/barebox,environment.rst @@ -9,6 +9,7 @@ Required properties: * ``device-path``: path to the device environment is on Optional properties: + * ``file-path``: path to a file in the device named by device-path The device-path is a multistring property. The first string should contain @@ -22,6 +23,9 @@ the path to the environment. Supported values for <type>: be the label for MTD partitions, the number for DOS partitions (beginning with 0) or the name for GPT partitions. +If the *environment* is located in a GPT partition, use +``6C3737F2-07F8-45D1-AD45-15D260AAB24D`` as partition type GUID. + The file-path is the name of a file located in a FAT filesystem on the device named in device-path. This filesystem will be mounted and the environment loaded from the file's location in the directory tree. diff --git a/Documentation/devicetree/bindings/barebox/virtual-reg.rst b/Documentation/devicetree/bindings/barebox/virtual-reg.rst new file mode 100644 index 0000000000..7d576d0cef --- /dev/null +++ b/Documentation/devicetree/bindings/barebox/virtual-reg.rst @@ -0,0 +1,29 @@ +virtual-reg property +==================== + +The ``virtual-reg`` property provides a hint on the 32-bit virtual +address mapping the first physical base address in the ``reg`` property. +This is meant to allow the OS to use the boot firmware's virtual memory +mapping to access device resources early in the kernel boot process. + +When barebox is compiled with ``CONFIG_MMU`` support and the +implementation supports remapping, devices with ``virtual_reg`` will have +all their resources remapped at the physical/virtual address offset calculated +by subtracting ``virtual-reg`` from the first address in ``reg``. + +This is normally used to map I/O memory away from the zero page, so it +can be used again to trap null pointer dereferences, while allowing +full access to the device memory:: + +.. code-block:: none + + &{/soc} { + #address-cells = <1>; + #size-cells = <1>; + + flash@0 { + reg = <0 0x10000>; + virtual-reg = <0x1000>; + /* => memory region remapped from [0x1000, 0x11000] to [0x0000, 0x10000] */ + }; + }; diff --git a/Documentation/devicetree/bindings/clocks/xlnx,ps7-clkc.rst b/Documentation/devicetree/bindings/clocks/xlnx,ps7-clkc.rst new file mode 100644 index 0000000000..523b0cf56e --- /dev/null +++ b/Documentation/devicetree/bindings/clocks/xlnx,ps7-clkc.rst @@ -0,0 +1,10 @@ +Xilinx PS7 clkc +=============== + +In addition to the upstream bindings, following properties are understood: + +Optional properties: + +- ``ps-clock-frequency`` : Overrides the ps clock frequency set by the driver. + Per default the clock is set to 33.3MHz. When this property is set, the frequency + is overwritten by the devicetree property. diff --git a/Documentation/devicetree/bindings/firmware/altr,passive-serial.txt b/Documentation/devicetree/bindings/firmware/altr,passive-serial.rst index eec12fbace..cbddd700ce 100644 --- a/Documentation/devicetree/bindings/firmware/altr,passive-serial.txt +++ b/Documentation/devicetree/bindings/firmware/altr,passive-serial.rst @@ -1,20 +1,23 @@ Altera FPGAs in passive serial mode ------------------------------------ +=================================== This binding defines the control interface to Altera FPGAs in passive serial mode. This is used to upload the firmware and to start the FPGA. Required properties: -- compatible: shall be "altr,fpga-passive-serial" or - "altr,fpga-arria10-passive-serial" for Arria 10 -- reg: SPI chip select -- nstat-gpios: Specify GPIO for controlling the nstat pin -- confd-gpios: Specify GPIO for controlling the confd pin -- nconfig-gpios: Specify GPIO for controlling the nconfig pin + +- ``compatible``: shall be ``"altr,fpga-passive-serial"`` or + ``"altr,fpga-arria10-passive-serial"`` for Arria 10 +- ``reg``: SPI chip select +- ``nstat-gpios``: Specify GPIO for controlling the nstat pin +- ``confd-gpios``: Specify GPIO for controlling the confd pin +- ``nconfig-gpios``: Specify GPIO for controlling the nconfig pin Example: +.. code-block:: none + fpga@0 { compatible = "altr,fpga-passive-serial"; nstat-gpios = <&gpio4 18 0>; diff --git a/Documentation/devicetree/bindings/firmware/altr,socfpga-fpga-mgr.txt b/Documentation/devicetree/bindings/firmware/altr,socfpga-fpga-mgr.rst index 70ec4abf25..478e8e6fc4 100644 --- a/Documentation/devicetree/bindings/firmware/altr,socfpga-fpga-mgr.txt +++ b/Documentation/devicetree/bindings/firmware/altr,socfpga-fpga-mgr.rst @@ -1,17 +1,21 @@ Altera SOCFPGA FPGA Manager ---------------------------- +=========================== This binding defines the FPGA Manager on Altera SOCFPGAs. This is used to upload the firmware to the FPGA part of the SoC. Required properties: -- compatible: shall be "altr,socfpga-fpga-mgr" -- reg: Must contain 2 register ranges: - 1. The control address space of the FPGA manager. - 2. The configuration data address space where the firmware data is written to. + +- ``compatible``: shall be ``"altr,socfpga-fpga-mgr"`` +- ``reg``: Must contain 2 register ranges: + + 1. The control address space of the FPGA manager. + 2. The configuration data address space where the firmware data is written to. Example: +.. code-block:: none + fpgamgr@ff706000 { compatible = "altr,socfpga-fpga-mgr"; reg = <0xff706000 0x1000>, diff --git a/Documentation/devicetree/bindings/leds/common.rst b/Documentation/devicetree/bindings/leds/common.rst index 911a55f4f6..8bf41f0d64 100644 --- a/Documentation/devicetree/bindings/leds/common.rst +++ b/Documentation/devicetree/bindings/leds/common.rst @@ -9,9 +9,10 @@ Common leds properties * ``net`` - LED indicates network activity (tx and rx) * ``net-rx`` - LED indicates network activity (rx only) * ``net-tx`` - LED indicates network activity (tx only) + * ``default-on`` - LED is switched on by default * ``label``: The label for this LED. If omitted, the label is taken from the node name (excluding the unit address). * ``panic-indicator`` - This property specifies that the LED should be used as a - panic indicator. + panic indicator. diff --git a/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.rst b/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.rst index 202bb3aa07..1c45267b1b 100644 --- a/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.rst +++ b/Documentation/devicetree/bindings/misc/fsl,imx-ocotp.rst @@ -6,13 +6,14 @@ Required properties: * ``compatible``: ``fsl,imx6q-ocotp`` * ``reg``: physical register base and size -Optional properties: +Deprecated properties: * ``barebox,provide-mac-address``: Provide MAC addresses for Ethernet devices. This can be multiple entries in the form <&phandle regofs> to assign a MAC - address to an Ethernet device. + address to an Ethernet device. This has been deprecated in favor or the upstream + nvmem cell binding. -Example: +Legacy example: .. code-block:: none @@ -21,3 +22,21 @@ Example: reg = <0x021bc000 0x4000>; barebox,provide-mac-address = <&fec 0x620>; }; + +Upstream alternative: + +.. code-block:: none + + &ocotp1 { + #address-cells = <1>; + #size-cells = <1>; + + fec_mac_addr: mac-addr@88 { + reg = <0x88 6>; + }; + }; + + &fec { + nvmem-cells = <&fec_mac_addr>; + nvmem-cell-names = "mac-address"; + }; diff --git a/Documentation/devicetree/bindings/mtd/partition.rst b/Documentation/devicetree/bindings/mtd/partition.rst new file mode 100644 index 0000000000..0ba117dffc --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partition.rst @@ -0,0 +1,53 @@ +.. _devicetree_binding_mtd_partition: + +Representing flash partitions in devicetree +=========================================== + +In addition to the upstream binding, another property is added: + +Optional properties: + +* ``partuuid``: The global partition UUID for this partition. + For GPT partitions, the partuuid is the 16-byte GPT Partition UUID (e.g. + ``de6f4f5c-c055-4374-09f7-8c6821dfb60e``). + For MBR partitions, the partuuid is the 4-byte disk identifier + followed by a dash and the partition number (starting with 1, e.g. + ``c9178f9d-01``). + + The partuuid is case-insensitive. + +Additionally, barebox also supports partitioning the eMMC boot partitions if +the partition table node is named appropriately: + +* ``partitions`` : user partition +* ``boot0-partitions`` : boot0 partition +* ``boot1-partitions`` : boot1 partition + +Examples: + +.. code-block:: none + + / { + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + state_part: state { + partuuid = "16367da7-c518-499f-9aad-e1f366692365"; + }; + }; + }; + + emmc@1 { + boot0-partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + barebox@0 { + label = "barebox"; + reg = <0x0 0x300000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/partition.txt b/Documentation/devicetree/bindings/mtd/partition.txt deleted file mode 100644 index 4288a82437..0000000000 --- a/Documentation/devicetree/bindings/mtd/partition.txt +++ /dev/null @@ -1,39 +0,0 @@ -Representing flash partitions in devicetree - -In addition to the upstream binding, another property is added: - -Optional properties: -- partuuid : The partition UUID for this partition. - -Additionally, barebox also supports partitioning the eMMC boot partitions if -the partition table node is named appropriately: -- partitions : user partition -- boot0-partitions : boot0 partition -- boot1-partitions : boot1 partition - -Examples: - -flash@0 { - partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; - - state_part: state { - partuuid = "16367da7-c518-499f-9aad-e1f366692365"; - }; - }; -}; - -emmc@1 { - boot0-partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; - - barebox@0 { - label = "barebox"; - reg = <0x0 0x300000>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/power/restart.rst b/Documentation/devicetree/bindings/power/restart.rst new file mode 100644 index 0000000000..9a84c4f224 --- /dev/null +++ b/Documentation/devicetree/bindings/power/restart.rst @@ -0,0 +1,15 @@ +System Restart Controllers +========================== + +In addition to upstream bindings, following properties are understood: + +Optional properties: + +- ``restart-priority`` : Overrides the priority set by the driver. Normally, + the device with the biggest reach should reset the system. + See :ref:`system_reset` for more information. + +- ``barebox,restart-warm-bootrom`` : Restart will not cause loss to non-volatile + registers sampled by the bootrom at startup. This is a necessary precondition + for working :ref:`reboot_mode` communication between barebox and the SoC's + BootROM. diff --git a/Documentation/devicetree/bindings/regulator/regulator.rst b/Documentation/devicetree/bindings/regulator/regulator.rst new file mode 100644 index 0000000000..754c474328 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/regulator.rst @@ -0,0 +1,36 @@ +Voltage/Current Regulators +========================== + +In addition to the upstream bindings, another property is added: + +Optional properties: + +- ``barebox,allow-dummy-supply`` : A property to allow usage of dummy power + regulator. This can be added to regulator nodes, whose drivers are not yet + supported. It will rely on regulator reset defaults and use of dummy regulator + instead. + +Examples: + +.. code-block:: none + + pmic@58 { + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_pmic>; + compatible = "dlg,da9063"; + reg = <0x58>; + + regulators { + barebox,allow-dummy-supply; + + vddcore_reg: bcore1 { + regulator-min-microvolt = <730000>; + regulator-max-microvolt = <1380000>; + }; + + vddsoc_reg: bcore2 { + regulator-min-microvolt = <730000>; + regulator-max-microvolt = <1380000>; + }; + } + } diff --git a/Documentation/devicetree/bindings/watchdog/watchdog.rst b/Documentation/devicetree/bindings/watchdog/watchdog.rst new file mode 100644 index 0000000000..753dc7e35f --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/watchdog.rst @@ -0,0 +1,10 @@ +Watchdogs +========= + +In addition to the upstream bindings, following properties are understood: + +Optional properties: + +- ``watchdog-priority`` : Overrides the priority set by the driver. Normally, + the watchdog device with the biggest reach should reset the system. + See :ref:`system_reset` for more information. diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 908652642b..f85ce6608d 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -1,11 +1,15 @@ +.. _bareboxdt: + Barebox devicetree handling and bindings ======================================== The preferred way of adding board support to barebox is to have devices on non-enumerable buses probed from device tree. -barebox imports the Linux OpenFirmware ``of_*``-API functions for device tree -parsing, which makes porting the device tree specific bits from device drivers -very straight forward. +barebox provide both the Linux OpenFirmware ``of_*`` and the libfdt ``fdt_`` APIs +for device tree parsing. The former makes porting the device tree specific +bits from Linux device drivers very straight forward, while the latter can be +used for very early (PBL) handling of flattened device trees, should this be +necessary. Additionally, barebox has support for programmatically fixing up device trees it passes to the kernel, either directly via ``of_register_fixup`` or via device @@ -31,6 +35,82 @@ device tree under ``dts/src/$ARCH`` with ``#include "$ARCH/board.dts"`` and then extends it with barebox-specifics like :ref:`barebox,state`, environment or boot-time device configuration. +Device Tree probing largely happens via compatible properties with no special +meaning to the node names themselves. It's thus paramount that any device tree +nodes extended in the barebox device tree are referenced by label (e.g. +``<&phandle>``, not by path, to avoid run-time breakage like this:: + + # Upstream dts/src/$ARCH/board.dts + / { + leds { + led-red { /* formerly named red when the barebox DTS was written */ + /* ... */ + }; + }; + }; + + # barebox arch/$ARCH/dts/board.dts + #include <$ARCH/board.dts> + / { + leds { + red { + barebox,default-trigger = "heartbeat"; + }; + }; + }; + +In the previous example, a device tree sync with upstream resulted in a regression +as the former override became a new node with a single property without effect. + +The preferred way around this is to use labels directly:: + + # Upstream dts/src/$ARCH/board.dts + / { + leds { + status_led: red { }; + }; + }; + + # barebox arch/$ARCH/dts/board.dts + #include <$ARCH/board.dts> + + &status_led { + barebox,default-trigger = "heartbeat"; + }; + +If there's no label defined upstream for the node, but for a parent, +a new label can be constructed from that label and a relative path:: + + # Upstream dts/src/$ARCH/board.dts + / { + led_controller: leds { + red { }; + }; + }; + + # barebox arch/$ARCH/dts/board.dts + #include <$ARCH/board.dts> + + &{led_controller/red} { + barebox,default-trigger = "heartbeat"; + }; + +As last resort, the full path shall be used:: + + &{/leds/red} { + barebox,default-trigger = "heartbeat"; + }; + +Any of these three approaches would lead to a compile error should the +``/leds/red`` path be renamed or removed. This also applies to uses +of ``/delete-node/``. + +Only exception to this rule are well-known node names that are specified by +the `specification`_ to be parsed by name. These are: ``chosen``, ``aliases`` +and ``cpus``, but **not** ``memory``. + +.. _specification: https://www.devicetree.org/specifications/ + Device Tree Compiler -------------------- @@ -63,7 +143,33 @@ Contents: :maxdepth: 1 bindings/barebox/* + bindings/firmware/* bindings/leds/* bindings/misc/* bindings/mtd/* + bindings/power/* + bindings/regulator/* bindings/rtc/* + bindings/watchdog/* + +Automatic Boot Argument Fixups to the Devicetree +------------------------------------------------ + +barebox automatically fixes up some boot and system information in the device tree. + +In the device tree root, barebox fixes up + + * serial-number (if available) + * machine compatible (if overridden) + +In the ``chosen``-node, barebox fixes up + + * barebox-version + * reset-source + * reset-source-instance (if available) + * reset-source-device (node-path, only if available) + * bootsource + * boot-hartid (only on RISC-V) + +These values can be read from the booted linux system in ``/proc/device-tree/`` +or ``/sys/firmware/devicetree/base``. diff --git a/Documentation/filesystems/smhfs.rst b/Documentation/filesystems/smhfs.rst index 8f8a0ec6b7..f70ca6015f 100644 --- a/Documentation/filesystems/smhfs.rst +++ b/Documentation/filesystems/smhfs.rst @@ -8,12 +8,12 @@ File I/O over ARM semihosting support Target Side Setup ----------------- -barebox can communicate with debug programms attached via SWD/JTAG by +barebox can communicate with debug programs attached via SWD/JTAG by means of ARM semihosting protocol. -Not all of the I/O primitives neccessary to implement a full +Not all of the I/O primitives necessary to implement a full filesystem are exposed in ARM semihosting API and because of that some -aspects of filesystem funcionality are missing. Implementation does +aspects of filesystem functionality are missing. Implementation does not have support for listing directories. This means a :ref:`command_ls` to a SMHFS-mounted path will show an empty directory. Nevertheless, the files are there. @@ -29,7 +29,7 @@ Host Side Setup --------------- FIXME: Currently OpenOCD does not work correctly if Barebox is built -with MMU enabled, so before using this featrue, please make sure that +with MMU enabled, so before using this feature, please make sure that MMU is disabled in your particular configuration To make semihosting work host machine connected to the target via diff --git a/Documentation/filesystems/tftp.rst b/Documentation/filesystems/tftp.rst index a292765e25..5a2910adbf 100644 --- a/Documentation/filesystems/tftp.rst +++ b/Documentation/filesystems/tftp.rst @@ -20,3 +20,43 @@ Example: In addition to the TFTP filesystem implementation, barebox does also have a :ref:`tftp command <command_tftp>`. + +RFC 7440 "windowsize" support +----------------------------- + +barebox supports the tftp windowsize option for downloading files. It +is not implemented for uploads. + +Generally, this option greatly improves the download speed (factors +4-30 are not uncommon). But choosing a too large windowsize can have +the opposite effect. Performance depends on: + + - the network infrastructure: when the tftp server sends files with + 1Gb/s but there are components in the network (switches or the + target nic) which support only 100 Mb/s, packets will be dropped. + + The lower the internal buffers of the bottleneck components, the + lower the optimal window size. + + In practice (iMX8MP on a Netgear GS108Ev3 with a port configured to + 100 Mb/s) it had to be reduced to + + .. code-block:: console + + global tftp.windowsize=26 + + for example. + + - the target network driver: datagrams from server will arive faster + than they can be processed and must be buffered internally. For + example, the `fec-imx` driver reserves place for + + .. code-block:: c + + #define FEC_RBD_NUM 64 + + packets before they are dropped + + - partially the workload: copying downloaded files to ram will be + faster than burning them into flash. Latter can consume internal + buffers quicker so that windowsize might be reduced diff --git a/Documentation/gen_commands.py b/Documentation/gen_commands.py index a55b1acd82..7c62a030dc 100755 --- a/Documentation/gen_commands.py +++ b/Documentation/gen_commands.py @@ -1,6 +1,4 @@ -#!/usr/bin/env python - -from __future__ import print_function +#!/usr/bin/env python3 import errno import os diff --git a/Documentation/glossary.rst b/Documentation/glossary.rst index 106dce98a9..88d356fbab 100644 --- a/Documentation/glossary.rst +++ b/Documentation/glossary.rst @@ -5,17 +5,17 @@ Glossary .. glossary:: :sorted: - FDT - Flattened Device Tree + DTS + Device Tree Source DTB - Device Tree Blob (or Binary) + Device Tree Blob (or Binary). The result of compiling a DTS. - DTS - Device Tree Source + FDT + Flattened Device Tree. A DTB loaded into memory. PBL - Pre BootLoader image + Pre BootLoader image. The board-specific entry point attached in front of multi-image barebox binaries. ESP EFI System Partition diff --git a/Documentation/index.rst b/Documentation/index.rst index b7dae2396b..a3e019e9f0 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -19,6 +19,8 @@ Contents: boards glossary devicetree/* + devel/devel.rst + talks * :ref:`search` * :ref:`genindex` diff --git a/Documentation/talks.rst b/Documentation/talks.rst new file mode 100644 index 0000000000..5206d649a2 --- /dev/null +++ b/Documentation/talks.rst @@ -0,0 +1,130 @@ +Talks and Lectures +================== + +This is a collection of talks held about barebox use and development +at different technical conferences. The most recent overview talk +is from 2020: + +Beyond 'Just' Booting: Barebox Bells and Whistles +------------------------------------------------- + +Ahmad Fatoum, Embedded Linux Conference - Europe 2020 +`[slides] <https://elinux.org/images/9/9d/Barebox-bells-n-whistles.pdf>`__ +`[video] <https://www.youtube.com/watch?v=fru1n54s2W4>`__ + + Porting barebox to a new STM32MP1 board and a general discussion + of design choices like multi-image, VFS, POSIX/Linux API, + fail-safe updates, boot fall-back mechanisms, etc. + +Besides older overview talks, there's a number of talks held +about different aspects of barebox use. +These are listed here in reverse chronological order. + +DOOM portieren für Einsteiger - Heavy Metal auf Bare Metal (German) +------------------------------------------------------------------- + +Ahmad Fatoum, FrOSCon 2021 +`[slides] <https://programm.froscon.de/2021/system/event_attachments/attachments/000/000/622/original/heavy-metal-on-bare-metal.pdf>`__ +`[video] <https://media.ccc.de/v/froscon2021-2687-doom_portieren_fur_einsteiger>`__ + + "DOOM as a boot splash. How, why and how to get it on your nearest + home appliance". A (German) walkthrough on how to leverage barebox + APIs to run DOOM on any hardware supported by barebox. + +Initializing RISC-V: A Guided Tour for ARM Developers +----------------------------------------------------- + +Rouven Czerwinski & Ahmad Fatoum, Embedded Linux Conference 2021 +`[slides] <https://elinux.org/images/8/80/Initializing-riscv.pdf>`__ +`[video] <https://www.youtube.com/watch?v=70oYYuflFLs>`__ + + A guide through the RISC-V architecture and some of its ISA extensions + and a walkthrough of the barebox port to the Beagle-V Starlight. + +From Reset Vector to Kernel - Navigating the ARM Matryoshka +----------------------------------------------------------- + +Ahmad Fatoum, FOSDEM 2021 +`[slides & video] <https://archive.fosdem.org/2021/schedule/event/from_reset_vector_to_kernel/>`__ + + A walkthrough of NXP i.MX8M bootstrap. From Boot ROM through barebox to Linux. + +Booting your i.MX processor secure and implementing i.MX8 secure boot in barebox +-------------------------------------------------------------------------------- + +Rouven Czerwinski, `Stratum 0 Talk 2019 <https://stratum0.org/wiki/Vortr%C3%A4ge/Vorbei#2019>`__ +`[video] <https://www.youtube.com/watch?v=ZUGLEulZLWM>`__ + + A walkthrough of NXP i.MX8MQ high assurance boot with barebox. + +Porting Barebox to the Digi CC-MX6UL SBC Pro (German) +----------------------------------------------------- + +Rouven Czerwinski, `Stratum 0 Live-Hacking 2019 <https://stratum0.org/wiki/Vortr%C3%A4ge/Vorbei#2019>`__ +`[video] <https://www.youtube.com/watch?v=FIwF6GfmsWM>`__ + + Live-coding a barebox port to a new i.MX6UL board while + explaining the details (in German). + +Remote update adventures with RAUC, Yocto and Barebox +----------------------------------------------------- + +Patrick Boettcher, `Embedded Recipes 2019 <https://embedded-recipes.org/2019/remote-update-adventures-with-rauc-yocto-and-barebox/>`__ +`[video] <https://www.youtube.com/watch?v=hS3Fjf7fuHM>`__ + + Remote update and redundant boot of Embedded Linux devices + in the field with RAUC and barebox bootchooser. + +Verified Boot: From ROM to Userspace +------------------------------------ + +Marc Kleine-Budde, Embedded Linux Conference - Europe 2016 +`[slides] <https://elinux.org/images/f/f8/Verified_Boot.pdf>`__ +`[video] <https://www.youtube.com/watch?v=lkFKtCh2SaU>`__ + + Using FOSS components, including barebox, for a cryptographically + secured boot chain on NXP i.MX6 SoCs. + +Booting Linux Made Easy: A Barebox Update +----------------------------------------- + +Robert Schwebel, `FOSDEM 2014 <https://archive.fosdem.org/2014/schedule/event/_booting_linux_made_easy:_a_barebox_update/>`__ +`[video] <https://www.youtube.com/watch?v=p-mHAQaJQcM>`__ + + An overview talk on barebox use in embedded Linux systems. + +Barebox and Bootloader Specification +------------------------------------ + +Sascha Hauer, Embedded Linux Conference - Europe 2013 +`[slides] <https://elinux.org/images/9/90/Barebox-elce2013-bootloaderspec.pdf>`__ +`[video] <https://www.youtube.com/watch?v=Z8FcIGXox_Y>`__ + + The bootloader specification and its support in barebox. + +Barebox Bootloader +------------------ + +Sascha Hauer, Embedded Linux Conference - Europe 2012 +`[slides] <https://elinux.org/images/6/6b/PRE-20121108-1-Barebox.pdf>`__ +`[video] <https://www.youtube.com/watch?v=oY8BjCEt_p8>`__ + + An update on barebox development progress with a discussion of newly + implemented features in the preceding three years. + +Barebox: Booting Linux Fast and Fancy +------------------------------------- + +Robert Schwebel & Sascha Hauer, Embedded Linux Conference - Europe 2010 +`[slides] <https://elinux.org/images/8/89/ELCE-2010-Barebox-Booting-Linux-Fast-and-Fancy.pdf>`__ + + Boot time optimization while using barebox. + +U-Boot-v2 +--------- + +Sascha Hauer & Marc Kleine-Budde, Embedded Linux Conference 2009 +`[slides] <https://elinux.org/images/9/90/Hauer-U_BootV2.pdf>`__ + + Early barebox (still named U-Boot v2 back then) presentation on + the motivation for the fork and the niceties made possible by it. 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. |