mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Roland Hieber <r.hieber@pengutronix.de>
To: barebox@lists.infradead.org
Cc: Roland Hieber <r.hieber@pengutronix.de>
Subject: [PATCH v2 14/14] Documentation: MXS: general update and improvements
Date: Fri, 10 Aug 2018 18:35:00 +0200	[thread overview]
Message-ID: <20180810163500.12042-15-r.hieber@pengutronix.de> (raw)
In-Reply-To: <20180810163500.12042-1-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

      parent reply	other threads:[~2018-08-10 16:35 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-08-10 16:34 [PATCH v2 00/14] MXS low-level improvements Roland Hieber
2018-08-10 16:34 ` [PATCH v2 01/14] scripts: mxsimage: Allow unencrypted images Roland Hieber
2018-08-10 16:34 ` [PATCH v2 02/14] images: MXS: allow generation of unencrypted bootstreams Roland Hieber
2018-08-10 16:34 ` [PATCH v2 03/14] ARM: MXS: i.MX28: allow setup of low-voltage SDRAM Roland Hieber
2018-08-10 16:34 ` [PATCH v2 04/14] ARM: MXS: allow configuration of EMI clock prescaler Roland Hieber
2018-08-10 16:34 ` [PATCH v2 05/14] ARM: i.MX28: Add memory size detection Roland Hieber
2018-08-10 16:34 ` [PATCH v2 06/14] ARM: i.MX23: " Roland Hieber
2018-08-10 19:14   ` Andrey Smirnov
2018-08-10 16:34 ` [PATCH v2 07/14] ARM: MXS: refactor mx2*_power_init source configuration Roland Hieber
2018-08-10 19:29   ` Andrey Smirnov
2018-08-13 13:04     ` Roland Hieber
2018-08-10 16:34 ` [PATCH v2 08/14] ARM: MXS: allow starting from battery input without 4P2 source enabled Roland Hieber
2018-08-10 16:34 ` [PATCH v2 09/14] ARM: MXS: make power levels configurable in mx2*_power_init Roland Hieber
2018-08-10 16:34 ` [PATCH v2 10/14] ARM: MXS: fix VDDx brownout setup logic Roland Hieber
2018-08-10 16:34 ` [PATCH v2 11/14] ARM: MXS: make VDDx brownout setup more understandable Roland Hieber
2018-08-10 16:34 ` [PATCH v2 12/14] ARM: MXS: mxs_power_status: use less magic values Roland Hieber
2018-08-10 16:34 ` [PATCH v2 13/14] ARM: MXS: mxs_power_status: align output Roland Hieber
2018-08-10 16:35 ` Roland Hieber [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20180810163500.12042-15-r.hieber@pengutronix.de \
    --to=r.hieber@pengutronix.de \
    --cc=barebox@lists.infradead.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox