live-metal/blend_helpers-arm.md

helper functions

These functions focus on supporting the arm-sdk and generating and writing the appropriate images to different block devices.

Table of Contents

• build_atf()
• build_uboot()
• set-bootloader()
• bootloader-version()
• upgrade-sd-bootloader()
• erase-sd-bootloader()
• write-emmc-flash()
• erase-spi-flash()
• write-spi-flash()
• create-u-boot-menu()
• create_spi_image()
• spi_flash_img()
• create-u-boot-spi-scripts()
• create-rockpro64-scripts()

build_atf()

This function automates the process of building the ARM Trusted Firmware (ATF) for the Rockchip RK3399 platform. It is designed to streamline the development and testing process by encapsulating the necessary steps into a single script.

Description

The build_atf() function performs the following actions:

1. Preparation: It sets up the required environment variables such as strapdir, atf_branch, atfgit, and compiler. These variables are essential for specifying the location of the ATF source code, the branch to checkout, the Git repository URL, and the compiler to use.

2. Git Configuration: The function configures Git with a global username and email address. This is necessary for committing changes during the build process.

3. Cloning the ATF Repository: It clones the specified branch of the ATF repository into a temporary directory. This ensures that the build process uses the correct version of the ATF source code.

4. Cleaning and Building: The function cleans any previous build artifacts using make realclean and then builds the bl31.elf file for the RK3399 platform using the specified compiler and platform settings. The build process is parallelized across all available processors for efficiency.

5. Error Handling: Throughout the process, error handling is implemented to ensure that any issues encountered during the cloning or building stages are promptly reported and handled.

6. Output: After a successful build, the bl31.elf file is copied to a distribution directory. This file is crucial for the boot process of devices running the RK3399 platform.

Usage

To use this function, ensure that the required environment variables (strapdir, atf_branch, atfgit, and compiler) are set appropriately. Then, simply call build_atf() in your script or terminal to initiate the build process.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.

References

• ARM Trusted Firmware documentation for RK3399: Source 0
• General guidance on building ATF: Source 4

build_uboot()

This function automates the process of building U-Boot for the Rockchip RK3399 platform, specifically tailored for the RockPro64 device. It is designed to streamline the development and testing process by encapsulating the necessary steps into a single script.

Description

The build_uboot() function performs the following actions:

1. Preparation: It sets up the required environment variables such as strapdir, ubootgit, uboot_branch, and MAKEOPTS. These variables are essential for specifying the location of the U-Boot source code, the branch to checkout, the Git repository URL, and the make options to use.

2. Git Clone: The function clones the specified branch of the U-Boot repository into a temporary directory. This ensures that the build process uses the correct version of the U-Boot source code.

3. Configuration: It applies various configurations to the U-Boot build process to enable specific features and functionalities. This includes enabling support for ZFS, EFI Secure Boot, and various command-line interfaces among others.

4. Building: The function cleans any previous build artifacts using make mrproper and then builds U-Boot using the specified make options and cross-compiler. The build process is parallelized across all available processors for efficiency.

5. Image Creation: After a successful build, the function creates two types of boot images: one for SD boot (idbloader.img) and another for SPI boot (u-boot.itb). These images are generated using the mkimage tool and are crucial for the boot process of devices running the RK3399 platform.

6. Output: The generated images are copied to a distribution directory. This allows for easy distribution and deployment of the built U-Boot images.

7. Error Handling: Throughout the process, error handling is implemented to ensure that any issues encountered during the cloning, configuration, or building stages are promptly reported and handled.

Usage

To use this function, ensure that the required environment variables (strapdir, ubootgit, uboot_branch, and MAKEOPTS) are set appropriately. Then, simply call build_uboot() in your script or terminal to initiate the build process.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for RK3399: Source 0
• General guidance on building U-Boot: Source 4

set-bootloader()

This function automates the process of setting the appropriate bootloader for different Rockchip-based boards, including Rock64, RockPro64, PineBook Pro, and RockPi4B. It is designed to streamline the development and testing process by encapsulating the necessary steps into a single script.

Description

The set-bootloader() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variable (strapdir). This variable is essential for specifying the root directory where the necessary files are located.

2. Board Detection: Based on the input argument ($1), the function determines the target board (Rock64, RockPro64, PineBook Pro, or RockPi4B) and sets the appropriate loader images (SD_LOADER and SPI_LOADER) and board identifier (BOARD). This is done through a case statement that matches the input against predefined patterns.

3. Error Handling for Unknown Boards: If the input does not match any of the predefined patterns, the function prints an error message and exits with a failure status. This ensures that only supported boards can proceed with the bootloader setup.

4. Device Tree Check: Before proceeding, the function checks if the current running board matches the detected board (BOARD). This is done by comparing the board identifier against the /proc/device-tree/compatible file. If there is a mismatch, the function warns the user about the potential risks of proceeding with an incorrect board setup.

Usage

To use this function, pass the board identifier as an argument when calling set-bootloader(). For example, to set the bootloader for a RockPro64, you would call set-bootloader rockchip-rockpro64.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• Rockchip documentation for bootloader setup: Source 0
• General guidance on setting bootloaders for Rockchip boards: Source 4

bootloader-version()

This function automates the process of retrieving the version information of the U-Boot bootloader installed on a Rockchip-based board. It is designed to streamline the development and testing process by encapsulating the necessary steps into a single script.

Description

The bootloader-version() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variable (strapdir). This variable is essential for specifying the root directory where the necessary files are located.

2. Version Retrieval: The function defines a nested function version() that takes a device identifier as an argument. This function attempts to retrieve the U-Boot version and other relevant information (such as the board and FDT file) from the specified device. It does this by using the strings command to parse the device's contents for U-Boot version strings and other metadata.

3. Error Handling: If the U-Boot version cannot be found on the specified device, the function prints a message indicating that U-Boot is not installed on the device.

Usage

To use this function, pass the device identifier as an argument when calling bootloader-version(). For example, to retrieve the U-Boot version from a device named mmcblk0boot0, you would call bootloader-version mmcblk0boot0.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for version retrieval: Source 1
• General guidance on working with U-Boot versions: Source 2

upgrade-sd-bootloader()

This function automates the process of upgrading the bootloader on an SD card for Rockchip-based boards. It is designed to streamline the development and testing process by encapsulating the necessary steps into a single script.

Description

The upgrade-sd-bootloader() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variables (strapdir and SD_LOADER). These variables are essential for specifying the root directory where the necessary files are located and the path to the new bootloader image.

2. Mount Check: The function checks if the EFI partition is mounted. This is crucial for writing the new bootloader image to the correct partition. If the EFI partition is not mounted, the function prints an error message and exits with a failure status.

3. Report Current Version: Before upgrading, the function retrieves and reports the current version of the bootloader installed on the device. This is done by calling the bootloader-version() function with the device identifier obtained from the mounted EFI partition.

4. Bootloader Upgrade: The function defines a nested function write_sd() that takes a device identifier and the path to the new bootloader image as arguments. This function writes the new bootloader image to a specific partition on the SD card. It assumes that the new bootloader image is intended for a partition numbered p1 on SD devices.

5. Sync: After writing the new bootloader image, the function calls sync to ensure that all pending writes to the disk are completed.

Usage

To use this function, ensure that the required environment variables (strapdir and SD_LOADER) are set appropriately. Then, simply call upgrade-sd-bootloader() in your script or terminal to initiate the bootloader upgrade process.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for bootloader upgrade: Source 0
• General guidance on upgrading bootloaders on SD cards: Source 1

erase-sd-bootloader()

This function automates the process of erasing the bootloader on an SD card for Rockchip-based boards. It is designed to streamline the development and testing process by encapsulating the necessary steps into a single script.

Description

The erase-sd-bootloader() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variable (strapdir). This variable is essential for specifying the root directory where the necessary files are located.

2. Mount Check: The function identifies the device associated with the mounted EFI partition. This is crucial for determining which partition to erase. If the EFI partition is not mounted, the function prints an error message and exits with a failure status.

3. Report Current Version: Before erasing, the function retrieves and reports the current version of the bootloader installed on the device. This is done by calling the bootloader-version() function with the device identifier obtained from the mounted EFI partition.

4. Erase Bootloader: The function defines a nested function write_sd() that takes a device identifier and the path to the erase block as arguments. This function writes zeros to a specific partition on the SD card, effectively erasing the bootloader. It assumes that the erase operation is intended for a partition numbered p1 on SD devices.

5. Sync: After erasing the bootloader, the function calls sync to ensure that all pending writes to the disk are completed.

Usage

To use this function, ensure that the required environment variable (strapdir) is set appropriately. Then, simply call erase-sd-bootloader() in your script or terminal to initiate the bootloader erasure process.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for bootloader erasure: Source 0
• General guidance on erasing bootloaders on SD cards: Source 1

create_spi_image()

This function automates the creation of a single SPI flash image for the Rockchip RK3399 platform, specifically tailored for devices that require a combined SPI flash image containing both the U-Boot ITB (Image Transfer Buffer) and a custom script for flashing the SPI flash. It is designed to streamline the development and testing process by encapsulating the necessary steps into a single script.

Description

The create_spi_image() function performs the following actions:

1. Initialization: It starts by calculating the padding size needed to align the U-Boot ITB at a specific memory address (0x60000 in this case). This is crucial for ensuring that the U-Boot ITB is correctly positioned within the SPI flash.

2. Padding: The function creates a zero-filled file ($(img1name)) with a size equal to the calculated padding size. This file serves as the initial part of the SPI flash image, ensuring that the U-Boot ITB is correctly aligned.

3. Combining Images: It concatenates the padded file with the U-Boot ITB file (u-boot.itb) to form a single SPI flash image. This combined image is then saved to a distribution directory.

4. Script Creation: The function calls create-u-boot-spi-scripts to generate the necessary scripts for flashing the SPI flash. This includes creating a script for flashing the SPI flash with the newly created SPI flash image.

5. SPI Flash Image Creation: Finally, the function uses the mkimage tool to create a script image (flash_spi.scr) that contains the commands for flashing the SPI flash. This script is also saved to the distribution directory.

Usage

To use this function, ensure that the required environment variables (img1name) are set appropriately. Then, simply call create_spi_image() in your script or terminal to initiate the SPI flash image creation process.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for RK3399: Source 0
• General guidance on creating SPI flash images: Source 4

spi_flash_img()

This function automates the creation of an SD card image that can be flashed onto an SPI flash chip, specifically for booting U-Boot from SPI on Rockchip RK3399 platforms. It is designed to streamline the development and testing process by encapsulating the necessary steps into a single script.

Description

The spi_flash_img() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variable (strapdir). This variable is essential for specifying the root directory where the necessary files are located.

2. Copying Scripts: The function copies the flash_spi.scr script and the spi_combined.img image to the current working directory. These files are necessary for flashing the SPI flash and contain the U-Boot ITB (Image Transfer Buffer) and a custom script for flashing the SPI flash.

3. Creating Temporary File System: It creates a temporary FAT32 file system (boot.tmp) with a size of 16MB. This file system will be used to store the boot scripts and images.

4. Copying Boot Scripts and Images: The function copies the boot.scr script and the spi_combined.img image into the temporary file system. This prepares the boot environment on the SD card.

5. Creating Main SPI Flash Image: It creates a new image (flash_spi.img) with a size of 32MB. This image will serve as the main SPI flash image for booting U-Boot.

6. Partitioning the SPI Flash Image: The function partitions the flash_spi.img into three parts: loader1, loader2, and boot. Each partition is assigned a specific size and purpose, with loader1 and loader2 likely serving as loaders for the U-Boot SPL (Secondary Program Loader), and boot being formatted as FAT16 to store the boot scripts and images.

7. Setting Legacy Boot Flag: The legacy_boot flag is set on the boot partition to indicate that it should be used for booting.

8. Writing U-Boot Images: The function writes the idbloader.img and u-boot.itb images to the loader1 and loader2 partitions of the flash_spi.img, respectively. This prepares the SPI flash for booting U-Boot.

9. Writing Boot Scripts and Images: The boot.tmp file system is written to the boot partition of the flash_spi.img. This includes the boot.scr script and the spi_combined.img image.

10. Compressing the SPI Flash Image: Finally, the flash_spi.img is compressed using gzip. This reduces the size of the image, making it easier to transfer and flash onto the SPI flash chip.

Usage

To use this function, ensure that the required environment variable (strapdir) is set appropriately. Then, simply call spi_flash_img() in your script or terminal to initiate the creation of the SD card image for SPI flashing.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.
• dd, mkfs.vfat, mcopy, parted, and gzip utilities.

References

• U-Boot documentation for RK3399: Source 0
• General guidance on creating bootable SD cards with U-Boot: Source 2

erase-spi-flash()

This function automates the process of erasing the SPI flash memory on embedded systems. It is designed to simplify the development and testing process by encapsulating the necessary steps into a single script.

Description

The erase-spi-flash() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variable (strapdir). This variable is essential for specifying the root directory where the necessary files are located.

2. SPI Flash Device Identification: The function searches for the SPI flash device by looking for the string "loader" in /proc/mtd. If the loader partition on MTD is not found, the function prints an error message and exits with a failure status.

3. Reporting Current Version: The function reports the current bootloader version by querying the device identified in the previous step.

4. Erasing SPI Flash: The function erases the entire SPI flash memory by calling flash_erase with the identified device and offsets for each partition.

Usage

To use this function, ensure that the required environment variable (strapdir) is set appropriately. Then, simply call erase-spi-flash() in your script or terminal to initiate the SPI flash erasing process.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for erasing SPI flash: Source 0
• General guidance on erasing SPI flash on embedded systems: Source 1

write-spi-flash()

This function automates the process of writing to the SPI flash memory on embedded systems. It is designed to simplify the development and testing process by encapsulating the necessary steps into a single script.

Description

The write-spi-flash() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variable (strapdir). This variable is essential for specifying the root directory where the necessary files are located.

2. SPI Flash Device Identification: The function searches for the SPI flash device by looking for the string "u-boot-spl" in /proc/mtd. If the "u-boot-spl" partition on MTD is not found, the function prints an error message and exits with a failure status.

3. Writing to SPI Flash: The function writes the content of the specified file to the identified SPI flash device. It first erases the device using flash_erase and then writes the content using nandwrite.

Usage

To use this function, ensure that the required environment variable (strapdir) is set appropriately. Then, simply call write-spi-flash() in your script or terminal to initiate the SPI flash writing process.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for writing to SPI flash: Source 1
• General guidance on writing to SPI flash on embedded systems: Source 3

write-emmc-flash()

This function automates the process of writing U-Boot to the eMMC storage on Rockchip-based boards. It is designed to streamline the development and testing process by encapsulating the necessary steps into a single script.

Description

The write-emmc-flash() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variable (strapdir). This variable is essential for specifying the root directory where the necessary files are located.

2. eMMC Device Identification: The function iterates over all MMC block devices to identify the eMMC device. It does this by checking the device type in /sys/block/<device>/device/type. Once identified, the eMMC device is stored in the emmc_blkdevice variable.

3. Mount Check: The function identifies the device currently mounted as the root filesystem. If the root filesystem is on the eMMC device, the function prints a warning message and exits with a failure status, preventing accidental overwriting of the running system.

4. Writing U-Boot to eMMC: The function writes the U-Boot IDBLoader and U-Boot ITB images to the eMMC device. It does this by using the dd command to copy the images to the correct offsets on the eMMC device. The IDBLoader is written to offset 64, and the U-Boot ITB is written to offset 16384.

Usage

To use this function, ensure that the required environment variable (strapdir) is set appropriately. Then, simply call write-emmc-flash() in your script or terminal to initiate the U-Boot writing process to the eMMC.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for writing to eMMC: Source 0
• General guidance on writing U-Boot to eMMC on Rockchip boards: Source 1

create-u-boot-menu()

This function automates the creation of a U-Boot menu for booting various operating systems or configurations. It is designed to simplify the setup process for developers working with U-Boot on embedded systems.

Description

The create-u-boot-menu() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variable (strapdir). This variable is essential for specifying the root directory where the necessary files are located.

2. U-Boot Menu Configuration: The function creates a U-Boot script (boot.cmd) that defines a boot menu with several options for booting different kernels or resetting the board. This script is then compiled into a U-Boot script image (boot.scr) using the mkimage tool.

3. U-Boot Script Compilation: The function compiles the boot.cmd script into a U-Boot script image (boot.scr) using the mkimage tool. This image is used by U-Boot to execute the boot menu.

Usage

To use this function, ensure that the required environment variable (strapdir) is set appropriately. Then, simply call create-u-boot-menu() in your script or terminal to generate the U-Boot boot menu.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for creating boot menus: Source 1
• General guidance on configuring U-Boot for booting various operating systems: Source 2

create-u-boot-spi-scripts()

"$R/tmp/kernels/u-boot-rockpro64"/scripts/load-spi-from-usb.cmd "$R/tmp/kernels/u-boot-rockpro64"/scripts/flash-spi.cmd "$R/tmp/kernels/u-boot-rockpro64"/scripts/erase_spi.cmd

create-u-boot-spi-scripts()

This function automates the creation of U-Boot SPI flash scripts for RockPro64 boards. It simplifies the process of erasing, flashing, and loading U-Boot to SPI flash, making it easier for developers to manage the boot process.

Description

The create-u-boot-spi-scripts() function performs the following actions:

1. Preparation: It checks for the presence of the required environment variable (strapdir). This variable is essential for specifying the root directory where the necessary files are located.

2. Script Creation:

   • erase_spi.cmd: This script erases the U-Boot partitions from SPI flash. It includes visual feedback through LED blinking to indicate progress.
   • flash-spi.cmd: This script flashes the U-Boot image to SPI flash. Similar to the erase script, it uses LED indicators to show the operation's progress.
   • load-spi-from-usb.cmd: This script loads U-Boot from a USB drive to SPI flash. It checks for the presence of the necessary files on the USB drive before proceeding.

3. Script Compilation: The function compiles these scripts into U-Boot script images using the mkimage tool, making them ready for use in U-Boot.

Usage

To use this function, ensure that the required environment variable (strapdir) is set appropriately. Then, simply call create-u-boot-spi-scripts() in your script or terminal to generate the U-Boot SPI flash scripts.

Dependencies

• A compatible cross-compiler for ARM architecture.
• Git installed on the system.
• Make utility.
• U-Boot source code and tools.

References

• U-Boot documentation for scripting: Source 1
• General guidance on managing U-Boot on RockPro64 boards: Source 2```

create-rockpro64-scripts()

/usr/local/sbin/rockpro64_reset_spi_flash.sh /usr/local/sbin/rockpro64_reset_emmc.sh /usr/local/sbin/rockpro64_disable_otg.sh /usr/local/sbin/rockpro64_enable_eth_gadget.sh

This function automates the creation of shell scripts for managing Ethernet gadget functionality and resetting the eMMC and SPI flash on RockPro64 boards. It simplifies the process of enabling and disabling Ethernet gadget mode, resetting the eMMC, and resetting the SPI flash, making it easier for developers to manage the board's configuration.

Description

The create-rockpro64-scripts() function performs the following actions:

1. Script Creation:

   • rockpro64_enable_eth_gadget.sh: This script enables the Ethernet gadget mode on the RockPro64 board, allowing it to act as a network device. It involves enabling the usb0_dwc3_peripheral overlay, reloading the DWC3 driver, and installing the Ethernet gadget.
   • rockpro64_disable_otg.sh: This script disables the Ethernet gadget mode, effectively turning off the board's ability to act as a network device. It involves disabling the dwc3_peripheral overlay and unbinding the DWC3 driver.
   • rockpro64_reset_emmc.sh: This script resets the eMMC interface on the RockPro64 board. It checks if the script is being run from the eMMC and prevents execution if so, unless the --force option is provided. It then unbinds and binds the SDHCI driver to reset the interface.
   • rockpro64_reset_spi_flash.sh: This script resets the SPI flash interface on the RockPro64 board. It unbinds and binds the SPI driver to reset the interface.

2. Script Compilation: The function compiles these scripts into executable files, making them ready for use in the terminal or included in other scripts.

Usage

To use this function, simply call create-rockpro64-scripts() in your script or terminal. This will generate the necessary shell scripts in the /usr/local/sbin/ directory, which can then be executed as needed.

Dependencies

• Bash shell.
• Access to the RockPro64 board's device tree overlays and drivers.

References

• RockPro64 documentation for managing Ethernet gadget mode: Source 1
• General guidance on managing RockPro64 interfaces: Source 2