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

# Install & boot the kernel

After a successful build, the Qualcomm<sup>®</sup> Linux boot system uses two flashed images
to bring up the kernel: `efi.bin` (ESP partition) and `dtb.bin` (DTB partition).

## Image composition

The Yocto build packages kernel artifacts into flashable images:

* **`efi.bin`** is the EFI System Partition (ESP) image. Contains systemd-boot (boot
  manager) and the kernel packaged as a UKI type-2 image, which bundles the kernel,
  initramfs, and optionally a device tree. Flashed to the `efi` partition.
* **`dtb.bin`** is the DTB partition image. Contains all compiled device tree blobs
  (DTBs). Flashed to the `dtb_a` partition.

**Table: Kernel build artifacts**

| Image             | Image name                               | Build deploy path                                               | Details                                                             |
| ----------------- | ---------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- |
| Kernel ELF        | `vmlinux`                                | `build/tmp/deploy/images/<machine>/<image>-*.rootfs.qcomflash/` | Output kernel ELF with debug symbols.                               |
| Initramfs         | `initramfs-qcom-image-<machine>.cpio.gz` | `build/tmp/deploy/images/<machine>/`                            | Initramfs in CPIO format.                                           |
| Kernel image      | `Image`                                  | `build/tmp/deploy/images/<machine>/`                            | Raw kernel binary. systemd-boot does not support compressed images. |
| Kernel modules    | `modules-<machine>.tgz`                  | `build/tmp/deploy/images/<machine>/`                            | Dynamically loadable kernel modules (DLKMs).                        |
| Device tree blobs | `<SoC>-<board>-<variant>.dtb`            | `build/tmp/deploy/images/<machine>/`                            | Individual device tree blobs.                                       |
| ESP partition     | `efi.bin`                                | `build/tmp/deploy/images/<machine>/<image>-*.rootfs.qcomflash/` | systemd-boot, kernel, and initramfs packaged as a UKI type-2 image. |
| DTB partition     | `dtb.bin`                                | `build/tmp/deploy/images/<machine>/<image>-*.rootfs.qcomflash/` | All DTBOs packaged in a FIT image.                                  |

## Deploy kernel artifacts

If you have not previously flashed all boot binaries, follow the full flashing
instructions in the
[BSP image build with firmware](https://dragonwingdocs.qualcomm.com/Key-Documents/Firmware-Guide/build-firmware) first.

For subsequent kernel-only updates, you can incrementally flash just `efi.bin`
and `dtb.bin`:

```bash theme={null}
# Navigate to the build output directory
cd build/tmp/deploy/images/<machine>/<image>-*.rootfs.qcomflash/

# Flash the ESP and DTB partition images
fastboot flash efi efi.bin
fastboot flash dtb_a dtb.bin
fastboot reboot
```

<Note>
  Both `efi.bin` and `dtb.bin` must be flashed together after a kernel or DTS
  change to keep the kernel and device tree in sync.
</Note>

## Verify the running kernel

After the device reboots, confirm that the expected kernel version is running and
that the boot completed without errors.

### Connect to the device

Use one of the following methods to access a shell on the device:

* **Serial console (UART)** is recommended for early-boot inspection. For setup
  instructions see [Connect to your target](./connect-to-your-target).
* **ADB shell** once the device has fully booted:

```bash theme={null}
adb shell
```

* **SSH** to connect over the network using the device IP address:

```bash theme={null}
ssh root@<device-ip>
```

### Check the kernel version

```bash theme={null}
# Short version string
uname -r

# Full version, architecture, and build timestamp
uname -a

# Detailed version including compiler
cat /proc/version
```

The output of `uname -r` should reflect the kernel version you built and flashed
(for example, a `6.18.x` string for the LTS track).

### Inspect boot health

Check the kernel ring buffer for errors or warnings from early boot:

```bash theme={null}
# Print the first 50 lines of kernel messages
dmesg | head -50

# Filter for errors and warnings only
dmesg --level=err,warn
```

On systems using systemd, kernel messages from the current boot can also be
viewed with:

```bash theme={null}
journalctl -k -b
```

### Confirm kernel modules

Verify that the expected kernel modules loaded successfully:

```bash theme={null}
# List all loaded modules
lsmod

# Check if Qualcomm-specific modules are present
lsmod | grep qcom
```

To check if a required module is missing, confirm it was included in the kernel
configuration and that the image was rebuilt after the configuration change by
running following command on target:

```bash theme={null}
zcat /proc/config.gz | grep CONFIG_<Module>
```

### Troubleshooting

If the kernel version does not match what was built, or if the device fails
to boot:

* Confirm the flash completed without errors by re-running the `fastboot flash`
  commands and checking for `OKAY` responses.
* Confirm that both `efi.bin` and `dtb.bin` were flashed to the correct
  partitions (`efi` and `dtb_a` respectively).
* For boot failure and kernel panic analysis, see
  [Troubleshoot kernel issues](./troubleshoot-kernel-issues).
* For serial console log capture, see
  [Kernel logging](./kernel-logging).