diff options
Diffstat (limited to 'Documentation/user/barebox.rst')
| -rw-r--r-- | Documentation/user/barebox.rst | 123 |
1 files changed, 115 insertions, 8 deletions
diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst index 6bea883115..43e5a631ba 100644 --- a/Documentation/user/barebox.rst +++ b/Documentation/user/barebox.rst @@ -54,7 +54,6 @@ variable. Currently, ``ARCH`` must be one of: * arm * mips -* nios2 * openrisc * ppc * riscv @@ -204,13 +203,66 @@ Starting barebox Bringing barebox to a board for the first time is highly board specific, see your board documentation for initial bringup. -barebox binaries are, where possible, designed to be startable second stage from another -bootloader. For example, if you have U-Boot running on your board, you can start barebox -with U-Boot's ``bootm`` command: +For ARM and RISC-V, the barebox build can additionally generate a generic DT image +(enable ``CONFIG_BOARD_ARM_GENERIC_DT`` or ``CONFIG_BOARD_RISCV_GENERIC_DT``, +respectively). The resulting ``images/barebox-dt-2nd.img`` can be booted just +like a Linux kernel that is passed an external device tree. For example: .. code-block:: console - U-Boot: tftp $load_addr barebox.bin + U-Boot: tftp $kernel_addr barebox-dt-2nd.img + U-Boot: tftp $fdt_addr my-board.dtb + U-Boot: bootz $kernel_addr - $fdt_addr # On 32-bit ARM + U-Boot: booti $kernel_addr - $fdt_addr # for other platforms + +Another option is to generate a FIT image containing the generic DT image and a +matching device tree with ``mkimage``: + +.. code-block:: console + + sh: mkimage --architecture arm \ + --os linux \ + --type kernel \ + --fit auto \ + --load-address $kernel_addr_r \ + --compression none \ + --image images/barebox-dt-2nd.img \ + --device-tree arch/${ARCH}/dts/my-board.dtb \ + barebox-dt-2nd.fit + +This FIT image can then be loaded by U-Boot and executed just like a regular +Linux kernel: + +.. code-block:: console + + U-Boot: tftp $fit_addr barebox-dt-2nd.fit + U-Boot: bootm $fit_addr + +Make sure that the address in ``$fit_addr`` is different from the +``$kernel_addr_r`` passed to ``mkimage`` as the load address of the Kernel +image. Otherwise U-Boot may attempt to overwrite the FIT image with the barebox +image contained within. + +For non-DT enabled-bootloaders or other architectures, often the normal barebox +binaries can also be used as they are designed to be startable second stage +from another bootloader, where possible. For example, if you have U-Boot running +on your board, you can start barebox with U-Boot's ``bootm`` command. The bootm +command doesn't support the barebox binaries directly, they first have to be +converted to uImage format using the mkimage tool provided with U-Boot: + +.. code-block:: console + + sh: mkimage -n barebox -A arm -T kernel -C none -a 0x80000000 -d \ + build/images/barebox-freescale-imx53-loco.img barebox.uImage + +U-Boot expects the start address of the binary to be given in the image using the +``-a`` option. The address depends on the board and must be an address which isn't +used by U-Boot. You can pick the same address you would use for generating a kernel +image for that board. The image can then be started with ``bootm``: + +.. code-block:: console + + U-Boot: tftp $load_addr barebox.uImage U-Boot: bootm $load_addr With barebox already running on your board, this can be used to chainload @@ -221,10 +273,11 @@ another barebox. For instance, if you mounted a TFTP server to ``/mnt/tftp`` bootm /mnt/tftp/barebox.bin -At least ``barebox.bin`` (with :ref:`pbl` support enabled ``arch/$ARCH/pbl/zbarebox.bin``) -should be startable second stage. The flash binary (``barebox-flash-image``) may or may not +At least ``barebox.bin`` (with :ref:`pbl` support enabled ``images/*.pblb``) +should be startable second stage. The final binaries (``images/*.img``) may or may not be startable second stage as it may have SoC specific headers which prevent running second -stage. +stage. barebox will usually have handlers in-place to skip these headers, so +it can chainload itself regardless. First Steps ----------- @@ -263,3 +316,57 @@ the usage for a particular command. barebox has tab completion which will comple your command. Arguments to commands are also completed depending on the command. If a command expects a file argument only files will be offered as completion. Other commands will only complete devices or devicetree nodes. + +Building barebox tools +---------------------- + +The normal barebox build results in one or more barebox images (cf. :ref:`multi_image`) +and a number of tools built from its ``scripts/`` directory. + +Most tools are used for the barebox build itself: e.g. the device tree compiler, +the Kconfig machinery and the different image formatting tools that wrap barebox, +so it may be loaded by the boot ROM of the relevant SoCs. + +In addition to these barebox also builds host and target tools that are useful +outside of barebox build: e.g. to manipulate the environment or to load an +image over a boot ROM's USB recovery protocol. These tools may link against +libraries, which are detected using ``PKG_CONFIG`` and ``CROSS_PKG_CONFIG`` +for native and cross build respectively. Their default values are:: + + PKG_CONFIG=pkg-config + CROSS_PKG_CONFIG=${CROSS_COMPILE}pkg-config + +These can be overridden using environment or make variables. + +As use of pkg-config both for host and target tool in the same build can +complicate build system integration. There are two ``ARCH=sandbox`` configuration +to make this more straight forward: + +Host Tools +^^^^^^^^^^ + +The ``hosttools_defconfig`` will compile standalone host tools for the +host (build) system. To build the USB loaders, ``PKG_CONFIG`` needs to know +about ``libusb-1.0``. This config won't build any target tools. + +.. code-block:: console + + export ARCH=sandbox + make hosttools_defconfig + make scripts + +Target Tools +^^^^^^^^^^^^ + +The ``targettools_defconfig`` will cross-compile standalone target tools for the +target system. To build the USB loaders, ``CROSS_PKG_CONFIG`` needs to know +about ``libusb-1.0``. This config won't build any host tools, so it's ok to +set ``CROSS_PKG_CONFIG=pkg-config`` if ``pkg-config`` is primed for target +use. Example: + +.. code-block:: console + + export ARCH=sandbox CROSS_COMPILE=aarch64-linux-gnu- + export CROSS_PKG_CONFIG=pkg-config + make targettools_defconfig + make scripts |