> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.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  | No         |         |

## Build U-Boot image

This section describes how to build the U-Boot binary as part of the QLI 2.0 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 2.0 release:
   ```bash theme={null}
   git checkout 5a77d4670d8084ada24a2735dda75788ed5ce925
   ```

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 qcs6490_defconfig`     |
   | IQ-9075 | `make O=.output qcom_lemans_defconfig` |
   | IQ-615  | `make O=.output qcom_qcs615_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>

#### Enabling Kernel-Based Virtual Machine (KVM)

To enable KVM mode in U-Boot, update the defconfig file for your target platform by adding the following configuration options:

```
CONFIG_ENABLE_ARM_SOC_BOOT0_HOOK=y
CONFIG_QCOM_EL2_GUNYAH_EXIT_SUPPORT=y
```

After modifying the defconfig, rebuild U-Boot following the steps in [Build U-Boot image](#build-u-boot-image).

### 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.

<Note>
  Kernel-Based Virtual Machine (KVM) is enabled by default for KVM-supported targets (IQ-9075 and IQ-615) in the Yocto build. The following configurations are added by default when building U-Boot for these targets:

  ```
  CONFIG_ENABLE_ARM_SOC_BOOT0_HOOK=y
  CONFIG_QCOM_EL2_GUNYAH_EXIT_SUPPORT=y
  ```
</Note>

## Flash U-Boot image

### Using Qualcomm tools

Follow the build flashing instructions to flash the U-Boot binary along with the QLI 2.0 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                                                          |

## See also

* [Troubleshoot using U-Boot log](./troubleshoot-using-uboot-log)