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@xxxxxxxxxxxxxx> --- 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..739f9c40fb 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. +All 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@xxxxxxxxxxxxxxxxxxx http://lists.infradead.org/mailman/listinfo/barebox
