# XBL Tools

Tools for manipulating Qualcomm XBL images.

## unpackxbl

This tool uses brute-force and heuristics to split a Qualcomm XBL partition
image into it's three respective parts.

1. sbl1.elf
2. xbl_core.elf
3. xbl_sec.mbn

## The components

### sbl1

sbl1 is the pre-loader responsible for loading everything else, it does some
basic hw init, DDR training, and loads tz, hyp, abl, and other images from
storage. Then it jumps to xbl_core via the hypervisor.

### xbl_core

This is the actual EDKII based UEFI bootloader, when people refer to Qualcomm
"XBL" they usually just mean this part. It receives some data from sbl1 which
includes the address of where ABL was loaded. ABL is just a single .efi
executable (`LinuxLoader.efi` which contains the actual Android boot image
handling and fastboot implementation). It's wrapped in an EFI Firmware Volume
(FV) with an ELF header appended. On Android/IoT configurations XBL will always
launch `LinuxLoader.efi`.

### xbl_sec

This binary is validated separetely to the rest of XBL, it is also the first
code to run. It initialises EL3 before jumping to the pre-loader. The entrypoint
of xbl.elf is actually for xbl_sec.

## Why?

By being able to unpack and existing XBL image, we can then re-pack it again
using the
[createxbl.py](https://github.com/coreboot/coreboot/blob/main/util/qualcomm/createxbl.py)
tool which is readily available in the coreboot repo.

Now, leveraging what we know about the structure of these ELF files, we can
provide a drop-in replacement for xbl_core, namely: U-Boot. We can build U-Boot
with the correct TEXT_BASE, have it generate an ELF file and then build a new
XBL image which will boot directly into U-Boot instead of into EDKII.

## On my device?

Unfortunately, re-generating the XBL image necessarily means re-generating the
hash and re-signing it. If your device is unfused (doesn't have Qualcomm
secureboot enabled), and signing images using
[qtestsign](https://github.com/msm8916-mainline/qtestsign) works for you, then
you can give this approach a try. Outside of development boards and engineering
samples, the only devices using XBL without secureboot that I'm aware of are the
SHIFT6mq and TCL Book 14 Go.

## Building

```sh
meson setup build
meson compile -C build
```

## Using

```sh
./build/unpackxbl /path/to/stock/xbl.elf
```

One can then build a new XBL image with (for example) U-Boot as the payload by
using `createxbl.py` from coreboot. This is known to work for SDM845, but other
SoCs may have some issues with the MBN header and certs as generated by
coreboot's `createxbl.py`. Running with `--no_hash` and using a different tool
to generate the header is recommended.

```sh
../coreboot/utils/qualcomm/createxbl.py -f ./sbl1.elf -s u-boot.elf -x ./xbl_sec.mbn -a 64 -b 64 -d 64 --mbn_version=5 -o uboot1st.elf
fastboot flash xbl uboot1st.elf reboot
```