Improve documentation.
Signed-off-by: Christian Hewitt christianshewitt@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@USB` it will force USB boot mode. If the content -is `boot@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@USB` forces USB boot. The content `boot@SDC` forces SD +card boot. The content `boot@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@USB` or `boot@SDC` or `boot@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@USB` or `boot@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.