rtl8196e-uart-bridge — cumulative driver audit¶
Cumulative audit ledger. The opening table and the finding registry (§5) are authoritative. §1 records the passes; §2–§4 keep the technical conclusions that the code comments and
DESIGN.md/SECURITY.mdrely on.
| Current state | Authoritative value |
|---|---|
| Audited code | driver v1.7 |
| Last audit pass | 2026-07-30 — C6, live-EZSP target validation of v1.7 |
| Last fully audited baseline | v1.6 (pass A2) |
| Post-baseline changes | v1.7 implements BRIDGE-009…011, including the teardown lock-order correction (C4); each change was reviewed and target-validated in passes C3–C6 |
| Validation state | W=1 builds and complete vmlinux links; BRIDGE-009…011 target gates passed on Linux 6.18 and 7.1 (C5, C6) |
| Maintained kernels | Linux 6.18 and 7.3; the two sources differ only by the kernel_bind() cast to struct sockaddr_unsized * required since Linux 7.1 |
| Scope | driver, Kconfig/Makefile, tty/socket/GPIO concurrency and exposed TCP/sysfs surfaces |
| Companions | DESIGN.md, README.md, SECURITY.md |
1. Audit-pass ledger¶
| Pass | Date | Baseline | Scope and outcome | IDs |
|---|---|---|---|---|
| A1 | 2026-06-12 | v1.3 → v1.4 | first standalone audit: full read of the source against the 6.18 tty, socket, gpiod and kernel/params.c APIs. No memory-safety flaw; S01…S03 implemented as v1.4, bench-checked on the bench gateway (armed at boot, three connect/disconnect cycles) |
BRIDGE-001…008, S01…S03 |
| C1 | 2026-06-13 | v1.4 → v1.5 | flow-control capability / firmware-mode split; change-local review | — |
| C2 | 2026-07-16 | v1.5 → v1.6 | blmode_pulse logs the sequence it performed, not an outcome it cannot observe; change-local review |
— |
| A2 | 2026-07-30 | v1.6 | independent full security/performance re-audit (source read before this ledger); corrected A1's BRIDGE-002 conclusion; targeted W=1 builds on both kernels, checkpatch.pl --strict style debt only, no runtime test |
BRIDGE-009…011 opened |
| C3 | 2026-07-30 | v1.6 → v1.7 | BRIDGE-009…011 implemented (§3); objects and complete vmlinux links with W=1 on both kernels |
BRIDGE-009…011 |
| C4 | 2026-07-30 | v1.7 candidate | target-discovered teardown self-deadlock fixed (§3); static lock-order review and W=1 links |
BRIDGE-011 |
| C5 | 2026-07-30 | v1.7 | target regression at 460800 baud, hardware flow control: 6.18 stop/start; 7.1 ten direct disarm/arm cycles, idle A→B replacement, teardown with a dormant client; no BUG, oops, hung task, call trace or warning | BRIDGE-009, 011 |
| C6 | 2026-07-30 | v1.7 | remaining gates closed with protocol-valid, read-only EZSP traffic (§4) | BRIDGE-009…011 |
Passes C5 and C6 ran on Linux 6.18.38 and 7.1.3. The 7.2 line carries the
same driver source with the kernel_bind() cast noted above.
2. Security review¶
2.1 Attack surface¶
| Surface | Who can reach it | Exposure |
|---|---|---|
TCP listener (default 0.0.0.0:8888) |
any peer that can route to the gateway | Unauthenticated, plaintext EZSP/CPC/Spinel session with the radio. Deliberate, documented, mitigated by BRIDGE_BIND=127.0.0.1 + SSH tunnel (SECURITY.md). Since v1.7 a new connection synchronously evicts the connected client (BRIDGE-009). |
| UART RX bytes (radio side) | EFR32 firmware (or whoever flashed it) | In flow_control=sw, bare 0x11/0x13 gate the TCP→UART direction — bounded to 1 s by the fail-open timer, so a hostile/wedged radio cannot park the worker or hang disarm. In hw/none modes, bytes are forwarded verbatim. |
| Module parameters (sysfs) | root only — modes 0600/0644/0444/0200, write bit owner-only on every knob | Validated setters (§2.2). Pulse knobs hold the global built-in param_lock for their duration (BRIDGE-003). |
Device tree /radio-bridge node |
build-time (trusted) | Seeds nrst_gpio / blmode_gpio and the realtek,hw-flow-control capability (the flow_control default) only; GPIO lines range-checked (args[0] <= 31). The capability is also a ceiling: an hw request is clamped to sw when the board lacks it, so CRTSCTS is never asserted on an unwired UART. |
2.2 Verified correct¶
Established by A1 on v1.3 and re-confirmed by A2 on v1.6 (no memory corruption, UAF or double release found):
- Socket ownership.
bridge_send_to_client_locked()never releases the client socket on error; it onlykernel_sock_shutdown()s it to wake the reader. Exactly one party releases each socket. Since v1.7 the per-client worker owns and releases its socket (§3). stopping_workerhandshake. A connection accepted inside a disarm/reconfig teardown window is released immediately instead of being installed as state the teardown no longer knows about; the flag is re-checked after every re-acquisition ofbridge_lock.listen_socklifetime vs the lockless reader. The accept worker readsstate.listen_sockwithREAD_ONCE(); teardown keeps the pointer populated until the synchronouskthread_stop()has returned.- Bounded XOFF gate. The sw-mode TX pause is a 1 s fail-open wait that also
polls
kthread_should_stop(). A network client cannot inject flow control: the XON/XOFF scan runs only on the UART→TCP direction. - nRST / blmode pulses. Open-drain throughout (driven low or floated, never
driven high against the EFR32's RESETn pull-up); write-only mode 0200,
serialized by
nrst_pulse_lock, lines claimed per pulse.blmode_pulsevalidatesblmode_gpio >= 0andblmode_gpio != nrst_gpioand releases the already-claimed line on error. - Input validation. baud 1200–4 000 000; port 1–65535; gpio lines 0–31
(blmode −1–31); brightness 0–255;
bind_addrthroughin4_pton();flow_controlparsed into a closed enum (numeric ABI kept forflash_efr32.sh); string params copied withstrscpyinto fixed buffers with-ENAMETOOLONGon overflow. - No torn reads. All
u64counters are read and written underbridge_lock(32-bit MIPS has no atomic 64-bit loads); the lockless reads areREAD_ONCE/WRITE_ONCEpairs with documented staleness tolerance. kernel_getpeername()intostruct sockaddr_inis safe on an AF_INET socket.tty_kopen_exclusiveguarantees no userspace open can race the kernel-side claim.
2.3 Standing risk and deployment contract¶
Anyone who can reach the listen port owns the radio; the threat model and the
loopback + SSH mitigation live in SECURITY.md. The deployment security
contract is one active TCP client at a time on the bridge port, met by
BRIDGE-009's synchronous replacement. Authentication, encryption and
loopback-only binding are deployment choices, outside that contract.
3. Findings¶
BRIDGE-001 — config-transition atomicity depends on the global param lock (low, latent)¶
bridge_disarm_locked() and the relisten path drop bridge_lock around
kernel_sock_shutdown() + synchronous kthread_stop(). In isolation, that
window would let a concurrent enable=1 arm fresh state that the resuming
teardown then wipes (NULL listen_sock under a live worker, orphaned kthread,
leaked refs). It is unreachable today because every sysfs write to a built-in
module's parameters runs under the global param_lock
(param_attr_store() → kernel_param_lock(NULL) in kernel/params.c), and
boot-time parsing is single-threaded. The risk is that the invariant lives
outside the driver: a future non-param entry point (reboot notifier,
platform-driver conversion, ioctl) would reopen the race. S01 (v1.4): the
dependency is documented at the bridge_lock definition and at the disarm
drop-and-retake site.
BRIDGE-002 — replace-on-connect claim (low; superseded by BRIDGE-009)¶
A1 inferred from the if (state.client_sock) branch that a new connection
replaced the current one, and amended DESIGN.md / SECURITY.md accordingly.
A2 showed that branch was unreachable in v1.6 (§BRIDGE-009). v1.7 implements
replacement for real, so the amended documents now describe the code.
BRIDGE-003 — pulse knobs hold the global param lock (info)¶
Because of the same kernel/params.c serialization, nrst_pulse holds the
global param_lock for ~100 ms and blmode_pulse for ~1.1 s
(msleep(100) + msleep(1000); the v1.3 sequence audited by A1 held the
blmode pin for 5 s, ~5.1 s in total). During that time every sysfs parameter
read/write of every built-in module blocks, including this driver's
stats/armed getters. Only the UART→TCP hot path
(bridge_port_receive_buf) is genuinely unaffected. Operationally harmless
(rare, root-triggered maintenance actions). S03 (v1.4): the
nrst_pulse_lock comment now states this behaviour.
BRIDGE-004 — connection-lifecycle messages not ratelimited (low)¶
A LAN peer flapping connections could churn the kernel log and the ramfs
/var/log/messages. S02 (v1.4): the connect/replace/disconnect messages
are pr_info_ratelimited.
BRIDGE-005 — kthread names truncated (info)¶
DRV_NAME "-worker" (and, since v1.7, DRV_NAME "-client") exceed
TASK_COMM_LEN; ps shows rtl8196e-uart-b. Cosmetic.
BRIDGE-006 — stale ancillary text (info)¶
The Kconfig help predated the v1.3 blmode_pulse/blmode_gpio knobs, and
README.md misstated the source size. S03 (v1.4) refreshed the Kconfig
help; the README figure was corrected by A1.
BRIDGE-007 — DT gpio phandle controller is ignored (info, accepted)¶
bridge_seed_defaults_from_dt() consumes only the line number of
nrst-gpios/blmode-gpios; the pulse paths claim through the
"gpio-rtl819x" label. Irrelevant on this single-gpiochip SoC and documented
in README.md; a multi-gpiochip port must revisit it.
BRIDGE-008 — tty path→devt TOCTOU (info, accepted)¶
resolve_tty_devt() resolves the path, then tty_kopen_exclusive() opens by
dev_t. Exploiting the gap requires root, on a static devtmpfs, against a
root-only knob. No action.
BRIDGE-009 — first client monopolized the worker (medium, fixed v1.7)¶
Defect (v1.6). A single worker called kernel_accept(), then stayed in
blocking kernel_recvmsg() on the accepted socket until that client
disconnected. state.client_sock was therefore always NULL at accept time,
the replacement branch was dead, and an idle peer could hold the radio
indefinitely (TCP keepalive does not evict a live, idle peer).
Fix (v1.7). Accepting and client RX are split. The accept worker stays in
kernel_accept() while a client is active; each client gets its own TCP→UART
worker. On a new accept, the accept worker detaches the old client from shared
state, shuts its socket down, joins its worker synchronously (kthread_stop),
then publishes the new socket and worker. The client worker exclusively owns
and releases its socket; after a natural EOF it clears client_sock, switches
the LED off and stays dormant until joined, which closes the EOF-versus-
replacement window. At most one dormant client is retained. UART bytes
arriving during the short no-client window of a replacement are counted in
drops_nocli.
Validated: idle A→B on 7.1 (C5: A saw EOF 3 ms after B connected); active A→B during EZSP traffic on 6.18 and 7.1 (C6), LED continuity (§4).
BRIDGE-010 — hot bind_addr reconfiguration could keep the old exposure (medium, fixed v1.7)¶
Defect (v1.6). Relisten bound the new listener before shutting the old
one down. Moving from the default 0.0.0.0:8888 to 127.0.0.1:8888 — the
documented hardening transition — normally failed with -EADDRINUSE, the
setter rolled back, and the wildcard listener stayed up. A successful
reconfiguration also dropped the connected client, contrary to DESIGN.md.
Fix (v1.7). Relisten stops and releases the old accept worker/listener
before binding the replacement; the client socket/worker is left untouched. If
the new bind or worker creation fails, the old parameter is restored and the
old listener recreated; if that rollback fails too, the bridge fully disarms
rather than reporting armed=1 without a listener.
Validated: C6 (§4).
BRIDGE-011 — client_ops swaps did not exclude flip-buffer callbacks (low, fixed v1.7)¶
Defect (v1.6). Arm, unwind and disarm assigned tty->port->client_ops
under tty_lock(), but tty_buffer.c calls client_ops->receive_buf() under
the flip buffer's own exclusion. Both ops tables are static, so there was no
UAF; the risks were a formal data race and boundary byte loss or
misdirection.
Fix (v1.7). Arm takes tty_buffer_lock_exclusive(), installs the bridge
client_ops before opening the UART, and holds the exclusion until tty,
socket and acceptor state are published. Disarm removes socket visibility,
stops both workers, closes the UART, then restores the saved client_ops
under flip-buffer exclusion.
Lock-order correction (C4). The first v1.7 candidate took the exclusion
and then called uart_close(); the close path's tty_buffer_flush() takes the
same non-recursive port->buf.lock, and disarm deadlocked against itself
(tty_buffer_flush → tty_ldisc_flush → tty_port_close_start →
tty_port_close → bridge_disarm_locked → param_set_enable). The corrected
v1.7 runs close with both flip-buffer exclusion and bridge_lock dropped, and
takes the exclusion solely around the client_ops restore. The partially-armed
error unwind uses the same order; the pre-open failure path also drops
bridge_lock around tty_kclose().
Validated: C5 and C6 teardown cycles (§4). Lockdep/KCSAN were not enabled; they would need a separate instrumented kernel and are not a functional gate.
Simplification items¶
| ID | Change | Status |
|---|---|---|
| BRIDGE-S01 | Document the param-lock dependency (BRIDGE-001) | implemented (v1.4) |
| BRIDGE-S02 | pr_info_ratelimited on connection-lifecycle messages (BRIDGE-004) |
implemented (v1.4) |
| BRIDGE-S03 | Refresh Kconfig help and the nrst_pulse_lock comment (BRIDGE-003, BRIDGE-006) |
implemented (v1.4) |
Considered and rejected¶
- Platform-driver conversion to bind
/radio-bridgeproperly (would also fix BRIDGE-007): churn for no functional gain, and it would turn BRIDGE-001's latent race into a live one. - Persistent gpiod descriptors: claim-per-pulse keeps the lines free for
other consumers and makes
nrst_gpiochanges stateless. tty_dev_name_to_number()instead ofkern_path(): the parameter is a path; name lookup would drop symlink semantics.- Spinlock or lock-free hot path: measured mutex cost ≈ 8 µs per
receive_bufat 892 857 baud, ~2.5 % worker CPU (DESIGN.md). sk_data_readycallbacks instead of blocking workers: would need its own queue and flush discipline for no measured benefit.- Table-driven param boilerplate: each setter's rollback differs (re-arm, re-termios, re-listen); a generic helper would obscure more than it saves.
- Previously rejected in
DESIGN.mdand still valid: line discipline hook, multi-client fan-out, netlink control plane, IRAM placement of the hot path.
Performance (A2)¶
- UART→TCP is non-blocking (
MSG_DONTWAIT) and accounts partial/error drops. Holdingbridge_lockover one send is acceptable on this single-core target; stats/config readers share that latency. - TCP→UART reads are bounded to 512 bytes; write retries are bounded by the
chunk length plus four no-progress sleeps. No unbounded allocation or queue;
drops_txis the operational signal for a fast peer. - The sw flow-control scan is linear per RX chunk; alternating XON/XOFF can fragment sends, but that input comes from the trusted radio firmware and is bounded by the chunk size.
4. Target validation of v1.7 (C5, C6)¶
Bench gateway, NCP-UART 7.5.1 firmware at 460800 baud with hardware flow
control. C6 traffic was generated by universal-silabs-flasher/Bellows:
protocol-valid, read-only EZSP; no radio configuration was changed.
- BRIDGE-009. On each kernel, client A started an EZSP probe and B
connected 350 ms later: A was evicted, B completed and detected
ApplicationType.EZSP7.5.1.0 (7.1 countersrx=773 tx=931, all drop counters 0). STATUS LED brightness read 255 with A, 255 after B replaced A, 0 after B closed. - BRIDGE-010. With client A open on each kernel:
0.0.0.0:8888→127.0.0.1:8888→0.0.0.0:8888, port 8888 → 8899, a forced failed change to the occupied port 22, then restoration to 8888. After the forced conflict the write failed,armedstayed 1, the parameter read back 8899 with exactly one 8899 listener; the driver then restored exactly one0.0.0.0:8888listener. A saw no EOF or reset throughout. - BRIDGE-011. Ten disarm/arm cycles per kernel during an active EZSP
handshake (samples
rx=115 tx=125before teardown), eacharmed=0→1with NCP recovery;drops_nocli=7(expected teardown window),drops_err=0,drops_tx=0. Linux 7.1 additionally ran five teardowns under a sustained Bellowsget_board_infoloop (baseline 71 calls in 3 s,rx=5807 tx=4036, zero drops; teardown samples 5156/3187, 4454/2750, 4753/2925, 4990/3087, 4805/2963), each with zero error/TX drops and a final NCP 7.5.1 redetection. One load establishment timed out atrx=112 tx=114; no teardown was performed, a full probe recovered ASH and the replayed cycle gave the last sample above. - Neither kernel logged a BUG, oops, hung/blocked task, call trace, deadlock or
warning. On 6.18 the 8250 report ended with UART1
tx=3472 rx=2766and no framing/overrun flag (7.1 does not expose that proc report in this build).
A long-duration maximum-throughput soak was not repeated for v1.7; it is optional performance evidence, distinct from these lifecycle tests.
5. Finding ID registry¶
| ID | Severity | Status | Summary |
|---|---|---|---|
| BRIDGE-001 | low (latent) | mitigated (v1.4) | transition atomicity relies on the global param lock; documented in-code at both sites |
| BRIDGE-002 | low | superseded by BRIDGE-009 | A1 inferred replace-on-connect from a branch that was unreachable until v1.7 |
| BRIDGE-003 | info | comment fixed (v1.4) | pulses hold the global param lock ~100 ms (nrst) / ~1.1 s (blmode) |
| BRIDGE-004 | low | fixed (v1.4) | connection-lifecycle messages ratelimited |
| BRIDGE-005 | info | open | kthread comm truncated to rtl8196e-uart-b |
| BRIDGE-006 | info | fixed (v1.4) | Kconfig help covers the blmode knobs; README size corrected |
| BRIDGE-007 | info | accepted | DT gpio controller phandle ignored, line number only |
| BRIDGE-008 | info | accepted | tty path→devt TOCTOU, root-only, negligible |
| BRIDGE-009 | medium | fixed (v1.7), target-validated | new client synchronously replaces the old one; one active client at a time |
| BRIDGE-010 | medium | fixed (v1.7), target-validated | conflict-safe relisten, client preserved, rollback to one valid listener |
| BRIDGE-011 | low | fixed (v1.7), target-validated | client_ops swaps quiesced against flip-buffer callbacks; teardown lock order corrected |
| BRIDGE-S01..S03 | — | implemented (v1.4) | see §3, simplification items |