[PATCH v2] Documentation: i.MX8M: add EVK barebox installation documentation

[PATCH v2] Documentation: i.MX8M: add EVK barebox installation documentation

[Ahmad Fatoum]

The barebox i.MX images have a preamble that pads the i.MX header to
the offset expected by the BootROM. This allows writing barebox images
directly to offset 0 on SD-Cards and eMMC user area. For some i.MX8M,
these images can't be directly written to eMMC boot partitions and
instead require special handling. Add a note about this to the
documentation.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
v1 -> v2:
  - Fix typo, s/as an/at an/ (Ulrich)
  - Fix typo, s/Power-fail installation/Power-fail-safe installation/ (Sascha)
---
 Documentation/boards/imx/nxp-imx8mm-evk.rst | 18 ++++++++++++++++
 Documentation/boards/imx/nxp-imx8mn-evk.rst | 24 +++++++++++++++++++++
 Documentation/boards/imx/nxp-imx8mp-evk.rst | 24 +++++++++++++++++++++
 3 files changed, 66 insertions(+)

diff --git a/Documentation/boards/imx/nxp-imx8mm-evk.rst b/Documentation/boards/imx/nxp-imx8mm-evk.rst
index c3cd35ae38a2..f0dfc53ed070 100644
--- a/Documentation/boards/imx/nxp-imx8mm-evk.rst
+++ b/Documentation/boards/imx/nxp-imx8mm-evk.rst
@@ -69,3 +69,21 @@ board for serial download mode as printed on the PCB. You can start barebox with
 the imx-usb-loader tool that comes with barebox like this:
 
 ./scripts/imx/imx-usb-loader images/barebox-nxp-imx8mm-evk.img
+
+Installing barebox
+==================
+
+When the EVK is strapped to boot from eMMC, the i.MX8M bootrom will
+consult the eMMC ext_csd register to determine whether to boot
+from the active eMMC boot partition or from the user area.
+
+The same barebox image written to the start of the SD-Card can
+be written to the start of the eMMC user area. Power-fail-safe
+installation to the eMMC boot partition requires special handling:
+
+  - The barebox image must be written to the inactive boot partition,
+    then afterwards, the newly written boot partition is activated
+    (This is controlled by the barebox ``mmcX.boot`` variable).
+
+The ``barebox_update`` command takes care of this and need just be
+supplied a barebox image as argument.
diff --git a/Documentation/boards/imx/nxp-imx8mn-evk.rst b/Documentation/boards/imx/nxp-imx8mn-evk.rst
index b920e22d33e9..177fc59c1085 100644
--- a/Documentation/boards/imx/nxp-imx8mn-evk.rst
+++ b/Documentation/boards/imx/nxp-imx8mn-evk.rst
@@ -58,3 +58,27 @@ Build barebox
 
  make imx_v8_defconfig
  make
+
+Installing barebox
+==================
+
+When the EVK is strapped to boot from eMMC, the i.MX8M bootrom will
+consult the eMMC ext_csd register to determine whether to boot
+from the active eMMC boot partition or from the user area.
+
+The same barebox image written to the start of the SD-Card can
+be written to the start of the eMMC user area. Power-fail-safe
+installation to the eMMC boot partition requires special handling:
+
+  - The barebox image must be written to the inactive boot partition,
+    then afterwards, the newly written boot partition is activated
+    (This is controlled by the barebox ``mmcX.boot`` variable).
+
+  - The barebox image includes a 32KiB preamble that allows the image
+    to be directly writable to the start of the SD-Card or eMMC user area.
+    Unlike older i.MX8M, the i.MX8MN BootROM expects the bootloader to not
+    start at an offset when booting from eMMC boot partitions, thus the first
+    32KiB must be stripped.
+
+The ``barebox_update`` command takes care of this and need just be
+supplied a barebox image as argument.
diff --git a/Documentation/boards/imx/nxp-imx8mp-evk.rst b/Documentation/boards/imx/nxp-imx8mp-evk.rst
index 1074992f2f88..53cdd904ab0e 100644
--- a/Documentation/boards/imx/nxp-imx8mp-evk.rst
+++ b/Documentation/boards/imx/nxp-imx8mp-evk.rst
@@ -66,3 +66,27 @@ Boot Configuration
 The NXP i.MX8MP-EVK board has four switches responsible for configuring
 bootsource/boot mode. The settings for the different boot sources are
 printed on the board.
+
+Installing barebox
+==================
+
+When the EVK is strapped to boot from eMMC, the i.MX8M bootrom will
+consult the eMMC ext_csd register to determine whether to boot
+from the active eMMC boot partition or from the user area.
+
+The same barebox image written to the start of the SD-Card can
+be written to the start of the eMMC user area. Power-fail-safe
+installation to the eMMC boot partition requires special handling:
+
+  - The barebox image must be written to the inactive boot partition,
+    then afterwards, the newly written boot partition is activated
+    (This is controlled by the barebox ``mmcX.boot`` variable).
+
+  - The barebox image includes a 32KiB preamble that allows the image
+    to be directly writable to the start of the SD-Card or eMMC user area.
+    Unlike older i.MX8M, the i.MX8MP BootROM expects the bootloader to not
+    start at an offset when booting from eMMC boot partitions, thus the first
+    32KiB must be stripped.
+
+The ``barebox_update`` command takes care of this and need just be
+supplied a barebox image as argument.
-- 
2.30.2

Re: [PATCH v2] Documentation: i.MX8M: add EVK barebox installation documentation

[Sascha Hauer]

On Fri, Feb 17, 2023 at 02:21:40PM +0100, Ahmad Fatoum wrote:
> The barebox i.MX images have a preamble that pads the i.MX header to
> the offset expected by the BootROM. This allows writing barebox images
> directly to offset 0 on SD-Cards and eMMC user area. For some i.MX8M,
> these images can't be directly written to eMMC boot partitions and
> instead require special handling. Add a note about this to the
> documentation.
> 
> Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
> ---
> v1 -> v2:
>   - Fix typo, s/as an/at an/ (Ulrich)
>   - Fix typo, s/Power-fail installation/Power-fail-safe installation/ (Sascha)
> ---
>  Documentation/boards/imx/nxp-imx8mm-evk.rst | 18 ++++++++++++++++
>  Documentation/boards/imx/nxp-imx8mn-evk.rst | 24 +++++++++++++++++++++
>  Documentation/boards/imx/nxp-imx8mp-evk.rst | 24 +++++++++++++++++++++
>  3 files changed, 66 insertions(+)

Applied, thanks

Sascha

> 
> diff --git a/Documentation/boards/imx/nxp-imx8mm-evk.rst b/Documentation/boards/imx/nxp-imx8mm-evk.rst
> index c3cd35ae38a2..f0dfc53ed070 100644
> --- a/Documentation/boards/imx/nxp-imx8mm-evk.rst
> +++ b/Documentation/boards/imx/nxp-imx8mm-evk.rst
> @@ -69,3 +69,21 @@ board for serial download mode as printed on the PCB. You can start barebox with
>  the imx-usb-loader tool that comes with barebox like this:
>  
>  ./scripts/imx/imx-usb-loader images/barebox-nxp-imx8mm-evk.img
> +
> +Installing barebox
> +==================
> +
> +When the EVK is strapped to boot from eMMC, the i.MX8M bootrom will
> +consult the eMMC ext_csd register to determine whether to boot
> +from the active eMMC boot partition or from the user area.
> +
> +The same barebox image written to the start of the SD-Card can
> +be written to the start of the eMMC user area. Power-fail-safe
> +installation to the eMMC boot partition requires special handling:
> +
> +  - The barebox image must be written to the inactive boot partition,
> +    then afterwards, the newly written boot partition is activated
> +    (This is controlled by the barebox ``mmcX.boot`` variable).
> +
> +The ``barebox_update`` command takes care of this and need just be
> +supplied a barebox image as argument.
> diff --git a/Documentation/boards/imx/nxp-imx8mn-evk.rst b/Documentation/boards/imx/nxp-imx8mn-evk.rst
> index b920e22d33e9..177fc59c1085 100644
> --- a/Documentation/boards/imx/nxp-imx8mn-evk.rst
> +++ b/Documentation/boards/imx/nxp-imx8mn-evk.rst
> @@ -58,3 +58,27 @@ Build barebox
>  
>   make imx_v8_defconfig
>   make
> +
> +Installing barebox
> +==================
> +
> +When the EVK is strapped to boot from eMMC, the i.MX8M bootrom will
> +consult the eMMC ext_csd register to determine whether to boot
> +from the active eMMC boot partition or from the user area.
> +
> +The same barebox image written to the start of the SD-Card can
> +be written to the start of the eMMC user area. Power-fail-safe
> +installation to the eMMC boot partition requires special handling:
> +
> +  - The barebox image must be written to the inactive boot partition,
> +    then afterwards, the newly written boot partition is activated
> +    (This is controlled by the barebox ``mmcX.boot`` variable).
> +
> +  - The barebox image includes a 32KiB preamble that allows the image
> +    to be directly writable to the start of the SD-Card or eMMC user area.
> +    Unlike older i.MX8M, the i.MX8MN BootROM expects the bootloader to not
> +    start at an offset when booting from eMMC boot partitions, thus the first
> +    32KiB must be stripped.
> +
> +The ``barebox_update`` command takes care of this and need just be
> +supplied a barebox image as argument.
> diff --git a/Documentation/boards/imx/nxp-imx8mp-evk.rst b/Documentation/boards/imx/nxp-imx8mp-evk.rst
> index 1074992f2f88..53cdd904ab0e 100644
> --- a/Documentation/boards/imx/nxp-imx8mp-evk.rst
> +++ b/Documentation/boards/imx/nxp-imx8mp-evk.rst
> @@ -66,3 +66,27 @@ Boot Configuration
>  The NXP i.MX8MP-EVK board has four switches responsible for configuring
>  bootsource/boot mode. The settings for the different boot sources are
>  printed on the board.
> +
> +Installing barebox
> +==================
> +
> +When the EVK is strapped to boot from eMMC, the i.MX8M bootrom will
> +consult the eMMC ext_csd register to determine whether to boot
> +from the active eMMC boot partition or from the user area.
> +
> +The same barebox image written to the start of the SD-Card can
> +be written to the start of the eMMC user area. Power-fail-safe
> +installation to the eMMC boot partition requires special handling:
> +
> +  - The barebox image must be written to the inactive boot partition,
> +    then afterwards, the newly written boot partition is activated
> +    (This is controlled by the barebox ``mmcX.boot`` variable).
> +
> +  - The barebox image includes a 32KiB preamble that allows the image
> +    to be directly writable to the start of the SD-Card or eMMC user area.
> +    Unlike older i.MX8M, the i.MX8MP BootROM expects the bootloader to not
> +    start at an offset when booting from eMMC boot partitions, thus the first
> +    32KiB must be stripped.
> +
> +The ``barebox_update`` command takes care of this and need just be
> +supplied a barebox image as argument.
> -- 
> 2.30.2
> 
> 
> 

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |