Skip to content

fix(snagboot): update snagboot documentation. #384

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jeevantelukula merged 1 commit into from
Jul 17, 2025
Merged

fix(snagboot): update snagboot documentation. #384

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added source/images/snagfactory.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
217 changes: 210 additions & 7 deletions source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,20 @@
* More info about installation can be found in `Snagfactory Readme <https://github.com/bootlin/snagboot/blob/main/README.md>`__.
* Snagfactory also is available on pip.

.. code-block:: console
.. code-block:: console

$ python3 -m pip install --user snagboot
$ python3 -m pip install --user snagboot
$ python3 -m pip install --user snagboot[gui]

.. note::

At the time of 11.0 release, the corresponding Snagfactory version was v2.2.
At the time of 11.1 release, the corresponding Snagfactory version was v2.3.

.. ifconfig:: CONFIG_part_variant in ('AM62DX')

.. note::

AM62DX support was added after v2.3. Refer this `commit <https://github.com/bootlin/snagboot/commit/d5a691b1916207ee674e99620c63cc3a6c3b3a28>`__.

*****************************************
Building bootloader binaries for Recovery
Expand Down Expand Up @@ -87,6 +94,14 @@

BOOT_MACHINE_A53=am62px_evm_a53_defconfig am62x_a53_usbdfu.config am6x_a53_snagfactory.config

.. ifconfig:: CONFIG_part_variant in ('AM62DX')

.. code-block:: make

UBOOT_MACHINE_R5=am62dx_evm_r5_defconfig am62x_r5_usbdfu.config

BOOT_MACHINE_A53=am62dx_evm_a53_defconfig am62x_a53_usbdfu.config am6x_a53_snagfactory.config

Generate the bootloader images using top-level makefile by running following
commands on the terminal from the top-level of the Linux SDK installer.

Expand Down Expand Up @@ -115,18 +130,206 @@

* Power off the EVM and set up the boot mode switches to boot from USB DFU.

.. code-block:: text
.. code-block:: text

SW2-11001100
SW3-00000000
SW2-11001100
SW3-00000000

* Power on the board.
* Optionally you can also connect host PC to board via UART to read the console logs.

How to use Snagfactory
**********************

Comprehensive instructions for using the Snagfactory tool can be found here.
Comprehensive instructions for installation of the Snagfactory tool are here:

* `Snagfactory doc <https://github.com/bootlin/snagboot/blob/main/docs/snagfactory.md>`__.
* `Snagfactory config doc <https://github.com/bootlin/snagboot/blob/main/docs/snagfactory_config.md>`__.


**SnagFactory GUI Tool Configuration and Device Flashing Procedure**

The tool currently supports MMC and MTD backends for flashing images.

Check warning on line 152 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'MTD') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'MTD') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 152, "column": 37}}}, "severity": "INFO"}

Check warning on line 152 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'MMC') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'MMC') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 152, "column": 29}}}, "severity": "INFO"}

.. note::

SnagFactory GUI tool is a prerequisite for this procedure.

The following steps outline the process for configuring and flashing a device by using
the SnagFactory GUI tool.

.. figure:: /images/snagfactory.png
:height: 500
:width: 800

**Step 1: Launch SnagFactory GUI Tool**

* Launch the SnagFactory GUI tool to begin the configuration and device flashing process.

.. code-block:: console

$ snagfactory

**Step 2: Select Configuration File Option**

* Upon launch, the SnagFactory GUI tool will present the option to add a configuration file.
Select the conf option to proceed with loading the configuration file.

**Step 3: Load YAML Configuration File**

* Load the YAML configuration file for the platform. This file has the necessary settings
and parameters for the device flashing process.

**Step 4: Flash the Device**

* Once you load the YAML configuration file, the SnagFactory GUI tool will flash the device with
the specified configuration.

The example configuration files for **emmc** and **ospi-nand** and **ospi-nor** are as follows.

Check warning on line 188 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'emmc'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'emmc'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 188, "column": 39}}}, "severity": "WARNING"}

For reference, the :file:`ospi-nor.yaml` file for **am62p** platform can be as follows:

.. code-block:: text

boards:
0451:6165: am62p
soc-models:
am62p-firmware:
tiboot3:
path: "<path_to_boot_binaries>/tiboot3.bin"
tispl:
path: "<path_to_boot_binaries>/tispl.bin"
u-boot:
path: "<path_to_boot_binaries>/u-boot.img"
am62p-tasks:
- eraseblk-size: 0x40000
fb-buffer-addr: 0x82000000
fb-buffer-size: 0x7000000
target-device: nor0
- task: run
args:
- "oem_run:mtd list"
- "oem_run:setenv mtdids nor0=nor0"
- task: mtd-parts
args:
- name: ospi.tiboot3
size: 0x80000
- name: ospi.tispl
size: 0x200000
- name: ospi.u-boot
size: 0x400000
- task: flash
args:
- image: "<path_to_flash_binaries>/tiboot3.bin"
part: ospi.tiboot3
- image: "<path_to_flash_binaries>/tispl.bin"
part: ospi.tispl
- image: "<path_to_flash_binaries>/u-boot.img"
part: ospi.u-boot

For reference, the :file:`ospi-nand.yaml` file for **am62xx-lp** platform can be as follows:

.. code-block:: text

boards:
0451:6165: am625
soc-models:
am625-firmware:
tiboot3:
path: "<path_to_boot_binaries>/tiboot3.bin"
tispl:
path: "<path_to_boot_binaries>/tispl.bin"
u-boot:
path: "<path_to_boot_binaries>/u-boot.img"
am625-tasks:
- eraseblk-size: 0x40000
fb-buffer-addr: 0x82000000
fb-buffer-size: 0x7000000
target-device: spi-nand0
- task: run
args:
- "oem_run:mtd list"
- "oem_run:setenv mtdids spi-nand0=spi-nand0"
- task: mtd-parts
args:
- name: ospi_nand.tiboot3
size: 0x80000
- name: ospi_nand.tispl
size: 0x200000
- name: ospi_nand.u-boot
size: 0x400000
- name: ospi_nand.env
size: 0x40000
- name: ospi_nand.env.backup
size: 0x40000
- name: ospi_nand.rootfs
size: 0x5fc0000
start: 0x2000000
- name: ospi_nand.phypattern
start: 0x7fc0000
size: 0x40000
- task: flash
args:
- image: "<path_to_flash_binaries>/tiboot3.bin"
part: ospi_nand.tiboot3
- image: "<path_to_flash_binaries>/tispl.bin"
part: ospi_nand.tispl
- image: "<path_to_flash_binaries>/u-boot.img"
part: ospi_nand.u-boot

For reference, the :file:`emmc.yaml` file for **am62p** platform can be as follows:

.. code-block:: text

boards:
"0451:6165": "am62p"
soc-models:
am62p-firmware:
tiboot3:
path: "<path_to_boot_binaries>/tiboot3.bin"
tispl:
path: "<path_to_boot_binaries>/tispl.bin"
u-boot:
path: "<path_to_boot_binaries>/u-boot.img"
am62p-tasks:
- target-device: mmc0
fb-buffer-addr: 0x82000000
fb-buffer-size: 0x7000000
- task: gpt
args:
- name: rootfs
size: 1G
- task: reset
- task: flash
args:
- image: "<path_to_flash_binaries>/tiboot3.bin"
image-offset: 0x0
part: "hwpart 1"
- image: "<path_to_flash_binaries>/tispl.bin"
image-offset: 0x80000
part: "hwpart 1"
- image: "<path_to_flash_binaries>/u-boot.img"
image-offset: 0x280000
part: "hwpart 1"
- image: "<path_to_flash_binaries>/rootfs.ext4"
part: "rootfs"

**Snagboot Command-line Configuration and Device Flashing Procedure**

Check warning on line 317 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'Snagboot'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'Snagboot'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 317, "column": 3}}}, "severity": "WARNING"}

Snagrecover uses vendor-specific ROM code mechanisms to initialize external RAM and run U-Boot, without modifying any non-volatile memories.

Check warning on line 319 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'Snagrecover'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'Snagrecover'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 319, "column": 1}}}, "severity": "WARNING"}

.. code-block:: console

$ snagrecover -s am625 -F "{'tiboot3': {'path': 'tiboot3.bin'}}" -F "{'tispl': {'path': 'tispl.bin'}}" -F "{'u-boot': {'path': 'u-boot.img'}}"

* Comprehensive instructions for using snagrecover command line are here:

Check warning on line 325 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'snagrecover'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'snagrecover'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 325, "column": 40}}}, "severity": "WARNING"}
`Snagrecover command line <https://github.com/bootlin/snagboot/blob/main/docs/snagrecover.md>`__.

Check warning on line 326 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'Snagrecover'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'Snagrecover'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 326, "column": 4}}}, "severity": "WARNING"}

Snagflash communicates with U-Boot to flash system images to non-volatile memories, using either DFU, UMS or Fastboot.

Check warning on line 328 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'DFU') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'DFU') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 328, "column": 98}}}, "severity": "INFO"}

Check warning on line 328 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.OxfordComma] Use the Oxford comma in 'DFU, UMS or Fastboot.'.

Raw Output:
{"message": "[RedHat.OxfordComma] Use the Oxford comma in 'DFU, UMS or Fastboot.'.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 328, "column": 98}}}, "severity": "INFO"}

Check warning on line 328 in source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'Snagflash'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'Snagflash'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 328, "column": 1}}}, "severity": "WARNING"}

.. code-block:: console

$ snagflash -P fastboot-uboot -p 0451:6165 -i

* Comprehensive instructions for using snagflash command line are here:
`Snagflash command line <https://github.com/bootlin/snagboot/blob/main/docs/snagflash.md>`__.
Loading