[PATCH v3 14/14] Documentation: MXS: general update and improvements

[Roland Hieber <r.hieber@pengutronix.de>]

Go more into detail about the relationship of the prepare stage and the
bootloader image, and about the generated images. Also don't use
mxs-usb-loader anymore since it has been removed.

Fixes: 3ca576cc4a4236a2556ab17 "scripts: imx/mxs remove mxs-usb-loader"
Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
---
 Documentation/boards/mxs.rst | 97 ++++++++++++++++++++----------------
 1 file changed, 53 insertions(+), 44 deletions(-)

diff --git a/Documentation/boards/mxs.rst b/Documentation/boards/mxs.rst
index feb024227a..53de4c1096 100644
--- a/Documentation/boards/mxs.rst
+++ b/Documentation/boards/mxs.rst
@@ -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 barebox.
+and thus are represented by their own architecture in both the kernel
+and in barebox.
 
 Bootlets
 --------
 
-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
 documentation instead.
 
-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
-the partition::
+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 **
+.. 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
 --------------------
-- 
2.18.0


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox