diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/boards/at91.rst | 16 | ||||
| -rw-r--r-- | Documentation/boards/at91/microchip-sama5d3-xplained.rst | 8 | ||||
| -rw-r--r-- | Documentation/boards/imx.rst | 29 | ||||
| -rw-r--r-- | Documentation/boards/imx/nxp-imx8mn-evk.rst | 60 | ||||
| -rw-r--r-- | Documentation/boards/socfpga.rst | 2 | ||||
| -rw-r--r-- | Documentation/devel/porting.rst | 21 | ||||
| -rw-r--r-- | Documentation/user/barebox.rst | 45 | ||||
| -rw-r--r-- | Documentation/user/defaultenv-2.rst | 2 | ||||
| -rw-r--r-- | Documentation/user/framebuffer.rst | 6 | ||||
| -rw-r--r-- | Documentation/user/multi-image.rst | 2 | ||||
| -rw-r--r-- | Documentation/user/reboot-mode.rst | 4 | ||||
| -rw-r--r-- | Documentation/user/virtio.rst | 2 |
12 files changed, 174 insertions, 23 deletions
diff --git a/Documentation/boards/at91.rst b/Documentation/boards/at91.rst index e45feee947..f502979df6 100644 --- a/Documentation/boards/at91.rst +++ b/Documentation/boards/at91.rst @@ -31,14 +31,20 @@ The resulting images will be placed under ``images/``: :: - barebox-groboards-sama5d27-giantboard.img - barebox-groboards-sama5d27-giantboard-xload-mmc.img + barebox-at91sam9x5ek.img + barebox-at91sam9263ek.img barebox-microchip-ksz9477-evb.img + barebox-microchip-ksz9477-evb-xload-mmc.img + barebox-sama5d3-xplained.img + barebox-sama5d3-xplained-xload-mmc.img barebox-sama5d27-som1-ek.img barebox-sama5d27-som1-ek-xload-mmc.img + barebox-groboards-sama5d27-giantboard.img + barebox-groboards-sama5d27-giantboard-xload-mmc.img + barebox-skov-arm9cpu.img -Older supported boards have yet to be migrated to multi-image and/or the -new defconfig. The majority of these have a short entry here. +Older supported boards have yet to be migrated to multi-image and device tree. +The majority of these have a short entry here. For each board defconfig file(s) are noted but barebox may include additional defconfig files and may also include boards not included in the following. @@ -54,7 +60,5 @@ This is a list of AT91 specific TODO items, listed in no particular order. * Update remaining boards to DT * Update remaing boards to support multi image boot -* Include remaining boards in ``at91_multi_defconfig`` -* Get bootstrap working in combination with multi image * Introduce defaultenv2 for all boards * Add pwm driver (required to support backlight) diff --git a/Documentation/boards/at91/microchip-sama5d3-xplained.rst b/Documentation/boards/at91/microchip-sama5d3-xplained.rst deleted file mode 100644 index e96111af72..0000000000 --- a/Documentation/boards/at91/microchip-sama5d3-xplained.rst +++ /dev/null @@ -1,8 +0,0 @@ -Atmel SAMA5D3_XPLAINED Evaluation Kit -===================================== - -Building barebox: - -.. code-block:: sh - - make ARCH=arm sama5d3_xplained_defconfig diff --git a/Documentation/boards/imx.rst b/Documentation/boards/imx.rst index 887b45c708..4ce9d9808c 100644 --- a/Documentation/boards/imx.rst +++ b/Documentation/boards/imx.rst @@ -83,6 +83,35 @@ The images can also always be started as second stage on the target: barebox@Board Name:/ bootm /mnt/tftp/barebox-freescale-imx51-babbage.img +BootROM Reboot mode codes (bmode) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For select SoCs, barebox supports communicating an alternative boot medium +that BootROM should select after a warm reset:: + + barebox@FSL i.MX8MM EVK board:/ devinfo gpr.reboot_mode + Driver: syscon-reboot-mode + Bus: platform + Parent: 30390000.reset-controller@30390000.of + Parameters: + next: normal (type: enum) (values: "normal", "serial") + prev: normal (type: enum) (values: "normal", "serial") + Device node: /soc@0/bus@30000000/reset-controller@30390000/reboot-mode + reboot-mode { + compatible = "barebox,syscon-reboot-mode"; + offset = <0x94 0x98>; + mask = <0xffffffff 0x40000000>; + mode-normal = <0x0 0x0>; + mode-serial = <0x10 0x40000000>; + }; + + barebox@FSL i.MX8MM EVK board:/ gpr.reboot_mode.next=serial reset -r imxwd-warm + +This will cause barebox to fall into serial download mode on an i.MX8MM. + +Different SoCs may have more possible reboot modes available. +See the section on :ref:`Reboot modes<reboot_mode>` for more information. + High Assurance Boot ^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/boards/imx/nxp-imx8mn-evk.rst b/Documentation/boards/imx/nxp-imx8mn-evk.rst new file mode 100644 index 0000000000..44cd0c68e4 --- /dev/null +++ b/Documentation/boards/imx/nxp-imx8mn-evk.rst @@ -0,0 +1,60 @@ +NXP i.MX8MN EVK Evaluation Board +================================ + +Board comes with either: + +* 2GiB of LPDDR4 RAM +* 2GiB of DDR4 RAM + +barebox supports both variants with the same image. + +Downloading DDR PHY Firmware +---------------------------- + +As a part of DDR intialization routine NXP i.MX8MN EVK requires and +uses several binary firmware blobs that are distributed under a +separate EULA and cannot be included in Barebox. In order to obtain +them do the following:: + + wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.12.bin + chmod +x firmware-imx-8.12.bin + ./firmware-imx-8.12.bin + +Executing that file should produce a EULA acceptance dialog as well as +result in the following files: + +- lpddr4_pmu_train_1d_dmem.bin +- lpddr4_pmu_train_1d_imem.bin +- lpddr4_pmu_train_2d_dmem.bin +- lpddr4_pmu_train_2d_imem.bin +- ddr4_dmem_1d_201810.bin +- ddr4_imem_1d_201810.bin +- ddr4_dmem_2d_201810.bin +- ddr4_imem_2d_201810.bin + +As a last step of this process those files need to be placed in +"firmware/":: + + for f in lpddr4_pmu_train_1d_dmem.bin \ + lpddr4_pmu_train_1d_imem.bin \ + lpddr4_pmu_train_2d_dmem.bin \ + lpddr4_pmu_train_2d_imem.bin; \ + do \ + cp firmware-imx-8.0/firmware/ddr/synopsys/${f} \ + firmware/${f}; \ + done + + for f in ddr4_dmem_1d_201810.bin \ + ddr4_imem_1d_201810.bin \ + ddr4_dmem_2d_201810.bin \ + ddr4_imem_2d_201810.bin; \ + do \ + cp firmware-imx-8.0/firmware/ddr/synopsys/${f} \ + firmware/${f%_201810.bin}.bin; \ + done + +Build barebox +============= + + make imx_v8_defconfig + make diff --git a/Documentation/boards/socfpga.rst b/Documentation/boards/socfpga.rst index 19d6060300..7e7f0619ea 100644 --- a/Documentation/boards/socfpga.rst +++ b/Documentation/boards/socfpga.rst @@ -121,7 +121,7 @@ Now run the command: .. code-block:: sh - scripts/socfpga_import_preloader <EMBEDDED_SDK> <ISW_HANDOFF> <BOARD_DIRECTORY> + scripts/socfpga_import_preloader -e <EMBEDDED_SDK> -i <ISW_HANDOFF> -b <BOARD_DIRECTORY> where `<SPL_GENERATED_DIR>` is the directory where the bsp-editor generated the files, `<ISW_HANDOFF>` is the directory where Quartus generated the handoff files, and diff --git a/Documentation/devel/porting.rst b/Documentation/devel/porting.rst index 97b787327c..1abaabc03a 100644 --- a/Documentation/devel/porting.rst +++ b/Documentation/devel/porting.rst @@ -169,6 +169,27 @@ Looking at other boards you might see some different patterns: needs to be done at start. If a board similar to yours does this, you probably want to do likewise. + - ``__naked``: All functions called before stack is correctly initialized must be + marked with this attribute. Otherwise, function prologue and epilogue may access + the uninitialized stack. If the compiler for the target architecture doesn't + support the attribute, stack must be set up in non-inline assembly: + Either a barebox assembly entry point or in earlier firmware. + The compiler may still spill excess local C variables used in a naked function + to the stack before it was initialized. + A naked function should thus preferably only contain inline assembly, set up a + stack and jump directly after to a ``noinline`` non naked function where the + stack is then normally usable. + + - ``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. + + - ``arm_setup_stack``: For 32-bit ARM, ``arm_setup_stack`` initializes the stack + top when called from a naked C function, which allows to write the entry point + directly in C. The stack pointer will be decremented before pushing values. + Avoid interleaving with C-code. See ``__naked`` above for more details. + - ``__dtb_z_my_board_start[];``: Because the PBL normally doesn't parse anything out of the device tree blob, boards can benefit from keeping the device tree blob compressed and only unpack it in barebox proper. Such LZO-compressed device trees diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst index 503f0b9797..b6b7a57af3 100644 --- a/Documentation/user/barebox.rst +++ b/Documentation/user/barebox.rst @@ -262,3 +262,48 @@ 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. + +There are two ``ARCH=sandbox`` 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``. + +.. 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 built 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: + +.. code-block:: console + + export ARCH=sandbox CROSS_COMPILE=aarch64-linux-gnu- + export CROSS_PKG_CONFIG=pkg-config + make targettools_defconfig + make scripts diff --git a/Documentation/user/defaultenv-2.rst b/Documentation/user/defaultenv-2.rst index bf738084b2..a01a70fa93 100644 --- a/Documentation/user/defaultenv-2.rst +++ b/Documentation/user/defaultenv-2.rst @@ -149,6 +149,6 @@ there will be a file ``eth0`` with a content like this: ----------- This contains the files to be sourced when barebox detects that the OS -had requested a specific reboot mode (via e.g. ``reboot bootloader`` +had requested a specific :ref:`reboot_mode` (via e.g. ``reboot bootloader`` under Linux). After the ``/env/init`` scripts were executed, barebox will ``source /env/bmode/${global.system.reboot_mode.prev}`` if available. diff --git a/Documentation/user/framebuffer.rst b/Documentation/user/framebuffer.rst index 8b95ad6b87..d17df822f2 100644 --- a/Documentation/user/framebuffer.rst +++ b/Documentation/user/framebuffer.rst @@ -4,9 +4,7 @@ Framebuffer support Framebuffer splash screen ------------------------- -barebox supports BMP and PNG graphics using the :ref:`command_splash` command. barebox -currently has no support for backlights, so unless there is a board specific enable -hook for enabling a display it must be done manually with a script. Since barebox +barebox supports BMP and PNG graphics using the :ref:`command_splash` command. Since barebox has nothing useful to show on the framebuffer it doesn't enable it during startup. A framebuffer can be enabled with the ``enable`` parameter of the framebuffer device: @@ -39,7 +37,7 @@ A typical script to enable the framebuffer could look like this: # wait for signals to become stable msleep 100 - # finally enable backlight + # finally enable backlight manually if no driver exists gpio_direction_output 42 1 Framebuffer console diff --git a/Documentation/user/multi-image.rst b/Documentation/user/multi-image.rst index 727b98fe5a..3b37d13794 100644 --- a/Documentation/user/multi-image.rst +++ b/Documentation/user/multi-image.rst @@ -51,4 +51,4 @@ generated a different entry point is selected using the ``-e`` option to ld. The linker will throw away all unused entry points and only keep the functions used by a particular entry point. -The Multi Image PBL files can be disassembled with ``make <entry-function-name.pbl.S`` +The Multi Image PBL files can be disassembled with ``make images/<entry-function-name>.pbl.S`` diff --git a/Documentation/user/reboot-mode.rst b/Documentation/user/reboot-mode.rst index 8717e39342..507d6feb01 100644 --- a/Documentation/user/reboot-mode.rst +++ b/Documentation/user/reboot-mode.rst @@ -44,7 +44,9 @@ the device. By convention, this should end with ``.reboot_mode``, e.g.:: 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``. +and ``$global.system.reboot_mode.next``. After executing the init scripts, +barebox startup will ``source /env/bmode/${global.system.reboot_mode.prev}`` +if available. Reset ===== diff --git a/Documentation/user/virtio.rst b/Documentation/user/virtio.rst index dde47d5f82..d944fa4821 100644 --- a/Documentation/user/virtio.rst +++ b/Documentation/user/virtio.rst @@ -35,7 +35,7 @@ queues configuration and buffer transfers are nearly identical. Both MMIO and non-legacy PCI are supported in barebox. The VirtIO spec defines a lots of VirtIO device types, however at present only -block, console, input and RNG devices are supported. +block, network, console, input and RNG devices are supported. Build Instructions ------------------ |