diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/boards/imx.rst | 73 | ||||
-rw-r--r-- | Documentation/boards/imx/embest-marsboard.rst | 82 | ||||
-rw-r--r-- | Documentation/boards/imx/zii-vf610-dev/openocd.cfg | 8 | ||||
-rw-r--r-- | Documentation/boards/layerscape.rst | 61 | ||||
-rw-r--r-- | Documentation/boards/layerscape/ls1046ardb.rst | 36 | ||||
-rw-r--r-- | Documentation/boards/layerscape/tqmls1046a.rst | 49 | ||||
-rw-r--r-- | Documentation/boards/stm32mp.rst | 4 | ||||
-rw-r--r-- | Documentation/devicetree/index.rst | 59 | ||||
-rwxr-xr-x | Documentation/gen_commands.py | 30 | ||||
-rw-r--r-- | Documentation/user/barebox.rst | 1 |
10 files changed, 384 insertions, 19 deletions
diff --git a/Documentation/boards/imx.rst b/Documentation/boards/imx.rst index 71cc6bb09a..8fe0a2828d 100644 --- a/Documentation/boards/imx.rst +++ b/Documentation/boards/imx.rst @@ -142,6 +142,79 @@ It must be included in the board's flash header: Analogous to HABv4 options and a template exist for HABv3. +Secure Boot on i.MX6 +~~~~~~~~~~~~~~~~~~~~ + +For most boards, the secure boot process on i.MX6 consist of the following image +constellation:: + + 0x0 +---------------------------------+ + | Barebox Header | + 0x400 +---------------------------------+ - + | i.MX IVT Header | | + | Boot Data +--+ | + | CSF Pointer +--|-+ | Signed Area + +---------------------------------+ | | | + | Device Configuration Data (DCD) | | | | + 0x1000 +---------------------------------+ | | | + | Barebox Prebootloader (PBL) |<-+ | | + +---------------------------------+ | | + | Piggydata (Main Barebox Binary) | | | + +---------------------------------+ | - + | Command Sequence File (CSF) |<---+ + +---------------------------------+ + +Here the Command Sequence File signs the complete Header, PBL and piggy data +file. This ensures that the whole barebox binary is authenticated. This is +possible since the DDR RAM is configured using the DCD and the whole DDR memory +area can be used to load data onto the device for authentication. +The boot ROM loads the CSF area and barebox into memory and uses the CSF to +verify the complete barebox binary. + +Boards which do require a boot via SRAM, need changes akin to the implementation +for i.MX8MQ described in the next chapter. + +Secure Boot on i.MX8MQ +~~~~~~~~~~~~~~~~~~~~~~ + +For i.MX8MQ the image has the following design:: + + 0x0 +---------------------------------+ + | Barebox Header | + +---------------------------------+ + | i.MX IVT Header | + | HDMI Firmware (Signed by NXP) | + +---------------------------------+ - + | i.MX IVT Header | | + | Boot Data +--+ | + | CSF Pointer +--|-+ | + +---------------------------------+ | | | Signed Area + | Device Configuration Data (DCD) | | | | + +---------------------------------+ | | | + | Barebox Prebootloader (PBL) |<-+ | | + | Piggydata Hash (SHA256) +----|-+ | + +---------------------------------+ | | - + | Command Sequence File (CSF) |<---+ | + +---------------------------------+ | - + | Piggydata (Main Barebox Binary) |<-----+ | Hashed Area + +---------------------------------+ - + +In contrast to i.MX6, for the i.MX8MQ the piggydata can not be signed together +with the PBL binary. The DDR memory is initialized during the start of the PBL, +previous to this no access to the DDR memory is possible. Since the Tightly +Coupled Memory used for early startup on i.MX8MQ has only 256Kib, the whole +barebox can't be loaded and verified at once, since the complete barebox with +firmware has a size of ~500Kib. + +The bootrom loads the HDMI firmware unconditionally, since it is signed by NXP. +Afterwards the Prebootloader (PBL) is loaded into SRAM and the bootrom proceeds +to verify the PBL according to the Command Sequence File (CSF). The verified +PBL initializes the ARM Trusted Firmware (TF-A) and DDR RAM. It subsequently +loads the piggydata from the boot media and calculates the sha256sum of the +piggydata. This is compared to the sha256sum built into the PBL during compile +time, the PBL will only continue to boot if the sha256sum matches the builtin +sha256sum. + Using GPT on i.MX ^^^^^^^^^^^^^^^^^ diff --git a/Documentation/boards/imx/embest-marsboard.rst b/Documentation/boards/imx/embest-marsboard.rst new file mode 100644 index 0000000000..bdaa0880ae --- /dev/null +++ b/Documentation/boards/imx/embest-marsboard.rst @@ -0,0 +1,82 @@ +Embest MarS Board +================= + +Board comes with: + +* 1G DDR3 SDRAM +* 4G eMMC +* 2M SPI-NOR Flash + +Layout:: + + .-----------------------------------------------------. + |O OTG-->| V | O| + | SW1 USB '---' .--| + | .-----------. v.---. .->| <| + | | | 1|o--| O | `--| + | | i.MX6Dual | 2|--o| N Debug | + | | SoC | `---' USB | + | | | | + | `-----------' | + | | + | | + | | + | | + |O O| + `-----------------------------------------------------' + +Boot Configuration +================== + +DIP Switch ``SW1`` on the board can be used to set ``BOOT_MODE1`` and +``BOOT_MODE0`` going to the i.MX6: + +Set ``SW1 = 01`` for serial boot:: + + SW1 + v.---. + 1|o--| O + 2|--o| N + `---' + +Set ``SW1 = 10`` for internal (SPI-NOR Flash) boot:: + + SW1 + v.---. + 1|--o| O + 2|o--| N + `---' + +Set ``SW1 = 00`` for boot from eFuses:: + + SW1 + v.---. + 1|o--| O + 2|o--| N + `---' + +Flashing barebox +---------------- + + 1. Connect to the board's Debug Mini-USB (115200 8N1) + + 2. Set ``SW1 = 01`` for serial boot mode (see above) + + 3. Turn board's power on + + 4. Upload barebox image to the board via imx-usb-loader + +.. code-block:: none + + host$ imx-usb-loader images/barebox-embest-imx6q-marsboard.img +.. + + 4. Flash barebox to SPI-NOR Flash via Android Fastboot + +.. code-block:: none + + host$ fastboot flash bbu-spiflash images/barebox-embest-imx6q-marsboard.img + +.. + + 5. Restore ``SW1 = 10`` for internal (SPI-NOR) boot (see above) diff --git a/Documentation/boards/imx/zii-vf610-dev/openocd.cfg b/Documentation/boards/imx/zii-vf610-dev/openocd.cfg index 5127c7623d..c94f9d048d 100644 --- a/Documentation/boards/imx/zii-vf610-dev/openocd.cfg +++ b/Documentation/boards/imx/zii-vf610-dev/openocd.cfg @@ -148,10 +148,10 @@ proc ddr_init { } { mww phys 0x400ae210 0x00000506 ;# wm 32 DDRMC_CR132 0x00000506 mww phys 0x400ae224 0x00020000 ;# wm 32 DDRMC_CR137 0x00020000 mww phys 0x400ae228 0x01000100 ;# wm 32 DDRMC_CR138 0x01000100 - mww phys 0x400ae22c 0x04070303 ;# wm 32 DDRMC_CR154 0x682c4000 - mww phys 0x400ae230 0x00000040 ;# wm 32 DDRMC_CR155 0x00000009 - mww phys 0x400ae23c 0x06000080 ;# wm 32 DDRMC_CR158 0x00000006 - mww phys 0x400ae240 0x04070303 ;# wm 32 DDRMC_CR161 0x00010606 + mww phys 0x400ae268 0x682c4000 ;# wm 32 DDRMC_CR154 0x682c4000 + mww phys 0x400ae26c 0x00000009 ;# wm 32 DDRMC_CR155 0x00000009 + mww phys 0x400ae278 0x00000006 ;# wm 32 DDRMC_CR158 0x00000006 + mww phys 0x400ae284 0x00010606 ;# wm 32 DDRMC_CR161 0x00010606 # # flash-header-zii-vf610-dev.imxcfg diff --git a/Documentation/boards/layerscape.rst b/Documentation/boards/layerscape.rst new file mode 100644 index 0000000000..ae089539e5 --- /dev/null +++ b/Documentation/boards/layerscape.rst @@ -0,0 +1,61 @@ +NXP Layerscape +============== + +barebox has support for some of the ARM64 based Layerscape SoCs from NXP. + +Booting barebox +--------------- + +The Layerscape SoCs contain logic dubbed the Pre-Bootloader (PBL). This unit +reads the boot medium and conducts basic IO multiplexing according to the RCW +(Reset Configuration Word). The RCW then refers the PBL to the location of the +Pre-Bootloader Instructions (PBI). These do basic device configuration and +afterwards poke the barebox PBL into On-Chip SRAM. +The barebox PBL then loads the complete barebox image and runs the PBL again, +this time from SDRAM after it has been set up. + +For each board, a barebox image per supported boot medium is generated. +They may differ in the RCW, PBI and endianess depending on the boot medium. + +Flashing barebox +---------------- + +The barebox binary is expected to be located 4K bytes into the SD-Card:: + + dd if=images/barebox-${boardname}-sd.image of=/dev/sdX bs=512 seek=8 + +From there on, ``barebox_update`` can be used to flash +barebox to the QSPI NOR-Flash if required:: + + barebox_update -t qspi /mnt/tftp/barebox-${global.hostname}-qspi.imaag + +Flashing to the eMMC is possible likewise:: + + barebox_update -t sd /mnt/tftp/barebox-${global.hostname}-sd.imaag + +.. note:: Some SoCs like the LS1046A feature only a single eSDHC. + In such a case, using eMMC and SD-Card at the same time is not possible. + Boot from QSPI to flash the eMMC. + +Firmware Blobs +-------------- + +Network: `fsl_fman_ucode_ls1046_r1.0_106_4_18.bin <https://github.com/NXP/qoriq-fm-ucode/raw/integration/fsl_fman_ucode_ls1046_r1.0_106_4_18.bin>`_. + +PSCI Firmware: `ppa-ls1046a.bin <https://github.com/NXP/qoriq-ppa-binary/raw/integration/soc-ls1046/ppa.itb>`_. + +Layerscape boards +----------------- + +With multi-image and device trees, it's expected to have ``layerscape_defconfig`` +as sole defconfig for all Layerscape boards:: + + make ARCH=arm layerscape_defconfig + +Generated images will be placed under ``images/``. + +.. toctree:: + :glob: + :maxdepth: 1 + + layerscape/* diff --git a/Documentation/boards/layerscape/ls1046ardb.rst b/Documentation/boards/layerscape/ls1046ardb.rst new file mode 100644 index 0000000000..323f2ca990 --- /dev/null +++ b/Documentation/boards/layerscape/ls1046ardb.rst @@ -0,0 +1,36 @@ +NXP LS1046A Reference Design Board +================================== + +Boot DIP Switches +----------------- + +Boot source selection happens via the the bottom most DIP switch (near the micro-usb port):: + + OFF -> ON + +---------+ + 1 | O---- | + 2 | O---- | + 3 | ----O | + 4 | O---- | + 5 | O---- | + 6 | O---- | + 7 | ----O | <---- Boot from QSPI (default) + 8 | O---- | + +---------+ + + OFF -> ON + +---------+ + 1 | O---- | + 2 | O---- | + 3 | ----O | + 4 | O---- | + 5 | O---- | + 6 | O---- | + 7 | O---- | <---- Boot from SDHC + 8 | O---- | + +---------+ + +Known Issues +------------ + +System reset may not complete if the CMSIS-DAP micro-usb is connected. diff --git a/Documentation/boards/layerscape/tqmls1046a.rst b/Documentation/boards/layerscape/tqmls1046a.rst new file mode 100644 index 0000000000..55a5dff4a3 --- /dev/null +++ b/Documentation/boards/layerscape/tqmls1046a.rst @@ -0,0 +1,49 @@ +TQ-Group TQMLS1046A Module +========================== + +Ethernet Ports +-------------- + +There two RGMII ports are the two closest to the RS-232 socket. +They are ``eth2`` for the lower port and ``eth3`` for the upper port. + +MBLS10xxA (Base Board) Boot DIP Switches +---------------------------------------- + +Boot source selection happens via the ``S5`` DIP-Switch:: + + +---------+ + | | + | | | O x | + | | | | x | <---- SDHC (X31) + | O O | x | + | | + | 1 2 3 4 | + +---------+ + + +---------+ + | | + | O | O x | + | | | | x | <---- eMMC + | | O | x | + | | + | 1 2 3 4 | + +---------+ + + +---------+ + | | + | | O O x | + | | | | x | <---- QSPI (eSDHC controls SDHC) + | O | | x | + | | + | 1 2 3 4 | + +---------+ + + +---------+ + | | + | O O O x | + | | | | x | <---- QSPI (eSDHC controls eMMC) + | | | | x | + | | + | 1 2 3 4 | + +---------+ diff --git a/Documentation/boards/stm32mp.rst b/Documentation/boards/stm32mp.rst index 24cf8859db..774ede6e56 100644 --- a/Documentation/boards/stm32mp.rst +++ b/Documentation/boards/stm32mp.rst @@ -60,6 +60,10 @@ An appropriate image for the boot media can be generated with following image = "barebox-@STM32MP_BOARD@.img" size = 1M } + partition barebox-environment { + image = "/dev/null" + size = 1M + } } Image can then be flashed on e.g. a SD-Card. diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index c6309defdf..908652642b 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -1,5 +1,60 @@ -Barebox specific devicetree bindings -==================================== +Barebox devicetree handling and bindings +======================================== + +The preferred way of adding board support to barebox is to have devices +on non-enumerable buses probed from device tree. +barebox imports the Linux OpenFirmware ``of_*``-API functions for device tree +parsing, which makes porting the device tree specific bits from device drivers +very straight forward. + +Additionally, barebox has support for programmatically fixing up device trees +it passes to the kernel, either directly via ``of_register_fixup`` or via device +tree overlays. + +Upstream Device Trees +--------------------- + +barebox regularly synchronizes with the Linux kernel device tree definitions +via the `kernel.org Split device-tree repository`_. +They are located under the top-level ``dts/`` directory. + +Patches against ``dts/`` and its subdirectories are not accepted upstream. + +.. _kernel.org Split device-tree repository: https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/ + +barebox Device Trees +-------------------- + +For supporting architectures, barebox device trees are located in +``arch/$ARCH/dts``. Usually the barebox ``board.dts`` imports the upstream +device tree under ``dts/src/$ARCH`` with ``#include "$ARCH/board.dts"`` and +then extends it with barebox-specifics like :ref:`barebox,state`, +environment or boot-time device configuration. + +Device Tree Compiler +-------------------- + +barebox makes use of the ``dtc`` and ``fdtget`` and the underlying ``libfdt`` +from the `Device-Tree Compiler`_ project. + +.. _Device-Tree Compiler: https://git.kernel.org/pub/scm/utils/dtc/dtc.git + +These utilities are built as part of the barebox build process. Additionally, +libfdt is compiled once more as part of the ``CONFIG_BOARD_ARM_GENERIC_DT`` +if selected. + +Steps to update ``scripts/dtc``: + +* Place a ``git-checkout`` of the upstream ``dtc`` directory in the parent + directory of your barebox ``git-checkout``. +* Run ``scripts/dtc/update-dtc-source.sh`` from the top-level barebox directory. +* Wait till ``dtc`` build, test, install and commit conclude. +* Compile-test with ``CONFIG_BOARD_ARM_GENERIC_DT=y``. +* If ``scripts/dtc/Makefile`` or barebox include file changes are necessary, + apply them manually in a commit preceding the ``dtc`` update. + +barebox-specific Bindings +------------------------- Contents: diff --git a/Documentation/gen_commands.py b/Documentation/gen_commands.py index 6251b4f22e..203a39bb11 100755 --- a/Documentation/gen_commands.py +++ b/Documentation/gen_commands.py @@ -1,5 +1,7 @@ #!/usr/bin/python +from __future__ import print_function + import errno import os import re @@ -28,10 +30,15 @@ CONT = re.compile(r"""\s*"(.*?)"\s*\)?\s*$""") CMDS = {} +def string_escape(s): + # This used to do s.decode("string_escape") which isn't available on Python 3. + # Actually we only need to drop '\t' and '\n', so do this here. + return s.replace(r'\t', '').replace(r'\n', '') + def parse_c(name): cmd = None last = None - for line in file(name, 'r'): + for line in open(name, 'r'): x = HELP_START.match(line) if x: cmd = CMDS.setdefault(x.group(1), defaultdict(list)) @@ -50,14 +57,14 @@ def parse_c(name): last = cmd['h_pre'] else: last = cmd['h_post'] - last.append(x.group(1).decode("string_escape").strip()) + last.append(string_escape(x.group(1)).strip()) continue x = HELP_OPT.match(line) if x: last = cmd['h_opts'] last.append([ - x.group(1).decode("string_escape"), - x.group(2).decode("string_escape") + string_escape(x.group(1)), + string_escape(x.group(2)), ]) continue x = CMD_FUNC.match(line) @@ -68,12 +75,12 @@ def parse_c(name): x = CMD_DESC.match(line) if x: last = cmd['c_desc'] - last.append(x.group(1).decode("string_escape")) + last.append(string_escape(x.group(1))) continue x = CMD_OPTS.match(line) if x: last = cmd['c_opts'] - last.append(x.group(1).decode("string_escape")) + last.append(string_escape(x.group(1))) continue x = CMD_GROUP.match(line) if x: @@ -85,9 +92,9 @@ def parse_c(name): if last is None: raise Exception("Parse error in %s: %r" % (name, line)) if isinstance(last[-1], str): - last[-1] += x.group(1).decode("string_escape") + last[-1] += string_escape(x.group(1)) elif isinstance(last[-1], list): - last[-1][1] += x.group(1).decode("string_escape") + last[-1][1] += string_escape(x.group(1)) continue x = HELP_END.match(line) if x: @@ -163,7 +170,7 @@ for name, cmd in CMDS.items(): rst = gen_rst(name, cmd) group = cmd.get('c_group') if group is None: - print >> sys.stderr, "gen_commands: warning: using default group 'misc' for command '%s'" % name + print("gen_commands: warning: using default group 'misc' for command '%s'" % name, file=sys.stderr) group = ['misc'] subdir = os.path.join(sys.argv[2], group[0]) try: @@ -183,9 +190,8 @@ for name, cmd in CMDS.items(): except: pass hash_new = hashlib.sha1() - hash_new.update(rst) + hash_new.update(rst.encode('utf-8')) if hash_old.hexdigest() == hash_new.hexdigest(): continue - file(target, 'w').write(rst) - + open(target, 'w').write(rst) diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst index c021a4c743..6bea883115 100644 --- a/Documentation/user/barebox.rst +++ b/Documentation/user/barebox.rst @@ -53,7 +53,6 @@ variable and the cross compiler with the ``CROSS_COMPILE`` environment variable. Currently, ``ARCH`` must be one of: * arm -* blackfin * mips * nios2 * openrisc |