> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build & Setup — RTC Testbench

## **Build & Setup**

### 1. Compile with meta-rtc

Follow the QLI 2.0 sync steps, then add the `meta-rtc` layer:

```bash theme={null}
# 1. Sync QLI 2.0 (see https://dragonwingdocs.qualcomm.com/Key-Documents/Yocto-Guide/build-qualcomm-linux)

# 2. Clone meta-rtc
git clone https://github.com/IIOTSS/meta-rtc.git

# 3. Copy the KAS overlay
cp meta-rtc/meta-rtc.yml meta-qcom/ci/meta-rtc.yml

# 4. Build with RT kernel and meta-rtc
kas build meta-qcom/ci/iq-9075-evk.yml \
          :meta-qcom/ci/qcom-distro.yml \
          :meta-qcom/ci/linux-qcom-rt-6.18.yml \
          :meta-qcom/ci/meta-rtc.yml
```

| KAS Overlay | Purpose |
| - | - |
| `iq-9075-evk.yml` | Board / machine configuration |
| `qcom-distro.yml` | Base distro configuration |
| `linux-qcom-rt-6.18.yml` | PREEMPT\_RT 6.18 kernel |
| `meta-rtc.yml` | OPC/UA binaries, test scripts, and configs |

***

### 2. Verify RT Boot

After flashing, confirm both devices boot with the correct RT kernel command line. CPUs 3–7 must be isolated:

```bash theme={null}
cat /proc/cmdline
```

Expected output:

```
root=PARTLABEL=rootfs rw rootwait console=ttyMSM0,115200 qcom_scm.download_mode=1 \
  isolcpus=3-7 irqaffinity=0-2 rcu_nocbs=3-7 rcupdate.rcu_expedited=1 cpuidle.off=1
```

***

### 3. Set Script Permissions

Run on **both** devices after every flash:

```bash theme={null}
chmod +x /usr/share/rtc-testbench/tests/common/postboot.sh
chmod +x /usr/share/rtc-testbench/tests/common/ptp.sh
chmod +x /usr/share/rtc-testbench/tests/opcua_qcom_emac/mirror.sh
chmod +x /usr/share/rtc-testbench/tests/opcua_qcom_emac/flow.sh
chmod +x /usr/share/rtc-testbench/tests/opcua_qcom_emac/ref.sh
```

***

### 4. Run postboot.sh

Run on **both** devices after every boot, before starting PTP:

```bash theme={null}
/usr/share/rtc-testbench/tests/common/postboot.sh
```

This script applies all RT tuning that cannot be set at initscripts time. It:

| Action | Why |
| - | - |
| Disables kernel tracing | Eliminates tracing overhead |
| Disables timer migration | Prevents timer callbacks migrating to RT CPUs |
| Affines workqueues to CPUs 0–2 | Keeps kernel work off RT-isolated CPUs |
| Disables all CPU idle states | Eliminates C-state re-entry latency |
| Sets CPU freq governor to `performance` | Prevents P-state transitions |
| Sets `sched_rt_runtime_us = -1` | Removes RT scheduling bandwidth cap |
| Affines all IRQs to CPUs 0–2 | Prevents interrupt delivery to RT CPUs |
| Removes WiFi modules (`ath11k`, `mac80211`) | `cfg80211_wiphy_work` was observed bursting on housekeeping CPUs and interfering with NAPI scheduling |
| Kills `redis-server`, `containerd` | Removes PM/I/O noise |
| Disables runtime PM on Ethernet MAC | Prevents device PM transitions during test |
| Disables runtime PM on UFS controller + clock gating/scaling | Prevents `ufshcd_gate_work` from stalling RT CPU |
| Disables runtime PM on all SCSI devices/hosts | `jbd2` was observed triggering SCSI PM wakeups on the RT CPU |
| Affines `end0` hardware IRQs to CPU 6 (mask `0x40`) | Co-locates NIC IRQ delivery with the NAPI threads pinned by `flow.sh` |

***

### 5. Start PTP Synchronization

Run on **both** devices simultaneously:

```bash theme={null}
/usr/share/rtc-testbench/tests/common/ptp.sh
```

* Defaults to interface `end0`
* Pins `ptp4l` to CPU 1 and `phc2sys` to CPU 2, both at `SCHED_FIFO 98`
* Uses 802.1AS-2011 endstation profile (`gPTP_qcom_emac.cfg`)
* Logs: `/var/log/ptp4l_run.log` and `/var/log/phc2sys_run.log`

> [!WARNING]
>
> Wait **5 minutes** after starting `ptp.sh` on both devices before proceeding. This allows the PTP clock offset to fully converge. Do not skip or shorten this wait.

***

> [card] [Test Execution](https://dragonwingdocs-staging.qualcomm.com/Suites/Industrial-Edge-Suite/rtc-testbench-execution.md)
>
> Configure peer MACs, run mirror/reference, interpret results

> [card] [Reference Files](https://dragonwingdocs-staging.qualcomm.com/Suites/Industrial-Edge-Suite/rtc-testbench-reference.md)
>
> Full source for postboot.sh, ptp.sh, and gPTP config
