[PATCH] doc: imx: psb: Document usage of SRC_GPR10 PERSIST_SECONDARY_BOOT for A/B switching
Marek Vasut
marex at denx.de
Thu Mar 25 01:20:48 CET 2021
Document SRC_GPR10 PERSIST_SECONDARY_BOOT functionality. This is useful for
reliable bootloader A/B updates, as it permits switching between two copies
of bootloader at different offsets of the same storage. The switch happens
in case one copy is corrupted OR can be enforced by user. This functionality
is present at least since i.MX53, however is poorly documented in all known
SoC datasheets, hence this document aims to clarify the usage, currently on
i.MX7D and i.MX8MM.
Signed-off-by: Marek Vasut <marex at denx.de> # Original MX7D work, this document
Signed-off-by: Igor Opaniuk <igor.opaniuk at foundries.io> # All the MX8M work
Cc: Christoph Niedermaier <cniedermaier at dh-electronics.de>
Cc: Fabio Estevam <festevam at gmail.com>
Cc: Harald Seiler <hws at denx.de>
Cc: Igor Opaniuk <igor.opaniuk at foundries.io>
Cc: Jan Kiszka <jan.kiszka at siemens.com>
Cc: Ludwig Zenz <lzenz at dh-electronics.com>
Cc: Marcel Ziswiler <marcel.ziswiler at toradex.com>
Cc: Peng Fan <peng.fan at nxp.com>
Cc: Stefano Babic <sbabic at denx.de>
Cc: Ye Li <ye.li at nxp.com>
Cc: uboot-imx <uboot-imx at nxp.com>
---
NOTE: This all was pieced together from various scraps of information.
Links to further reading below.
- MX53/Vybrid
https://community.nxp.com/t5/Vybrid-Processors/Vybrid-secondary-image-table-format-for-redundant-boot-from-SD/m-p/487232/highlight/true#M5274
- MX53
https://community.nxp.com/t5/i-MX-Processors/i-MX53-Redundant-Boot-blog-archive/m-p/151804
- MX8M
https://community.nxp.com/t5/i-MX-Processors/i-MX-8M-Mini-eMMC-Boot-Fusing/m-p/1025730
- MX8M
https://review.trustedfirmware.org/plugins/gitiles/TF-A/trusted-firmware-a/+/73b99795e3bc480eeab9d2b892755b2ecaececde%5E%21/
---
doc/imx/index.rst | 9 +++
doc/imx/misc/index.rst | 9 +++
doc/imx/misc/psb.rst | 174 +++++++++++++++++++++++++++++++++++++++++
doc/index.rst | 11 +++
4 files changed, 203 insertions(+)
create mode 100644 doc/imx/index.rst
create mode 100644 doc/imx/misc/index.rst
create mode 100644 doc/imx/misc/psb.rst
diff --git a/doc/imx/index.rst b/doc/imx/index.rst
new file mode 100644
index 00000000000..b225b1d1837
--- /dev/null
+++ b/doc/imx/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+NXP i.MX Machine-specific doc
+=============================
+
+.. toctree::
+ :maxdepth: 2
+
+ misc/index
diff --git a/doc/imx/misc/index.rst b/doc/imx/misc/index.rst
new file mode 100644
index 00000000000..85fbdb6588f
--- /dev/null
+++ b/doc/imx/misc/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Miscellaneous
+=============
+
+.. toctree::
+ :maxdepth: 2
+
+ psb
diff --git a/doc/imx/misc/psb.rst b/doc/imx/misc/psb.rst
new file mode 100644
index 00000000000..bde6b1c0207
--- /dev/null
+++ b/doc/imx/misc/psb.rst
@@ -0,0 +1,174 @@
+i.MX7D/i.MX8MM SRC_GPR10 PERSIST_SECONDARY_BOOT for bootloader A/B switching
+============================================================================
+
+Introduction
+------------
+Since at least iMX53 until iMX8MM, it is possible to have two copies of
+bootloader in SD/eMMC and switch between them. The switch is triggered
+either by the BootROM in case the bootloader image is faulty OR can be
+enforced by the user.
+
+Operation
+---------
+ #. Upon Power-On Reset (POR)
+
+ - SRC_GPR10 bit PERSIST_SECONDARY_BOOT is set to 0
+ - BootROM attempts to start bootloader A-copy
+
+ - if A-copy valid
+
+ - BootROM starts A-copy
+ - END
+
+ - if A-copy NOT valid
+
+ - BootROM sets SRC_GPR10 bit PERSIST_SECONDARY_BOOT to 1
+ - BootROM triggers WARM reset, GOTO 1)
+ - END
+
+ #. Upon COLD Reset
+
+ - GOTO 1)
+ - END
+
+ #. Upon WARM Reset
+
+ - SRC_GPR10 bit PERSIST_SECONDARY_BOOT is retained
+
+ - if SRC_GPR10 bit PERSIST_SECONDARY_BOOT is 0
+
+ - BootROM attempts to start bootloader A-copy
+
+ - if A-copy valid
+
+ - BootROM starts A-copy
+ - END
+
+ - if A-copy NOT valid
+
+ - BootROM sets SRC_GPR10 bit PERSIST_SECONDARY_BOOT to 1
+ - BootROM triggers WARM reset. GOTO 1.3)
+ - END
+
+ - if SRC_GPR10 bit PERSIST_SECONDARY_BOOT is 1
+
+ - BootROM attempts to start bootloader B-copy
+
+ - if B-copy valid
+
+ - BootROM starts B-copy
+ - END
+
+ - if B-copy NOT valid
+ - System hangs
+ - END
+
+Setup
+-----
+The bootloader A-copy must be placed at predetermined offset in SD/eMMC. The
+bootloader B-copy area offset is determined by an offset stored in Secondary
+Image Table (SIT). The SIT must be placed at predetermined offset in SD/eMMC.
+
+The following table contains offset of SIT, bootloader A-copy and recommended
+bootloader B-copy offset. The offsets are in 512 Byte sector units (that is
+offset 0x1 means 512 Bytes from the start of SD/eMMC card data partition).
+For details on the addition of two numbers in recommended B-copy offset, see
+SIT format below.
+
++----------+--------------------+-----------------------+-----------------------------+
+| SoC | SIT offset (fixed) | A-copy offset (fixed) | B-copy offset (recommended) |
++----------+--------------------+-----------------------+-----------------------------+
+| iMX7D | 0x1 | 0x2 | 0x800+0x2 |
++----------+--------------------+-----------------------+-----------------------------+
+| iMX8MM | 0x41 | 0x42 | 0x1000+0x42 |
++----------+--------------------+-----------------------+-----------------------------+
+
+SIT format
+~~~~~~~~~~
+SIT is a 20 byte long structure containing of 5 32-bit words. Those encode
+bootloader B-copy area offset (called "firstSectorNumber"), magic value
+(called "tag") that is always 0x00112233, and three unused words set to 0.
+SIT is documented in [1] and [2]. Example SIT are below::
+
+ $ hexdump -vC sit-mx7d.bin
+ 00000000 00 00 00 00
+ 00000004 00 00 00 00
+ 00000008 33 22 11 00 <--- This is the "tag"
+ 0000000c 00 08 00 00 <--- This is the "firstSectorNumber"
+ 00000010 00 00 00 00
+
+ $ hexdump -vC sit-mx8mm.bin
+ 00000000 00 00 00 00
+ 00000004 00 00 00 00
+ 00000008 33 22 11 00 <--- This is the "tag"
+ 0000000c 00 10 00 00 <--- This is the "firstSectorNumber"
+ 00000010 00 00 00 00
+
+B-copy area offset ("firstSectorNumber") is offset, in units of 512 Byte
+sectors, that is added to the start of boot media when switching between
+A-copy and B-copy. For A-copy, this offset is 0x0. For B-copy, this offset
+is determined by SIT (e.g. if firstSectorNumber is 0x1000 as it is above
+in sit-mx8mm.bin, then the B-copy offset is 0x1000 sectors = 2 MiB).
+
+Bootloader A-copy (e.g. u-boot.imx or flash.bin) is placed at fixed offset
+from A-copy area offset (e.g. 0x2 sectors from sector 0x0 for iMX7D, which
+means u-boot.imx A-copy must be written to sector 0x2).
+
+The same applies to bootloader B-copy, which is placed at fixed offset from
+B-copy area offset determined by SIT (e.g. 0x2 sectors from sector 0x800 [see
+sit-mx7d.bin example above, this can be changed in SIT firstSectorNumber] for
+iMX7D, which means u-boot.imx B-copy must be written to sector 0x802)
+
+**WARNING:**
+B-copy area offset ("firstSectorNumber") is NOT equal to bootloader
+(image, which is u-boot.imx or flash.bin) B-copy offset.
+
+To generate SIT, use for example the following bourne shell printf command::
+
+$ printf '\x0\x0\x0\x0\x0\x0\x0\x0\x33\x22\x11\x00\x00\x08\x00\x00\x0\x0\x0\x0' > sit-mx7d.bin
+$ printf '\x0\x0\x0\x0\x0\x0\x0\x0\x33\x22\x11\x00\x00\x10\x00\x00\x0\x0\x0\x0' > sit-mx8mm.bin
+
+Write bootloader A/B copy and SIT to SD/eMMC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Examples of writing SIT and two copies of bootloader to SD or eMMC:
+
+- iMX8MM, SD card at /dev/sdX, Linux command line
+ ::
+
+ $ dd if=sit-mx8mm.bin of=/dev/sdX bs=512 seek=65
+ $ dd if=flash.bin of=/dev/sdX bs=512 seek=66
+ $ dd if=flash.bin of=/dev/sdX bs=512 seek=4162
+
+- iMX8MM, eMMC 1 data partition, U-Boot command line
+ ::
+
+ => mmc partconf 1 0 0 0
+
+ => dhcp ${loadaddr} sit-mx8mm.bin
+ => mmc dev 1
+ => mmc write ${loadaddr} 0x41 0x1
+
+ => dhcp ${loadaddr} flash.bin
+ => setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt
+ => mmc dev 1
+ => mmc write ${loadaddr} 0x42 ${blkcnt}
+ => mmc write ${loadaddr} 0x1042 ${blkcnt}
+
+WARM reset into B-copy using WDT
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To perform a reboot into B-copy, the PERSIST_SECONDARY_BOOT must be set
+in SRC_GPR0 register. Example on iMX8MM::
+
+ => mw 0x30390098 0x40000000
+
+A WARM reset can be triggered using WDT as follows::
+
+ => mw.w 0x30280000 0x25
+
+References
+----------
+
+.. [1] i.MX 7Dual Applications Processor Reference Manual, Rev. 1, 01/2018 ; section 6.6.5.3.5 Redundant boot support for expansion device
+.. [2] i.MX 8M Mini Applications Processor Reference Manual, Rev. 3, 11/2020 ; section 6.1.5.4.5 Redundant boot support for expansion device
diff --git a/doc/index.rst b/doc/index.rst
index 4c44955d67f..5d5bb73846c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -87,6 +87,17 @@ implementation.
arch/index
+Machine-specific doc
+--------------------
+
+These books provide programming details about machine-specific
+implementation.
+
+.. toctree::
+ :maxdepth: 2
+
+ imx/index
+
Board-specific doc
------------------
--
2.30.2
More information about the U-Boot
mailing list