|author||Sascha Hauer <email@example.com>||2018-09-11 17:23:33 +0200|
|committer||Sascha Hauer <firstname.lastname@example.org>||2018-09-11 17:23:33 +0200|
Merge branch 'for-next/mxs'
Diffstat (limited to 'Documentation')
1 files changed, 53 insertions, 44 deletions
diff --git a/Documentation/boards/mxs.rst b/Documentation/boards/mxs.rst
index feb0242..53de4c1 100644
@@ -3,71 +3,83 @@ Freescale MXS
Freescale i.MXs or MXS are a SoC family which consists of the i.MX23
and the i.MX28. These are quite different from the regular i.MX SoCs
-and thus are represented by their own architecture in both the Kernel
+and thus are represented by their own architecture in both the kernel
+and in barebox.
-Traditionally These SoCs need the Freescale bootlets source and the
-elf2sb2 binary to build a bootable image out of the barebox binary.
-Since the bootlets are board specific and the source code is only
-hardly customisable each vendor usually has his own slightly different
+Traditionally these SoCs need the Freescale bootlets source and the
+*elf2sb2* binary to set up the PMIC and SDRAM, and to build a bootable
+image out of the barebox binary.
+Since the bootlets are board-specific and the source code is only
+hardly customisable, each vendor usually has their own slightly different
version of the bootlets. Booting with the Freescale bootlets is not
-described here, refer to the bootlet sourcecode or your vendors
+described here, refer to the bootlet source code or your vendor's
-U-Boot and barebox have a port of the bootlets integrated into their
-source. The barebox bootlet code is derived from the U-Boot bootlet
-code written by Marek Vasut.
+Barebox has a port of the bootlets integrated into its source, which is
+derived from the U-Boot bootlet code written by Marek Vasut.
-Currently only the Karo TX28 is supported by the barebox bootlets,
-but we recommend that this approach should be followed for new boards
-and existing boards should be ported over.
+Most MXS boards in the barebox tree have been ported to use barebox bootlets and
+image generation, and we recommend this approach for new boards too.
Booting Freescale i.MXs
The Freescale MXS SoCs have a multi staged boot process which needs
different images composed out of different binaries. The ROM executes
-a so called bootstream which contains multiple executables. The first
-one is executed in SRAM and the purpose of this binary is to setup
-the internal PMIC and the SDRAM. The second image is usually the
-bootloader itself. In case of barebox the bootstream is composed
-out of the self extracting barebox image (pblx) and the prepare
-stage for setting up the SDRAM.
+a so called *bootstream* which can contain multiple executables.
+The first executable (the prepare stage) is only a small binary executed in
+SRAM, which has a limited size of 128 KB. Its purpose is to setup the internal
+PMIC and the SDRAM, and then jump back to the MXS ROM code, which then maps the
+second executable (the full bootloader) into SDRAM and executes it.
+In case of barebox, the bootstream (``*-bootstream.img``) is composed of the
+self extracting barebox image (``*.pblx``) and the prepare stage
+(``prep_*.pblb``). The file name of those images reflects the name of the
+respective entry points.
The bootstream image itself is useful for USB boot, but for booting from
SD cards or NAND a BCB header has to be prepended to the image. In case
-of SD boot the image has the .mxssd file extension in barebox.
+of SD boot the image is named ``*-sd.img``.
+Bootstream images can be unencrypted or encrypted. Depending on the OCOTP fuses
+of your chip, you might need the one or the other to boot the board.
-Since the bootstream images are encrypted they are not suitable for
-2nd stage execution. For this purpose the 2nd stage images are generated.
+Since some of the bootstream images are encrypted, they are not suitable for
+2nd stage execution. For this purpose a 2nd stage image with the name
+``*-2nd.img`` is generated.
Booting from USB
-barebox has the mxs-usb-loader tool (derived from the sbloader tool from
-the rockbox project). If the board is connected to the PC and started in
-USB Boot mode it should show up in lsusb::
+If enabled in *menuconfig* → *System Type*, barebox builds the *imx-usb-loader*
+tool (derived from the *sbloader* tool from the rockbox project), which can
+load images onto MXS SoCs over USB. (Refer to the documentation of your board
+how to get it into USB boot mode.)
+If the board is connected to the PC and started in USB boot mode, it should
+show up in lsusb::
Bus 001 Device 098: ID 15a2:004f Freescale Semiconductor, Inc. i.MX28 SystemOnChip in RecoveryMode
-The bootstream images can be directly booted with::
+The bootstream images can then directly be booted with::
- ./scripts/mxs-usb-loader 0 images/barebox-karo-tx28-bootstream.img
+ ./scripts/imx-usb-loader images/barebox-karo-tx28-bootstream.img
-You might require appropriate udev rules or sudo to gain the rights to
+You might require appropriate udev rules or *sudo* to gain the rights to
access the USB device.
Booting from SD cards
-The SD images are suitable for booting from SD cards. SD cards need a special
-partitioning which can be created with the following fdisk sequence (using
-/dev/sdg as example)::
+The SD images are suitable for booting from SD cards. The MXS SoCs require a
+special partition of type 0x53 (OnTrack DM6 Aux) which contains the BCB header.
+The partitioning can be created with the following fdisk sequence (using
+*/dev/sdg* as an example for the SD card)::
- fdisk /dev/sdg
+ $ fdisk /dev/sdg
Welcome to fdisk (util-linux 2.25.1).
Changes will remain in memory only, until you decide to write them.
@@ -93,24 +105,21 @@ partitioning which can be created with the following fdisk sequence (using
Hex code (type L to list all codes): 53
Changed type of partition 'Linux' to 'OnTrack DM6 Aux3'.
- Command (m for help):
Command (m for help): w
-After writing the new partition table the image can be written directly to
+After writing the new partition table, the image can be written directly to
+the first partition::
cat images/barebox-karo-tx28-sd.img > /dev/sdg1
-** NOTE **
-The MXS SoCs require a special partition of type 0x53 (OnTrack DM6 Aux)
-which contains the BCB header. For some unknown reason the BCB header is
-inside a partition, but contains the sector number of the raw device from
-which the rest of the image is read. With standard settings booting from
-SD card only works if the partition containing the bootloader starts at
-sector 2048 (the standard for fdisk). See the -p parameter to the mxsboot
-tool which changes this sector number in the image.
+ For some unknown reason the BCB header is
+ inside a partition, but contains the sector number of the raw device from
+ which the rest of the image is read. With standard settings, booting from
+ SD card only works if the partition containing the bootloader starts at
+ sector 2048 (the standard for fdisk). See the *-p* parameter to the
+ ``scripts/mxsboot`` tool to change this sector number in the image.
Booting second stage