Skip to content

Day31 - UART Debugging in Linux (TTY / Serial)

🎯 Objective

  • Learn systematic UART debugging methodology
  • Map issues to correct layer (DT / TTY / driver / hardware)
  • Understand common TX/RX failure patterns
  • Build practical troubleshooting workflow

🧠 1. Debugging Layer Model

Always debug from bottom to top:

1. Device Tree / Pinmux
2. TTY device node
3. Console / system occupation
4. termios configuration
5. Driver TX/RX flow
6. External wiring / peer device

🧠 2. Problem Classification

A. No /dev/ttyXXX

Possible causes:

  • overlay not applied
  • driver not probed
  • pinmux not configured

B. Device exists but unusable

Possible causes:

  • used as console
  • getty service attached
  • occupied by other process

C. TX not working

Symptoms:

  • write() succeeds
  • no data observed on wire

Possible causes:

  • wrong baudrate / format
  • TX interrupt not running
  • FIFO not draining
  • flow control blocking

D. RX not working

Symptoms:

  • read() returns nothing
  • or data inconsistent

Possible causes:

  • pin wiring issue
  • IRQ not triggered
  • flip buffer not pushed
  • termios blocking behavior

E. Strange behavior

Symptoms:

  • missing characters
  • delayed output
  • unexpected echo

Possible causes:

  • canonical mode enabled
  • echo enabled
  • CR/LF conversion

🧠 3. TX Debug Model

write()
  → xmit buffer
  → start_tx()
  → FIFO
  → TX interrupt refill
  → hardware

Key Checks

  • is data in xmit buffer?
  • is TX interrupt enabled?
  • is FIFO being written?
  • is hardware transmitting?

🧠 4. RX Debug Model

UART RX
  → IRQ
  → driver (PIO/DMA)
  → flip buffer
  → tty buffer
  → read()

Key Checks

  • is data entering FIFO?
  • is IRQ firing?
  • is driver pushing flip buffer?
  • is tty buffer consumed?

🧠 5. termios Impact

Important flags:

  • baudrate
  • cs8
  • -parenb
  • -cstopb
  • -icanon
  • -echo
  • clocal
  • cread
  • -crtscts

Key Insight

Many UART issues are actually termios issues

🧠 6. Flow Control Reality (PL011)

  • configured via termios (CRTSCTS)
  • hardware handles gating
  • driver refill logic unchanged

🧠 7. Debug Philosophy

Rule 1

Always isolate layer by layer

Rule 2

Do not trust shell tools blindly

Rule 3

Prefer deterministic tests (fixed length, raw mode)

Rule 4

Separate "data not sent" vs "data not observed"

🎯 8. Final Insight

UART debugging is about identifying where data stops moving

user → tty → driver → hardware → wire → peer