diff options
Diffstat (limited to 'Documentation')
53 files changed, 1157 insertions, 310 deletions
diff --git a/Documentation/boards/aarch64-qemu-virt.rst b/Documentation/boards/aarch64-qemu-virt.rst index 42e7d00bfe..8bf590a7a8 100644 --- a/Documentation/boards/aarch64-qemu-virt.rst +++ b/Documentation/boards/aarch64-qemu-virt.rst @@ -1,8 +1,11 @@ Aarch64 Qemu virt ================= -Besides a number of physical ARM64 targets, barebox also supports a -``qemu-virt64`` board. +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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 f502979df6..961ef58d84 100644 --- a/Documentation/boards/at91.rst +++ b/Documentation/boards/at91.rst @@ -35,6 +35,8 @@ The resulting images will be placed under ``images/``: 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 diff --git a/Documentation/boards/bcm2835.rst b/Documentation/boards/bcm2835.rst index f6df3e9e80..f7ab723d63 100644 --- a/Documentation/boards/bcm2835.rst +++ b/Documentation/boards/bcm2835.rst @@ -4,29 +4,36 @@ Broadcom BCM283x Raspberry Pi ------------ -barebox supports has support for BCM283x-based Raspberry Pi single board -computers. Support is most extensive for BCM283[567]. For the newer BCM2711 -used in the Raspberry Pi 4, only basic support is currently available -(Serial Port, Pinctrl/GPIO, SD-Card). +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`_ (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, 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) - ``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 + - ``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``. - The ``images/barebox-raspberry-pi.img`` is expected to replace the other images - in the future. It contains the device trees of all supported (and enabled) variants + 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:: diff --git a/Documentation/boards/emulated.rst b/Documentation/boards/emulated.rst index 584883d6ef..a67533613e 100644 --- a/Documentation/boards/emulated.rst +++ b/Documentation/boards/emulated.rst @@ -56,20 +56,20 @@ The script can also be used with a precompiled barebox tree:: export KBUILD_OUTPUT=build # run a barebox image built outside tuxmake on an ARM virt machine - ARCH=arm ./test/emulate.pl virt@vexpress_defconfig --no-tuxmake + ARCH=arm ./test/emulate.pl virt@multi_v7_defconfig --no-tuxmake # run tests instead of starting emulator interactively - ARCH=arm ./test/emulate.pl virt@vexpress_defconfig --no-tuxmake --test + 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 virt64_defconfig + 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 virt64_defconfig -- -device ? + 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 4ce9d9808c..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 @@ -86,8 +86,8 @@ The images can also always be started as second stage on the target: BootROM Reboot mode codes (bmode) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For select SoCs, barebox supports communicating an alternative boot medium -that BootROM should select after a warm reset:: +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 @@ -105,12 +105,19 @@ that BootROM should select after a warm reset:: mode-serial = <0x10 0x40000000>; }; - barebox@FSL i.MX8MM EVK board:/ gpr.reboot_mode.next=serial reset -r imxwd-warm + barebox@FSL i.MX8MM EVK board:/ gpr.reboot_mode.next=serial reset -w -This will cause barebox to fall into serial download mode on an i.MX8MM. +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. -See the section on :ref:`Reboot modes<reboot_mode>` for more information. +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 ^^^^^^^^^^^^^^^^^^^ @@ -124,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). @@ -143,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 @@ -161,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 ~~~~~~~~~~~~~~~~~~~~ @@ -340,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 ------------------ @@ -373,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/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 index b920e22d33..597db57eaf 100644 --- a/Documentation/boards/imx/nxp-imx8mn-evk.rst +++ b/Documentation/boards/imx/nxp-imx8mn-evk.rst @@ -58,3 +58,39 @@ 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 index 1074992f2f..da26339864 100644 --- a/Documentation/boards/imx/nxp-imx8mp-evk.rst +++ b/Documentation/boards/imx/nxp-imx8mp-evk.rst @@ -47,7 +47,7 @@ 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}/imx8mp-bl31.bin + 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. @@ -66,3 +66,39 @@ 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/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/mips/max9331.rst b/Documentation/boards/mips/max9331.rst index f09dabc2da..f7529f9874 100644 --- a/Documentation/boards/mips/max9331.rst +++ b/Documentation/boards/mips/max9331.rst @@ -126,7 +126,7 @@ 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:: assembly +.. code-block:: asm lui ra, 0x9f02 jr ra diff --git a/Documentation/boards/riscv.rst b/Documentation/boards/riscv.rst index b7a3a95f0f..990bd16a64 100644 --- a/Documentation/boards/riscv.rst +++ b/Documentation/boards/riscv.rst @@ -6,10 +6,10 @@ QEMU Virt barebox supports both the qemu riscv32 and riscv64 ``-M virt`` boards:: - make ARCH=riscv virt64_defconfig + make ARCH=riscv rv64i_defconfig qemu-system-riscv64 -M virt -serial stdio -kernel build/images/barebox-dt-2nd.img -Replace ``64`` by ``32`` for 32-bit build. :ref:`virtio_sect` over MMIO is supported and +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 \ @@ -58,14 +58,14 @@ To activate add:: into the config file. -See https://barebox.org/jsbarebox/?graphic=1 for a live example. +See https://barebox.org/demo/?graphic=1 for a live example. BeagleV ------- barebox has second-stage support for the BeagleV Starlight:: - make ARCH=riscv starfive_defconfig + make ARCH=riscv rv64i_defconfig make Thie resulting ``./images/barebox-beaglev-starlight.img`` can be used as payload @@ -188,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/rockchip.rst b/Documentation/boards/rockchip.rst index d4f8a9c5a3..aa2febc8eb 100644 --- a/Documentation/boards/rockchip.rst +++ b/Documentation/boards/rockchip.rst @@ -60,6 +60,8 @@ Supported Boards - Rockchip RK3568 Bananapi R2 Pro - Pine64 Quartz64 Model A - Radxa ROCK3 Model A +- Radxa CM3 (RK3566) IO Board +- Protonic MECSBC The steps described in the following target the RK3568 and the RK3568 EVB but generally apply to both SoCs and all boards. @@ -73,9 +75,9 @@ The build process needs three binary files which have to be copied from the .. code-block:: sh - cp $RKBIN/bin/rk35/rk3568_bl31_v1.24.elf firmware/rk3568-bl31.bin - cp $RKBIN/bin/rk35/rk3568_bl32_v1.05.bin firmware/rk3568-op-tee.bin - cp $RKBIN/bin/rk35/rk3568_ddr_1560MHz_v1.08.bin arch/arm/boards/rockchip-rk3568-evb/sdram-init.bin + 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: 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/stm32mp.rst b/Documentation/boards/stm32mp.rst index 4cdd281a9e..813117a04f 100644 --- a/Documentation/boards/stm32mp.rst +++ b/Documentation/boards/stm32mp.rst @@ -164,9 +164,13 @@ 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 -137::ref:`stm32mp_fip`. Upstream TF-A doesn't support DFU for +: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 --------------------- diff --git a/Documentation/boards/zynqmp.rst b/Documentation/boards/zynqmp.rst index 98fcac017b..86078d496e 100644 --- a/Documentation/boards/zynqmp.rst +++ b/Documentation/boards/zynqmp.rst @@ -11,13 +11,13 @@ 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 ZCU104 reference board. Use it to build the +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-zcu104.img`` is **not** an image +.. 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 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/porting.rst b/Documentation/devel/porting.rst index 01ee26e0d6..e63de12590 100644 --- a/Documentation/devel/porting.rst +++ b/Documentation/devel/porting.rst @@ -113,6 +113,9 @@ 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[]; @@ -128,22 +131,24 @@ call the common PBL code with a memory region and your device tree blob:: Lets look at this line by line: - - ``ENTRY_FUNCTION_WITHSTACK(start_my_board, STACK_TOP, r0, r1, r2)`` +``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 ``STACK_TOP`` as the initial stack + 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[];`` +``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. Declare the start variable, so - you can pass along the address of the device tree. + ``__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();`` +``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 @@ -152,28 +157,34 @@ Lets look at this line by line: 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();`` +``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);`` +``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 function pointer that can be used - to output a single character. This can be used for the early PBL - console to output messages even before any drivers are initialized. + 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`` will compute a new stack top from the supplied memory - region and uncompress barebox proper and pass along its arguments. +``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 +``*_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 +``__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 @@ -184,39 +195,45 @@ Looking at other boards you might see some different patterns: 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_FNCTION_WITHSTACK`` with a zero + 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 +``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. + 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 +``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 +``__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 LZO-compressed device trees + 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 +``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()`` returns the difference +``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_*(...)``: +``*_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 disk. + 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 @@ -230,7 +247,7 @@ 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_d *dev) + static int my_board_probe(struct device *dev) { /* Do some board-specific setup */ return 0; @@ -241,7 +258,7 @@ tree binding, you can write a driver that matches against your board's { /* sentinel */ }, }; - static struct driver_d my_board_driver = { + static struct driver my_board_driver = { .name = "board-mine", .probe = my_board_probe, .of_compatible = my_board_of_match, @@ -258,7 +275,7 @@ 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/stm32mp157c-odyssey.dts> + #include <arm/st/stm32mp157c-odyssey.dts> #include "stm32mp151.dtsi" / { @@ -371,11 +388,8 @@ Miscellaneous Linux porting advice: * Branches dependent on ``system_state``: Take the ``SYSTEM_BOOTING`` branch * ``usleep`` and co.: use ``[mud]elay`` - * ``.of_node``: use ``.device_node`` or ``dev_of_node`` * ``jiffies``: use ``get_time_ns()`` * ``time_before``: use ``!is_timeout()`` - * ``clk_hw_register_fixed_rate_with_accuracy``: use ``clk_hw_register_fixed_rate`` without accuracy - * ``CLK_SET_RATE_GATE`` can be ignored * ``clk_prepare``: is for the non-atomic code preparing for clk enablement. Merge it into ``clk_enable`` *************************** @@ -388,9 +402,18 @@ New header format ================= Your loader may require a specific header or format. If the header is meant -to be executable, it should preferably be added as inline assembly to -the start of the PBL entry points. See ``__barebox_arm_head`` and -``__barebox_riscv_header``. Otherwise, add a new tool to ``scripts/`` +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. @@ -418,7 +441,7 @@ 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 -baord support for an example. +board support for an example. Core drivers ============ diff --git a/Documentation/devel/project-ideas.rst b/Documentation/devel/project-ideas.rst index d9957e4091..4127b2556b 100644 --- a/Documentation/devel/project-ideas.rst +++ b/Documentation/devel/project-ideas.rst @@ -156,8 +156,6 @@ 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: - - Support for higher MMC speed modes: The maximum currently supported - is 50/52 MHz and no DDR. - 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 @@ -185,13 +183,13 @@ 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/jsbarebox/ +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 jsbarebox tutorial. e.g. by adding new +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. diff --git a/Documentation/devicetree/bindings/barebox/aliases.rst b/Documentation/devicetree/bindings/barebox/aliases.rst index 527cc85ef6..2848a88f15 100644 --- a/Documentation/devicetree/bindings/barebox/aliases.rst +++ b/Documentation/devicetree/bindings/barebox/aliases.rst @@ -2,9 +2,10 @@ barebox DT aliases ================== barebox can use the properties in the ``/aliases`` node to arrive -at deterministic names for devices, e.g.:: +at deterministic names for devices, e.g.: .. code-block:: none + / { aliases { mmc0 = &sdhci; @@ -18,17 +19,22 @@ 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 an -``/aliases/barebox,bootsource-${bootsource}${bootsource_instance}`` +a device tree override is possible via a +``/chosen/barebox,bootsource-${bootsource}${bootsource_instance}`` property: .. code-block:: none - &{/aliases} { - mmc0 = &sdmmc0; - mmc1 = &sdhci; - barebox,bootsource-mmc0 = &sdhci; - barebox,bootsource-mmc1 = &sdmmc0; + / { + 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}`` 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.rst b/Documentation/devicetree/bindings/firmware/altr,passive-serial.rst index 1012137bc9..cbddd700ce 100644 --- a/Documentation/devicetree/bindings/firmware/altr,passive-serial.rst +++ b/Documentation/devicetree/bindings/firmware/altr,passive-serial.rst @@ -6,6 +6,7 @@ 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 diff --git a/Documentation/devicetree/bindings/firmware/altr,socfpga-fpga-mgr.rst b/Documentation/devicetree/bindings/firmware/altr,socfpga-fpga-mgr.rst index 9f7de6b985..478e8e6fc4 100644 --- a/Documentation/devicetree/bindings/firmware/altr,socfpga-fpga-mgr.rst +++ b/Documentation/devicetree/bindings/firmware/altr,socfpga-fpga-mgr.rst @@ -5,10 +5,12 @@ 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. + + 1. The control address space of the FPGA manager. + 2. The configuration data address space where the firmware data is written to. Example: 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 index 6db54070a9..0ba117dffc 100644 --- a/Documentation/devicetree/bindings/mtd/partition.rst +++ b/Documentation/devicetree/bindings/mtd/partition.rst @@ -1,22 +1,33 @@ +.. _devicetree_binding_mtd_partition: + Representing flash partitions in devicetree =========================================== In addition to the upstream binding, another property is added: Optional properties: -- ``partuuid`` : The partition UUID for this partition. + +* ``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 + +* ``partitions`` : user partition +* ``boot0-partitions`` : boot0 partition +* ``boot1-partitions`` : boot1 partition Examples: .. code-block:: none - flash@0 { + / { partitions { compatible = "fixed-partitions"; #address-cells = <1>; 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 index 9afc020acd..754c474328 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.rst +++ b/Documentation/devicetree/bindings/regulator/regulator.rst @@ -4,6 +4,7 @@ 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 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 d03db3cf82..f85ce6608d 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -37,8 +37,8 @@ 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 a phandle, not by -path, to avoid run-time breakage like this:: +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 / { @@ -62,15 +62,48 @@ path, to avoid run-time breakage like this:: 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. -Using phandles avoids this. When no phandle mapping the full path is defined -upstream, the ``&{/path}`` syntax should be used instead, e.g.:: +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"; }; -This would lead to a compile error should the ``/leds/red`` path be renamed or -removed. This also applies to uses of ``/delete-node/``. +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`` @@ -114,5 +147,29 @@ Contents: 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/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/talks.rst b/Documentation/talks.rst index 5f1af59931..5206d649a2 100644 --- a/Documentation/talks.rst +++ b/Documentation/talks.rst @@ -100,7 +100,7 @@ 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 freedesktop.org bootloader specification and its support in barebox. + The bootloader specification and its support in barebox. Barebox Bootloader ------------------ 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 7b37ddba77..43e5a631ba 100644 --- a/Documentation/user/barebox.rst +++ b/Documentation/user/barebox.rst @@ -212,7 +212,36 @@ like a Linux kernel that is passed an external device tree. For example: U-Boot: tftp $kernel_addr barebox-dt-2nd.img U-Boot: tftp $fdt_addr my-board.dtb - U-Boot: booti $kernel_addr - $fdt_addr + 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 @@ -224,7 +253,7 @@ 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 image + 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 @@ -233,7 +262,7 @@ image for that board. The image can then be started with ``bootm``: .. code-block:: console - U-Boot: tftp $load_addr barebox.bin + 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 @@ -300,16 +329,25 @@ 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. +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. -There are two ``ARCH=sandbox`` to make this more straight forward: +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``. +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 @@ -322,9 +360,9 @@ 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 built any host tools, so it's ok to +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. The default is ``CROSS_PKG_CONFIG=$(CROSS_COMPILE)pkg-config``. Example: +use. Example: .. code-block:: console diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst index db0a4f8898..1a2ce70bb2 100644 --- a/Documentation/user/bootchooser.rst +++ b/Documentation/user/bootchooser.rst @@ -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 60babb513c..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 ------------ diff --git a/Documentation/user/introduction.rst b/Documentation/user/introduction.rst index e7388b8bc9..63a4c29cba 100644 --- a/Documentation/user/introduction.rst +++ b/Documentation/user/introduction.rst @@ -29,12 +29,10 @@ http://lists.infradead.org/mailman/listinfo/barebox/ Mails sent to the barebox mailing list are archived on `lore.barebox.org <https://lore.barebox.org/barebox/>`_. -Patch series sent there can be fetched with `b4 <https://pypi.org/project/b4/>`_ :: +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 am https://lore.barebox.org/$messageid # replace with link + b4 shazam -M https://lore.barebox.org/$messageid # replace with link -There's also an IRC channel, which is -`bridged to Matrix <https://app.element.io/#/room/#barebox:matrix.org>`_: -#barebox on Libera Chat +There's also an IRC channel: #barebox on Libera Chat 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/reboot-mode.rst b/Documentation/user/reboot-mode.rst index 83d4136b85..1929a67e0b 100644 --- a/Documentation/user/reboot-mode.rst +++ b/Documentation/user/reboot-mode.rst @@ -47,7 +47,9 @@ 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. +if available. Example usage:: + + gpr.reboot_mode=serial reset -w Reset ===== @@ -60,6 +62,9 @@ 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 ============== diff --git a/Documentation/user/remote-control.rst b/Documentation/user/remote-control.rst index 43f1fb3118..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 - python2 -m 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 a0e27d4fe8..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,8 +571,87 @@ content, its backend-type and *state* variable layout. }; }; -If the *state* variable set is set to be located in a GPT partition, use -``4778ed65-bf42-45fa-9c5b-287a1dc4aab1`` as the partition type GUID. + +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 #### diff --git a/Documentation/user/usb.rst b/Documentation/user/usb.rst index 2479efe9d6..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 ---------------------------- diff --git a/Documentation/user/virtio.rst b/Documentation/user/virtio.rst index d944fa4821..046e5dac82 100644 --- a/Documentation/user/virtio.rst +++ b/Documentation/user/virtio.rst @@ -44,7 +44,7 @@ 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 vexpress_defconfig + $ make multi_v7_defconfig $ make Testing @@ -72,15 +72,17 @@ 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,disable-legacy=on \ + -device virtio-rng-pci \ -drive if=none,file=image1.hdimg,format=raw,id=hd0 \ - -device virtio-blk-pci,drive=hd0,disable-legacy=on \ + -device virtio-blk-pci,drive=hd0 \ -drive if=none,file=image2.hdimg,format=raw,id=hd1 \ - -device virtio-blk-pci,drive=hd1,disable-legacy=on + -device virtio-blk-pci,drive=hd1 -Note the use of ``disable-legacy=on``. barebox doesn't support legacy -or transitional VirtIO devices. Some versions of QEMU may need to -have ``,disable-modern=off`` specfied as well. +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 |