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

# RT kernel fundamentals

A real-time (RT) system provides deterministic, bounded response times to
external events. A system qualifies as real-time if it is free of unbounded
latency, its worst-case response time can be calculated with precision, and all
tasks meet their scheduling deadlines within defined jitter limits.

Qualcomm<sup>®</sup> Linux ships an LTS RT kernel (6.18.x) built on top of the upstream
`PREEMPT_RT` patch set. The RT kernel is targeted at kernel-space processes
that require deterministic scheduling. User-space applications cannot achieve
RT behavior by using the RT kernel alone; they must also be written with RT
scheduling policies (`SCHED_FIFO` / `SCHED_RR`) and pinned to isolated CPU
cores.

## How PREEMPT\_RT changes the kernel

The standard Linux kernel (`CONFIG_PREEMPT` or `CONFIG_PREEMPT_VOLUNTARY`)
allows certain critical sections to run non-preemptibly, causing unbounded
scheduling latency spikes. `PREEMPT_RT` eliminates this by:

| **Change**                                            | **Effect**                                                                                                        |
| :---------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| Converting spinlocks to sleeping mutexes (RT mutexes) | Critical sections become preemptible, reducing worst-case latency                                                 |
| Making interrupt handlers threaded by default         | ISRs run as kernel threads with a configurable priority, removing them from the non-preemptible interrupt context |
| Serialising RCU (Read-Copy-Update) callbacks          | RCU callbacks run in dedicated threads rather than softirq context, reducing jitter                               |
| Converting `local_lock_t` to per-CPU sleeping locks   | Per-CPU code paths become preemptible                                                                             |

The result is a kernel where nearly every code path can be preempted by a
higher-priority RT task, giving deterministic worst-case latencies in the
microsecond range on tuned Qualcomm hardware.

For the authoritative upstream documentation, see
[Linux kernel realtime](https://realtime-linux.org/).

## Required Kconfig options

The Qualcomm Linux `meta-qcom` layer enables `CONFIG_PREEMPT_RT` by default
through the `rt.config` configuration fragment included in the
`linux-qcom-rt_6.18.bb` recipe. The following table describes the key Kconfig
options and their role:

**Table: RT kernel Kconfig options**

|       **Option**       | **Default in RT build** | **Description**                                                                                                                                       |
| :--------------------: | :---------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
|   `CONFIG_PREEMPT_RT`  |           `y`           | Enables full kernel preemption. Mandatory for RT.                                                                                                     |
|  `CONFIG_NO_HZ_COMMON` |           `y`           | Infrastructure for tickless idle and full-tickless operation. Required by `NO_HZ_FULL`.                                                               |
|   `CONFIG_NO_HZ_FULL`  |           `y`           | Suppresses scheduling-clock interrupts on CPUs with a single runnable task. Reduces jitter on isolated RT cores.                                      |
|    `CONFIG_CPUSETS`    |           `y`           | Allows grouping CPUs into sets for affinity control. Required for isolating RT tasks to dedicated cores.                                              |
| `CONFIG_CPU_ISOLATION` |           `y`           | Enables `isolcpus=` kernel parameter support to remove cores from the general scheduler.                                                              |
|    `CONFIG_HZ_1000`    |           `y`           | Sets the kernel timer frequency to 1000 Hz (1 ms tick period). Higher `HZ` values increase scheduling granularity at the cost of more timer overhead. |

Verify that these options are active on a running RT system:

```bash theme={null}
zcat /proc/config.gz | grep -E "CONFIG_PREEMPT|CONFIG_NO_HZ|CONFIG_CPUSETS"
```

Expected output:

```text theme={null}
# CONFIG_PREEMPT_NONE is not set
# CONFIG_PREEMPT_VOLUNTARY is not set
# CONFIG_PREEMPT is not set
CONFIG_PREEMPT_RT=y
CONFIG_NO_HZ_COMMON=y
CONFIG_NO_HZ_FULL=y
CONFIG_CPUSETS=y
```

## RT vs standard kernel trade-offs

Choosing the RT kernel involves accepting specific trade-offs:

|         **Dimension**         |       **Standard kernel**      |                           **RT kernel**                          |
| :---------------------------: | :----------------------------: | :--------------------------------------------------------------: |
| Worst-case scheduling latency |      Unbounded (μs to ms)      |                Bounded (low μs on tuned hardware)                |
|           Throughput          | Higher, fewer context switches |              Slightly lower, more preemption points              |
|       Power consumption       |          Lower in idle         |            Higher, `NO_HZ_FULL` keeps RT cores active            |
|      Debugging complexity     |         Standard tools         | RT-specific tools (`cyclictest`, `ftrace` with `hwlat_detector`) |
|            Use case           |   General-purpose, multimedia  |      Industrial control, robotics, time-sensitive networking     |

<Note>
  The RT kernel is supported on all Qualcomm Linux hardware platforms
  (QCS6490, IQ-9075, IQ-8275, IQ-615). Latency numbers depend on the
  specific SoC, CPU topology, and tuning applied. Always measure on target
  hardware and do not rely solely on simulation results.
</Note>

## Verify RT is active

After booting the RT kernel, confirm full RT preemption is enabled:

```bash theme={null}
# Kernel version string includes -rt suffix
uname -r
# Example: 6.18.0-rt1+

# Confirm PREEMPT_RT in the version banner
cat /proc/version

# Verify the Kconfig flag
zcat /proc/config.gz | grep CONFIG_PREEMPT_RT
# Expected: CONFIG_PREEMPT_RT=y
```