Skip to content

fix(tools): update snagboot documentation #776

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

Open
sadik-smd wants to merge 1 commit into
base: master
Choose a base branch
from
Open

fix(tools): update snagboot documentation #776

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
6 changes: 6 additions & 0 deletions .github/styles/config/vocabularies/PSDK/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ PVRCarbon
PVRTune
Sitara
Slint
SPL

@StaticRocket StaticRocket Aug 5, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acronyms should not be considered valid words

TFLite
TVM
Trixie
Expand All @@ -31,6 +32,11 @@ Zink
[Kk]irkstone
[Mm]ulticast
[Ss]carthgap
[Ss]nagboot
[Ff]astboot
[Ss]nagfactory
[Ss]nagrecover
[Ss]nagflash
Comment on lines +37 to +39

@StaticRocket StaticRocket Aug 5, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The other entries are fine as they are project names. These ones though are command names which I'm a little more hesitant to treat as proper words, especially since most command names are compound words that omit punctuation or use unusual spelling for ease of use.

If you use inline code or the command role in the documentation, vale will properly ignore it's use. Additionally, it will make it clear to the reader when you are talking about a command or something else.

I don't really know how much to enforce this here though since the upstream Snagboot docs are so lax about their spelling.

[Tt]oolchain
balenaEtcher
bdebstrap
Expand Down
161 changes: 123 additions & 38 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 @@ -18,37 +18,104 @@
Installing Snagfactory
**********************

Install using the SDK installer (recommended)
=============================================

The Linux SDK installer includes a setup script that installs Snagboot and
configures udev rules automatically.

.. code-block:: console

$ cd <sdk_install_dir>
$ ./bin/setup-snagboot.sh

To also install the optional Snagfactory GUI:

.. code-block:: console

$ ./bin/setup-snagboot.sh --gui

The script installs Snagboot by using pip, sets up udev rules so USB access works
without root, and verifies the installation. If pip installs the tools to
``~/.local/bin`` but that directory is not on ``PATH``, add the following to ``~/.bashrc``:

@StaticRocket StaticRocket Aug 5, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
``~/.local/bin`` but that directory is not on ``PATH``, add the following to ``~/.bashrc``:
:file:`~/.local/bin` but that directory is not on ``PATH``, add the following to :file:`~/.bashrc`:

Pip has a built in warning about this. Not sure how old it is. If it's present for our supported Ubuntu host version then this should be safe to omit I think. Well, unless that setup script eats the message.


.. code-block:: console

$ export PATH="$HOME/.local/bin:$PATH"

Manual installation
===================

If the SDK installer is not available, install Snagboot directly by using pip:

* Snagfactory tool is hosted here `Snagfactory <https://github.com/bootlin/snagboot>`__.
* 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

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

After installation, set up udev rules so USB access works without root:

.. code-block:: console

$ python3 -m snagrecover --udev | sudo tee /etc/udev/rules.d/80-snagboot.rules
$ sudo udevadm control --reload-rules && sudo udevadm trigger

.. note::

At the time of 11.2 release, the corresponding Snagfactory version was v2.5.
At the time of 12.01 release, the corresponding Snagfactory version was v2.5.

.. 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
*****************************************
*******************************************
Build boot loader binaries for recovery
*******************************************

For Snagrecover, boot loader images must support Device Firmware Upgrade (DFU) boot
and fastboot download. The u-boot build requires the USB DFU fragment config to enable
DFU boot. It also requires the additional fragment config
:file:`am6x_a53_snagfactory.config`, that enables fastboot support in U-Boot and other
required configs for snagfactory.

For Snagrecover, bootloader images must support DFU boot and fastboot download.
In addition to USB DFU fragment config (which enables DFU boot) for the u-boot
build, an additional fragment config :file:`am6x_a53_snagfactory.config` needs to be
used, which enables fastboot support in U-Boot and other required configs for
snagfactory.
Build using the SDK installer (recommended)
===========================================

To build bootloader images for recovery using SDK, following change is needed
in :file:`Rules.make` file present in the top level of Linux SDK Installer.
The Linux SDK installer includes a dedicated Makefile target that builds
boot loader images with all the required DFU and Fastboot configuration
fragments applied automatically.

From the top level of the Linux SDK installer:

.. code-block:: console

$ make u-boot-snagboot_clean
$ make u-boot-snagboot
$ make u-boot-snagboot_stage

The build places the staged boot loader images in
:file:`board-support/built-images/snagboot/`. The directory contains:

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.SimpleWords] Use simple language. Consider using 'has' rather than 'contains'.

Raw Output:
{"message": "[RedHat.SimpleWords] Use simple language. Consider using 'has' rather than 'contains'.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 102, "column": 61}}}, "severity": "INFO"}

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Slash] Use either 'or' or 'and' in 'support/built'

Raw Output:
{"message": "[RedHat.Slash] Use either 'or' or 'and' in 'support/built'", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 102, "column": 14}}}, "severity": "WARNING"}

* :file:`tiboot3.bin` (R5 Secondary Program Loader (SPL), or A53 SPL for AM62L)
* :file:`tispl.bin` (A53 SPL with DFU and fastboot support)
* :file:`u-boot.img` (U-Boot with fastboot support)

.. note::

For AM62L, only the A53 build is needed. The ``u-boot-snagboot`` target

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.PassiveVoice] 'is needed' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.

Raw Output:
{"message": "[RedHat.PassiveVoice] 'is needed' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 110, "column": 34}}}, "severity": "INFO"}
handles this automatically.

Manual build
============

If the SDK installer is not available, apply the required config fragments

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.SentenceLength] Try to keep sentences to an average of 32 words or fewer.

Raw Output:
{"message": "[RedHat.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 116, "column": 1}}}, "severity": "INFO"}
manually by editing :file:`Rules.make` in the top level of the Linux SDK and
then running the standard u-boot build.

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

Expand Down Expand Up @@ -108,18 +175,15 @@

UBOOT_MACHINE=am62lx_evm_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.
Then build using the top-level makefile:

.. code-block:: console

$ make u-boot_clean
$ make u-boot
$ make u-boot_stage

Save the bootloader binaries generated in a separate directory. These bootloader
images will be used for recovery and to start flashing the images. The bootloader
images after make can be found in :file:`board-support/built-images`.
The boot loader images are placed in :file:`board-support/built-images`.

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Slash] Use either 'or' or 'and' in 'support/built'

Raw Output:
{"message": "[RedHat.Slash] Use either 'or' or 'and' in 'support/built'", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 186, "column": 51}}}, "severity": "WARNING"}

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.PassiveVoice] 'are placed' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.

Raw Output:
{"message": "[RedHat.PassiveVoice] 'are placed' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 186, "column": 24}}}, "severity": "INFO"}

For more details regarding USB DFU refer :ref:`usb-device-firmware-upgrade-label`.

Expand Down Expand Up @@ -183,16 +247,37 @@
SW3 - BOOTMODE[8:15] = 00000000

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

Check warning on line 250 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 'UART') on first occurrence if they're likely to be unfamiliar.

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

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

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>`__.

YAML configuration files

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'YAML configuration files'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'YAML configuration files'.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 260, "column": 1}}}, "severity": "INFO"}
=========================

Ready-to-use YAML configuration files for all supported platforms are bundled

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.PassiveVoice] 'are bundled' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.

Raw Output:
{"message": "[RedHat.PassiveVoice] 'are bundled' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 263, "column": 67}}}, "severity": "INFO"}
with the SDK installer under:

.. code-block:: text

<sdk_install_dir>/bin/snagboot_flash/yaml/<board>/

The same configuration files are also available from the TI GitHub repository:

`snagfactory-configs <https://github.com/TexasInstruments/snagfactory-configs>`__

Before using a YAML file, replace the two path placeholders with actual paths
to your binaries:

* ``<path_to_snagboot_binaries>/`` — recovery boot loader images built with

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.EmDash] Do not use em dashes. Use punctuation marks such as commas, parentheses, or colons instead.

Raw Output:
{"message": "[RedHat.EmDash] Do not use em dashes. Use punctuation marks such as commas, parentheses, or colons instead.", "location": {"path": "source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst", "range": {"start": {"line": 277, "column": 36}}}, "severity": "WARNING"}

@StaticRocket StaticRocket Aug 5, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#726

``u-boot-snagboot`` (placed in :file:`board-support/built-images/snagboot/`)
* ``<path_to_flash_binaries>/`` — production images to be written to the
target non-volatile memory

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

Expand All @@ -217,22 +302,22 @@

$ snagfactory

**Step 2: Select Configuration File Option**
**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**
**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**
**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 following table outline the board names for snagfactory yaml configuration.
The following table outlines the board names for snagfactory YAML configuration.

@StaticRocket StaticRocket Aug 5, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For future reference: The yaml examples listed below can be tagged with yaml for language aware linting and syntax highlighting: https://pygments.org/docs/lexers/


.. list-table::
:header-rows: 1
Expand Down Expand Up @@ -276,11 +361,11 @@
soc-models:
am62p-firmware:
tiboot3:
path: "<path_to_boot_binaries>/tiboot3.bin"
path: "<path_to_snagboot_binaries>/tiboot3.bin"
tispl:
path: "<path_to_boot_binaries>/tispl.bin"
path: "<path_to_snagboot_binaries>/tispl.bin"
u-boot:
path: "<path_to_boot_binaries>/u-boot.img"
path: "<path_to_snagboot_binaries>/u-boot.img"
am62p-tasks:
- eraseblk-size: 0x40000
fb-buffer-addr: 0x82000000
Expand Down Expand Up @@ -316,11 +401,11 @@
soc-models:
am625-firmware:
tiboot3:
path: "<path_to_boot_binaries>/tiboot3.bin"
path: "<path_to_snagboot_binaries>/tiboot3.bin"
tispl:
path: "<path_to_boot_binaries>/tispl.bin"
path: "<path_to_snagboot_binaries>/tispl.bin"
u-boot:
path: "<path_to_boot_binaries>/u-boot.img"
path: "<path_to_snagboot_binaries>/u-boot.img"
am625-tasks:
- eraseblk-size: 0x40000
fb-buffer-addr: 0x82000000
Expand Down Expand Up @@ -357,7 +442,7 @@
- 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:
For reference, the :file:`emmc.yaml` file for **am62p** platform can be as follows:

.. code-block:: text

Expand All @@ -366,11 +451,11 @@
soc-models:
am62p-firmware:
tiboot3:
path: "<path_to_boot_binaries>/tiboot3.bin"
path: "<path_to_snagboot_binaries>/tiboot3.bin"
tispl:
path: "<path_to_boot_binaries>/tispl.bin"
path: "<path_to_snagboot_binaries>/tispl.bin"
u-boot:
path: "<path_to_boot_binaries>/u-boot.img"
path: "<path_to_snagboot_binaries>/u-boot.img"
am62p-tasks:
- target-device: mmc0
fb-buffer-addr: 0x82000000
Expand All @@ -394,7 +479,7 @@
- image: "<path_to_flash_binaries>/rootfs.ext4"
part: "rootfs"

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

.. code-block:: text

Expand All @@ -404,11 +489,11 @@
soc-models:
am62l3-firmware:
tiboot3:
path: "<path_to_boot_binaries>/tiboot3.bin"
path: "<path_to_snagboot_binaries>/tiboot3.bin"
tispl:
path: "<path_to_boot_binaries>/tispl.bin"
path: "<path_to_snagboot_binaries>/tispl.bin"
u-boot:
path: "<path_to_boot_binaries>/u-boot.img"
path: "<path_to_snagboot_binaries>/u-boot.img"

am62l3-tasks:
- target-device: mmc0
Expand Down Expand Up @@ -438,7 +523,7 @@

For eMMC boot configuration, refer :ref:`emmc_boot_config`

**Snagboot Command-line Configuration and Device Flashing Procedure**
**Snagboot command-line configuration and device flashing procedure**

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

Expand Down
Loading