diff --git a/.github/styles/config/vocabularies/PSDK/accept.txt b/.github/styles/config/vocabularies/PSDK/accept.txt index 668feebd7..be15f965b 100644 --- a/.github/styles/config/vocabularies/PSDK/accept.txt +++ b/.github/styles/config/vocabularies/PSDK/accept.txt @@ -14,6 +14,7 @@ PVRCarbon PVRTune Sitara Slint +SPL TFLite TVM Trixie @@ -31,6 +32,11 @@ Zink [Kk]irkstone [Mm]ulticast [Ss]carthgap +[Ss]nagboot +[Ff]astboot +[Ss]nagfactory +[Ss]nagrecover +[Ss]nagflash [Tt]oolchain balenaEtcher bdebstrap diff --git a/source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst b/source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst index 2bf99fbe1..834fb00f7 100644 --- a/source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst +++ b/source/linux/Foundational_Components/Tools/Flash_via_Fastboot.rst @@ -18,18 +18,54 @@ enviroment. 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 + $ ./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``: + +.. 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 `__. * More info about installation can be found in `Snagfactory Readme `__. -* 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') @@ -37,18 +73,49 @@ Installing Snagfactory AM62DX support was added after v2.3. Refer this `commit `__. -***************************************** -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: + +* :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 + handles this automatically. + +Manual build +============ + +If the SDK installer is not available, apply the required config fragments +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') @@ -108,8 +175,7 @@ in :file:`Rules.make` file present in the top level of Linux SDK Installer. 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 @@ -117,9 +183,7 @@ commands on the terminal from the top-level of the Linux SDK installer. $ 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`. For more details regarding USB DFU refer :ref:`usb-device-firmware-upgrade-label`. @@ -183,16 +247,37 @@ Connections 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. How to use Snagfactory -********************** +====================== Comprehensive instructions for installation of the Snagfactory tool are here: * `Snagfactory doc `__. * `Snagfactory config doc `__. +YAML configuration files +========================= + +Ready-to-use YAML configuration files for all supported platforms are bundled +with the SDK installer under: + +.. code-block:: text + + /bin/snagboot_flash/yaml// + +The same configuration files are also available from the TI GitHub repository: + +`snagfactory-configs `__ + +Before using a YAML file, replace the two path placeholders with actual paths +to your binaries: + +* ``/`` — recovery boot loader images built with + ``u-boot-snagboot`` (placed in :file:`board-support/built-images/snagboot/`) +* ``/`` — production images to be written to the + target non-volatile memory **SnagFactory GUI Tool Configuration and Device Flashing Procedure** @@ -217,22 +302,22 @@ the SnagFactory GUI tool. $ 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. .. list-table:: :header-rows: 1 @@ -276,11 +361,11 @@ For reference, the :file:`ospi-nor.yaml` file for **am62p** platform can be as f soc-models: am62p-firmware: tiboot3: - path: "/tiboot3.bin" + path: "/tiboot3.bin" tispl: - path: "/tispl.bin" + path: "/tispl.bin" u-boot: - path: "/u-boot.img" + path: "/u-boot.img" am62p-tasks: - eraseblk-size: 0x40000 fb-buffer-addr: 0x82000000 @@ -316,11 +401,11 @@ For reference, the :file:`ospi-nand.yaml` file for **am62xx-lp** platform can be soc-models: am625-firmware: tiboot3: - path: "/tiboot3.bin" + path: "/tiboot3.bin" tispl: - path: "/tispl.bin" + path: "/tispl.bin" u-boot: - path: "/u-boot.img" + path: "/u-boot.img" am625-tasks: - eraseblk-size: 0x40000 fb-buffer-addr: 0x82000000 @@ -357,7 +442,7 @@ For reference, the :file:`ospi-nand.yaml` file for **am62xx-lp** platform can be - image: "/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 @@ -366,11 +451,11 @@ For reference, the :file:`emmc.yaml` file for **am62p** platform can be as foll soc-models: am62p-firmware: tiboot3: - path: "/tiboot3.bin" + path: "/tiboot3.bin" tispl: - path: "/tispl.bin" + path: "/tispl.bin" u-boot: - path: "/u-boot.img" + path: "/u-boot.img" am62p-tasks: - target-device: mmc0 fb-buffer-addr: 0x82000000 @@ -394,7 +479,7 @@ For reference, the :file:`emmc.yaml` file for **am62p** platform can be as foll - image: "/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 @@ -404,11 +489,11 @@ For reference, the :file:`emmc.yaml` file for **am62l** platform can be as foll soc-models: am62l3-firmware: tiboot3: - path: "/tiboot3.bin" + path: "/tiboot3.bin" tispl: - path: "/tispl.bin" + path: "/tispl.bin" u-boot: - path: "/u-boot.img" + path: "/u-boot.img" am62l3-tasks: - target-device: mmc0 @@ -438,7 +523,7 @@ For reference, the :file:`emmc.yaml` file for **am62l** platform can be as foll 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.