> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# U-Boot on Qualcomm Linux

## Overview

This page provides an overview of U-Boot (Universal Boot Loader) support in Qualcomm Linux (QLI) software.

## Supported SoCs

| SoC Name | Supported? | Storage |
| - | - | - |
| QCS6490 | Yes | UFS |
| IQ-9075 | Yes | UFS |
| IQ-615 | Yes | eMMC |
| IQ-8275 | Yes | UFS |
| CQ-2390/IQ-2390 | Yes | eMMC |

## Build U-Boot image

This section describes how to build the U-Boot binary as part of the QLI software.

### 1. From Qualcomm Linux GitHub repository

#### Prerequisites

Before proceeding with the build steps, do the following:

1. Install following package on your local machine:
   ```bash theme={null}
   sudo apt install libgnutls28-dev
   ```

2. Download and extract the Arm GNU Toolchain:

   ```bash theme={null}
   cd ~  # or your preferred location
   wget https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu.tar.xz
   tar -xf arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu.tar.xz
   ```

   <Note>
     * This creates the toolchain directory at `~/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu/`. If you extract it to a different location, adjust the paths in the build commands accordingly.
     * Install the toolchain on an x86 64-bit host computer only.
     * For other versions, visit [Arm GNU Toolchain Downloads](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads).
   </Note>

3. Download the qtestsign utility:
   ```bash theme={null}
   cd ~  # or your preferred location
   git clone https://github.com/msm8916-mainline/qtestsign qtestsign
   ```

#### Build steps

1. Download the U-Boot repository from Qualcomm Linux GitHub to your local workspace and move to the `u-boot` folder:
   ```bash theme={null}
   git clone https://github.com/qualcomm-linux/u-boot.git
   ```

2. Switch the branch:
   ```bash theme={null}
   git switch qcom-next
   ```

3. Check out the SRC REV for the QLI release:
   ```bash theme={null}
   git checkout 5ec66cb5c3f29e2da1f55464109cae3fe8545b69
   ```

4. Configure the build for your platform. This command creates the required configuration files in the `.output` directory. Choose the command based on your platform:

   | SoC | Command |
   | - | - |
   | QCS6490 | `make O=.output qcm6490_defconfig` |
   | IQ-9075 | `make O=.output qcom_lemans_defconfig` |
   | IQ-615 | `make O=.output qcom_qcs615_defconfig` |
   | IQ-8275 | `make O=.output qcom_qcs8300_defconfig` |
   | CQ-2390/IQ-2390 | `make O=.output qcom_shikra_defconfig` |

5. Build U-Boot using the cross-compile toolchain:

   ```bash theme={null}
   make -j8 CROSS_COMPILE=~/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu- O=.output
   ```

   <Note>
     Replace `~/arm-gnu-toolchain-14.2.rel1-x86_64-aarch64-none-linux-gnu/` with your actual toolchain installation path if you extracted it to a different location.
   </Note>

   **Expected result:**

   * The U-Boot build completes without errors.
   * The `u-boot.elf` file is available in the `.output` directory.

#### Convert u-boot.elf to u-boot.mbn

This command generates the signed `u-boot.mbn` file required for flashing:

```bash theme={null}
python ~/qtestsign/qtestsign.py -v6 aboot -o .output/u-boot.mbn .output/u-boot.elf
```

<Note>
  Replace `~/qtestsign/` with your actual qtestsign installation path if you cloned it to a different location.
</Note>

### 2. Using Yocto build

Follow the instructions on the [Build Qualcomm Linux using Yocto](/Key-Documents/Yocto-Guide/build-qualcomm-linux) page with the following modifications:

* To generate the U-Boot binary, append `:meta-qcom/ci/u-boot-qcom.yml` KAS fragment to the build command in step 3 of "Build a BSP image".
* In the build artifacts folder, the final U-Boot binary is generated as `uefi.elf` in the `<workspace-dir>/build/tmp/deploy/images/<MACHINE>/<IMAGE>-<MACHINE>.rootfs.qcomflash/` directory.

## Flash U-Boot image

### Using Qualcomm tools

Follow the build flashing instructions to flash the U-Boot binary along with the QLI build as described in [Flash software images](/Key-Documents/Flash-Guide/flash-with-qdl).

### Using Fastboot

1. Enter fastboot mode using one of the following methods:
   * From kernel:
     ```bash theme={null}
     adb shell reboot bootloader
     ```
   * From U-Boot CLI:
     ```
     run fastboot
     ```
2. Flash the desired image from the host. For example, to flash the U-Boot image:
   ```bash theme={null}
   fastboot flash uefi_a u-boot.mbn
   ```
3. Restart the device:
   ```bash theme={null}
   fastboot reboot
   ```

## Supported U-Boot commands

The following table lists some of the key U-Boot commands available on the supported platforms. These commands cover boot management, environment management, storage access, and hardware peripheral control. The available commands may vary depending on the platform support.

<Note>
  * In QCS6490, Watchdog is used by the Hypervisor; therefore, Watchdog commands do not work for QCS6490.
</Note>

| Command | Description |
| - | - |
| **Boot** | |
| `run bootcmd` | Run the default boot command sequence defined in `bootcmd` |
| `bootefi bootmgr` | Load and boot EFI payload based on BootOrder/BootXXXX variables |
| `bootflow scan [-abeGl] [bdev]` | Scan for valid bootflows (`-l` list, `-a` all, `-e` errors, `-b` boot) |
| `bootflow list [-e]` | List scanned bootflows (`-e` to include errors) |
| `bootflow select [<num>\|<name>]` | Select a bootflow by number or name |
| `bootflow info [-ds]` | Show info on the current bootflow (`-d` dump bootflow) |
| `bootflow boot` | Boot the current bootflow |
| `bootdev list [-p]` | List all available boot devices (`-p` to probe) |
| `bootdev info [-p]` | Show information about the current boot device (`-p` to probe) |
| **General** | |
| `printenv` | Print environment variables |
| `saveenv` | Save environment variables |
| `version` | Print monitor, compiler, and linker version |
| `run fastboot` | Enter fastboot mode and wait for fastboot command requests from the host machine |
| `reset -edl` | Enter EDL (Emergency Download) mode |
| **SCSI** | |
| `scsi scan` | Scan SCSI bus |
| `scsi info` | Show available SCSI devices |
| `scsi device [dev]` | Show or set current device (`dev` should be 0, 1, 2, 3, 4, 5, ...) |
| `scsi part [dev]` | Print partition table of one or all SCSI devices |
| `scsi read [addr] [blk#] [cnt]` | Read `cnt` blocks starting at block `blk#` to memory address `addr` |
| `scsi write [addr] [blk#] [cnt]` | Write `cnt` blocks starting at block `blk#` from memory address `addr` |
| **MMC** | |
| `mmc list` | List available MMC devices |
| `mmc info` | Show current MMC device info |
| `mmc dev [dev]` | Show or set current MMC device |
| `mmc part` | Print partition table of the current MMC device |
| `mmc read [addr] [blk#] [cnt]` | Read `cnt` blocks from MMC starting at block `blk#` to memory address `addr` |
| `mmc write [addr] [blk#] [cnt]` | Write `cnt` blocks to MMC starting at block `blk#` from memory address `addr` |
| **Regulator** | |
| `regulator list` | List UCLASS regulator devices |
| `regulator dev [regulator-name]` | Show or set the operating regulator device |
| `regulator info` | Print constraints info |
| `regulator status [-a]` | Print operating status (for all with `-a`) |
| `regulator value [val] [-f]` | Print or set voltage value in µV (force with `-f`) |
| `regulator enable` | Enable the regulator output |
| `regulator disable` | Disable the regulator output |
| **Watchdog (WDT)** | |
| `wdt list` | List available watchdog devices |
| `wdt dev [devname]` | Show or set current watchdog device |
| `wdt start <timeout_ms>` | Start the watchdog timer with the specified timeout in milliseconds |
| `wdt stop` | Stop the watchdog timer |

## UEFI Secure Boot

U-Boot supports UEFI Secure Boot, which validates the authenticity of EFI images (such as the kernel and bootloader) before execution using a chain of trust based on the platform key (PK), key exchange key (KEK), signature database (db), and forbidden signatures database (dbx).

For the complete procedure to generate keys, preseed the variable store, sign EFI images, and build U-Boot with `CONFIG_EFI_SECURE_BOOT` enabled, see [EFI Secure Boot](https://github.com/qualcomm-linux/u-boot/blob/qcom-next/doc/usage/efi_secureboot.rst) in the U-Boot documentation.

## See also

* [Troubleshoot using U-Boot log](./troubleshoot-using-uboot-log)
* [EFI Secure Boot (upstream U-Boot documentation)](https://github.com/qualcomm-linux/u-boot/blob/qcom-next/doc/usage/efi_secureboot.rst)