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

# OTA and upgrade considerations

OTA updates and manual kernel upgrades on an RT system require additional steps
beyond the standard kernel upgrade procedure. The RT tuning configuration is
not automatically preserved, and the post-upgrade latency baseline must be
re-validated before returning the device to production.

## Upgrade workflow

OTA updates on Qualcomm<sup>®</sup> Linux replace the UKI image on the ESP and, if
applicable, the DTB in the `dtb_a` partition. The flash procedure is identical
for standard and RT kernels.

### 1. Record the current RT kernel version

Before upgrading, capture the running kernel version and worst-case latency
as a baseline:

```bash theme={null}
uname -r
cat /proc/version
```

Run a short cyclic test to establish the pre-upgrade latency baseline:

```bash theme={null}
cyclictest -a 7 -t 1 -m -l 10000 -i 1000 -p 99 -h 100
```

Record the `Max` latency value from the output.

### 2. Flash the new RT image

**Via Yocto build:**

```bash theme={null}
# Build the new RT image
kas shell meta-qcom/ci/<board>.yml:meta-qcom/ci/linux-qcom-rt-6.18.yml:meta-qcom/ci/qcom-distro.yml
bitbake qcom-multimedia-image

# Flash both ESP and DTB partitions
cd build/tmp/deploy/images/<Machine>/<Image>-*.rootfs.qcomflash/
fastboot flash efi efi.bin
fastboot flash dtb_a dtb.bin
```

**Via standalone ESP update:**

```bash theme={null}
fastboot flash efi efi.bin
fastboot flash dtb_a dtb.bin
```

### 3. Reboot and verify the updated kernel

```bash theme={null}
fastboot reboot
uname -r   # Confirm the new -rt version string
```

### 4. Re-apply RT tuning and run post-upgrade validation

RT tuning settings do not survive a reboot. Re-apply them manually or via the
tuning service (see below) before running validation:

```bash theme={null}
cyclictest -a 7 -t 1 -m -l 100000000 -i 1000 -p 99 -h 100
```

Compare the `Max` latency against the pre-upgrade baseline. A regression
indicates a configuration or kernel issue. See
[RT validation and known limitations](./rt-validation-and-known-limitations).

## Persist RT tuning across reboots

RT tuning commands are one-shot where they apply to the running system and are lost
on reboot. To re-apply tuning automatically after every boot, package the tuning
commands in a systemd service:

**1. Create the tuning script:**

```bash theme={null}
cat > /usr/local/bin/rt-tuning.sh << 'EOF'
#!/bin/sh
# Disable timer migration
echo 0 > /proc/sys/kernel/timer_migration

# Affine workqueues to housekeeping CPUs (CPUs 0-6 on QCS6490/IQ-9075/IQ-615)
for wq in /sys/devices/virtual/workqueue/*; do
    [ -w "$wq/cpumask" ] && echo 7F > "$wq/cpumask"
done

# Set all CPUs to performance governor
for policy in /sys/devices/system/cpu/cpufreq/policy*; do
    [ -w "$policy/scaling_governor" ] && echo performance > "$policy/scaling_governor"
done

# Disable RT accounting/throttling
echo -1 > /proc/sys/kernel/sched_rt_runtime_us

# Set IRQ affinity to housekeeping CPUs 0-6
ALLOW_CPUS="0,1,2,3,4,5,6"
cpu_list_to_mask() {
    MASK=0
    for cpu in $(echo $1 | tr ',' ' '); do
        MASK=$((MASK | (1 << cpu)))
    done
    printf "%x\n" "$MASK"
}
MASK=$(cpu_list_to_mask "$ALLOW_CPUS")
for irq in /proc/irq/[0-9]*; do
    smp_file="$irq/smp_affinity"
    [ -w "$smp_file" ] && echo "$MASK" > "$smp_file" 2>/dev/null
done
EOF
chmod +x /usr/local/bin/rt-tuning.sh
```

**2. Create the systemd unit file:**

```ini theme={null}
# /etc/systemd/system/rt-tuning.service
[Unit]
Description=RT kernel tuning
After=multi-user.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/rt-tuning.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
```

**3. Enable the service:**

```bash theme={null}
systemctl enable rt-tuning.service
systemctl start rt-tuning.service
```

For IQ-8275, adjust the workqueue mask and IRQ affinity CPU list to match
the platform topology (CPUs 0-2, 4-7; mask `F7`). See
[RT validation and known limitations](./rt-validation-and-known-limitations)
for the IQ-8275-specific tuning commands.

## Known upgrade constraints

**Kernel and DTB version alignment**

Always flash `dtb.bin` and `efi.bin` together. Mismatched kernel and DTB
versions can cause device tree binding failures and boot errors.

**Initramfs**

If the initramfs is customised for the RT build (for example, to run the
tuning script during early boot), rebuild it when upgrading the kernel version.
A stale initramfs built against an older kernel may fail to load required
modules.

**PREEMPT\_RT configuration fragments**

Custom `.cfg` Kconfig fragments added to `linux-qcom-rt_6.18.bb` must be
reviewed after every kernel version bump. Options may be renamed, removed, or
have changed dependencies. A mismatched fragment causes a Yocto build warning
(`Fragment ... references unknown config`) or a silent no-op.

**Secure boot**

If the device is configured for secure boot, the new UKI must be signed with
the correct key before flashing. An unsigned or incorrectly signed UKI is
rejected by UEFI firmware at boot. See
[UEFI and systemd-boot](./uefi-and-systemd-boot).