[PATCH] doc: imx: psb: Document usage of SRC_GPR10 PERSIST_SECONDARY_BOOT for A/B switching
Peng Fan (OSS)
peng.fan at oss.nxp.com
Thu Mar 25 12:00:50 CET 2021
On 2021/3/25 8:20, Marek Vasut wrote:
> 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>
Reviewed-by: Peng Fan <peng.fan 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
> ------------------
>
>
More information about the U-Boot
mailing list