[PATCH 02/33] doc: boards: amlogic: update documentation for boot-flow
Christian Hewitt
christianshewitt at gmail.com
Mon Mar 20 12:45:38 CET 2023
Improve documentation.
Signed-off-by: Christian Hewitt <christianshewitt at gmail.com>
---
doc/board/amlogic/boot-flow.rst | 178 ++++++++++++++++----------------
1 file changed, 90 insertions(+), 88 deletions(-)
diff --git a/doc/board/amlogic/boot-flow.rst b/doc/board/amlogic/boot-flow.rst
index 2049672b1b..041297c512 100644
--- a/doc/board/amlogic/boot-flow.rst
+++ b/doc/board/amlogic/boot-flow.rst
@@ -3,132 +3,134 @@
Amlogic SoC Boot Flow
=====================
-The Amlogic SoCs have a pre-defined boot sequence in the SoC ROM code. Here are
-the possible boot sources of different SoC families supported by U-Boot:
+Amlogic SoCs follow a pre-defined boot sequence stored in SoC ROM code. The possible boot
+sequences of the different SoC families are:
-GX* & AXG family
+GX* & AXG Family
----------------
-+----------+--------------------+-------+-------+---------------+---------------+
-| | 1 | 2 | 3 | 4 | 5 |
-+==========+====================+=======+=======+===============+===============+
-| S905 | POC=0: SPI NOR | eMMC | NAND | SD Card | USB Device |
-| S905X | | | | | |
-| S905L | | | | | |
-| S905W | | | | | |
-| S912 | | | | | |
-+----------+--------------------+-------+-------+---------------+---------------+
-| S805X | POC=0: SPI NOR | eMMC | NAND | USB Device | - |
-| A113D | | | | | |
-| A113X | | | | | |
-+----------+--------------------+-------+-------+---------------+---------------+
++----------+-------------------+---------+---------+---------+---------+
+| | 1 | 2 | 3 | 4 | 5 |
++==========+===================+=========+=========+=========+=========+
+| S905 | POC=0: SPI NOR | eMMC | NAND | SD | USB |
+| S905D | | | | | |
+| S905L | | | | | |
+| S905W | | | | | |
+| S905X | | | | | |
+| S905Y | | | | | |
+| S912 | | | | | |
++----------+-------------------+---------+---------+---------+---------+
+| S805X | POC=0: SPI NOR | eMMC | NAND | USB | - |
+| A113D | | | | | |
+| A113X | | | | | |
++----------+-------------------+---------+---------+---------+---------+
POC pin: `NAND_CLE`
-Some boards provide a button to force USB BOOT which disables the eMMC clock signal
-to bypass the eMMC stage. Others have removable eMMC modules; removing the eMMC and
-SDCard will allow boot from USB.
+Some boards provide a button to force USB boot by disabling the eMMC clock signal and
+allowing the eMMC step to be bypassed. Others have removable eMMC modules; removing an
+eMMC module and SD card will allow boot from USB.
-An exception is the lafrite board (aml-s805x-xx) which has no SDCard slot and boots
-from SPI. The only ways to boot the lafrite board from USB are:
+An exception is the Libre Computer AML-S805X-XX (LaFrite) board which has no SD card
+slot and boots from SPI. Booting a LaFrite board from USB requires either:
- - Erase the first sectors of SPI NOR flash
- - Insert an HDMI boot plug forcing boot over USB
+ - Erasing the first sectors of SPI NOR flash
+ - Inserting an HDMI boot plug forcing boot over USB
-The VIM1 and initial VIM2 boards provide a test point on the eMMC signals to block
-the storage from answering and continue to the next boot step.
+The VIM1 and initial VIM2 boards provide a test point on the eMMC signals to block the
+storage from answering, allowing boot to continue with the next boot step.
-The USB Device boot uses the first USB interface. On some boards this port is only
-available on an USB-A type connector and needs an special Type-A to Type-A cable to
-communicate with the BootROM.
+USB boot uses the first USB interface. On some boards this port is only available on a
+USB-A type connector and requires a special Type-A to Type-A cable to communicate with
+the BootROM.
-G12* & SM1 family
+G12* & SM1 Family
-----------------
-+-------+-------+-------+---------------+---------------+---------------+---------------+
-| POC0 | POC1 | POC2 | 1 | 2 | 3 | 4 |
-+=======+=======+=======+===============+===============+===============+===============+
-| 0 | 0 | 0 | USB Device | SPI NOR | NAND/eMMC | SDCard |
-+-------+-------+-------+---------------+---------------+---------------+---------------+
-| 0 | 0 | 1 | USB Device | NAND/eMMC | SDCard | - |
-+-------+-------+-------+---------------+---------------+---------------+---------------+
-| 0 | 1 | 0 | SPI NOR | NAND/eMMC | SDCard | USB Device |
-+-------+-------+-------+---------------+---------------+---------------+---------------+
-| 0 | 1 | 1 | SPI NAND | NAND/eMMC | USB Device | - |
-+-------+-------+-------+---------------+---------------+---------------+---------------+
-| 1 | 0 | 0 | USB Device | SPI NOR | NAND/eMMC | SDCard |
-+-------+-------+-------+---------------+---------------+---------------+---------------+
-| 1 | 0 | 1 | USB Device | NAND/eMMC | SDCard | - |
-+-------+-------+-------+---------------+---------------+---------------+---------------+
-| 1 | 1 | 0 | SPI NOR | NAND/eMMC | SDCard | USB Device |
-+-------+-------+-------+---------------+---------------+---------------+---------------+
-| 1 | 1 | 1 | NAND/eMMC | SDCard | USB Device | - |
-+-------+-------+-------+---------------+---------------+---------------+---------------+
-
-The last option (1/1/1) is the normal default seen on production devices.
++-------+-------+-------+------------+------------+------------+-----------+
+| POC0 | POC1 | POC2 | 1 | 2 | 3 | 4 |
++=======+=======+=======+============+============+============+===========+
+| 0 | 0 | 0 | USB | SPI-NOR | NAND/eMMC | SD |
++-------+-------+-------+------------+------------+-------------+----------+
+| 0 | 0 | 1 | USB | NAND/eMMC | SD | - |
++-------+-------+-------+------------+------------+------------+-----------+
+| 0 | 1 | 0 | SPI-NOR | NAND/eMMC | SD | USB |
++-------+-------+-------+------------+------------+------------+-----------+
+| 0 | 1 | 1 | SPI-NAND | NAND/eMMC | USB | - |
++-------+-------+-------+------------+------------+------------+-----------+
+| 1 | 0 | 0 | USB | SPI-NOR | NAND/eMMC | SD |
++-------+-------+-------+------------+------------+------------+-----------+
+| 1 | 0 | 1 | USB | NAND/eMMC | SD | - |
++-------+-------+-------+------------+------------+------------+-----------+
+| 1 | 1 | 0 | SPI-NOR | NAND/eMMC | SD | USB |
++-------+-------+-------+------------+------------+------------+-----------+
+| 1 | 1 | 1 | NAND/eMMC | SD | USB | - |
++-------+-------+-------+------------+------------+------------+-----------+
+
+The last option (1/1/1) is the normal default seen on production devices:
* POC0 pin: `BOOT_4` (0 and all other 1 means SPI NAND boot first)
* POC1 pin: `BOOT_5` (0 and all other 1 means USB Device boot first
* POC2 pin: `BOOT_6` (0 and all other 1 means SPI NOR boot first)
Most boards provide a button to force USB BOOT which lowers `BOOT_5` to 0. Some boards
-provide a test point on the eMMC or SPI NOR clock signals to block the storage from
-answering and continue to the next boot step.
+provide a test point on eMMC or SPI NOR clock signals to block storage from answering
+and allowing boot to continue from the next boot step.
-The Khadas VIM3/3L boards embed a microcontroller which sets POC signals according
-to its configuration or a specific key press sequence to either boot from SPI NOR
-or eMMC then SDCard, or boot as an USB Device.
+The Khadas VIM3/3L boards embed a microcontroller which sets POC signals according to
+its configuration or a specific key press sequence to either boot from SPI NOR or eMMC
+then SD card, or boot as a USB device.
-The Odroid N2/N2+ has a hardware switch to select between SPI NOR or eMMC boot.
+The Odroid N2/N2+ has a hardware switch to select between SPI NOR or eMMC boot. The
+Odroid HC4 has a button to disable SPI-NOR allowing boot from SD card.
Boot Modes
----------
- * SDCard
+ * SD
-The BootROM fetches the first SDCard sectors in one sequence, then checks the content
-of the data. The BootROM expects to find the FIP binary in sector 1, 512 bytes offset
-from the start.
+The BootROM fetches the first SD card sectors in one sequence then checks the content of
+the data. It expects to find the FIP binary in sector 1, 512 bytes offset from the start.
* eMMC
-The BootROM fetches the first sectors in one sequence, first on the main partition,
-and then on the Boot0 followed by Boot1 HW partitions. After each read, the BootROM
-checks the data and looks to the next partition if it fails. The BootROM expects to
-find the FIP binary in sector 1, 512 bytes offset from the start.
+The BootROM fetches the first sectors of the main partition in one sequence then checks
+the content of the data. On GXL and newer boards it expects to find the FIP binary in
+sector 1, 512 bytes offset from the start. If not found it checks the boot0 partition,
+then the boot1 partition. On GXBB it expects to find the FIP binary at an offset that
+conflicts with MBR partition tables, but this has been worked around (thus avoiding the
+need for a partition scheme that relocates the MBR). For a more detailed explanation
+please see: https://github.com/LibreELEC/amlogic-boot-fip/pull/8
- * SPI NOR
+ * SPI-NOR
-The BootROM fetches the first SPI NOR sectors in one sequence, then checks the content
-of the data. The BootROM expects to find the FIP binary in sector 1, 512 bytes offset
-from the start.
+The BootROM fetches the first SPI NOR sectors in one sequence then checks the content of
+the data. It expects to find the FIP binary in sector 1, 512 bytes offset from the start.
- * NAND & SPI NAND
+ * NAND & SPI-NAND
These modes are rarely used in open platforms and no details are available.
- * USB Device
+ * USB
-The BootROM sets the USB Gadget interface to serve a custom USB protocol with the
-USB ID 1b8e:c003. The Amlogic `update` utility is designed to use this protocol. It
-is also implemented in the Amlogic Vendor U-Boot.
+The BootROM supports a custom USB protocol and sets the USB Gadget interface to use the
+USB ID 1b8e:c003. The Amlogic `update` utility uses this protocol. It is also supported
+in the Amlogic vendor U-Boot sources.
-The open-source `pyamlboot` utility https://github.com/superna9999/pyamlboot also
-implements this protocol and can load U-Boot in memory in order to start the SoC
-without any attached storage or to recover from a failed/incorrect image flash.
+The `pyamlboot` utility https://github.com/superna9999/pyamlboot is open-source and also
+implements the USB protocol. It can load U-Boot into memory to start the SoC without the
+storage being attached, or to recover the device from a failed/incorrect image flash.
-HDMI Recovery
--------------
+HDMI Recovery Dongle
+--------------------
-The BootROM also briefly reads 8 bytes at address I2C 0x52 offset 0xf8 (248) on the
-HDMI DDC bus. If the content is `boot at USB` it will force USB boot mode. If the content
-is `boot at SDC` it will force SDCard boot mode.
+The BootROM also reads 8 bytes at address I2C 0x52 offset 0xf8 (248) on the HDMI DDC bus
+during startup. The content `boot at USB` forces USB boot. The content `boot at SDC` forces SD
+card boot. The content `boot at SPI` forces SPI-NOT boot. If an SD card or USB device does
+not enumerate the BootROM continues with the normal boot sequence.
-If USB Device doesn't enumerate or SD Card boot step doesn't work, the BootROM will
-continue with the normal boot sequence.
+HDMI boot dongles can be created by connecting a 256bytes EEPROM set to answer on address
+0x52, with `boot at USB` or `boot at SDC` or `boot at SPI` programmed at offset 0xf8 (248).
-Special boot dongles can be built by connecting a 256bytes EEPROM set to answer on
-address 0x52, and program `boot at USB` or `boot at SDC` at offset 0xf8 (248).
-
-Note: If the SoC is booted with USB Device forced at first step, it will keep the boot
-order on warm reboot. Only cold reboot (power removed) will reset the boot order.
+If the SoC is booted with USB Device forced at first step, it will retain the forced boot
+order on warm reboot. Only cold reboot (removing power) will reset the boot order.
--
2.34.1
More information about the U-Boot
mailing list