# RT-4D Firmware — Main Loop, UI State Machine & UI-Rewrite Hook Points

**Key:** `main-loop` · **Target:** `stock-fw/rt4d_stock_v3.25_abs_0x08002800.bin` (ARM Cortex-M4F Thumb, load/vaddr base `0x08002800`).
All disassembly via capstone `CS_ARCH_ARM + CS_MODE_THUMB`.

This is the hook-point document for a full UI rewrite. It nails down (1) the boot→superloop path, (2) the single UI screen-state variable and the **two mirror-image dispatch tables** (draw + input) keyed on it, (3) how screens redraw and transition, and (4) the exact vaddrs and strategy to redirect rendering + navigation into custom code while keeping all lower-level radio/codeplug/serial APIs intact.

---

## 0. TL;DR — the hook

- **Screen-state variable:** `g_screen = *(uint8_t*)0x200008B3` (0..11). A shadow `*(uint8_t*)0x200008B2` holds the previous screen. `0x200008B3` is referenced by **55** literal-pool words across the image — it is the central UI selector.
- **Draw dispatcher:** `ui_draw_dispatch @0x0801E1BC` — `tbb`-jumps on `g_screen` (12 entries) to the current screen's incremental redraw routine. Called every UI tick from the scheduler at `0x080207E6`.
- **Input dispatcher:** `ui_process_key @0x0801E6EC` — pulls a keycode/keystate from the key struct at `0x20000B57`, then `tbb`-jumps on `g_screen` (12 entries, table `@0x0801E780`) to the current screen's key handler `handler(u8 keycode, u8 keystate)`. Called every UI tick from the scheduler at `0x08020816`.
- **Hook strategy (recommended):** patch the two `bl` call sites in the scheduler — `0x080207E6` (`bl ui_draw_dispatch`) and `0x08020816` (`bl ui_process_key`) — to call your own router. Your router owns rendering + navigation and calls the stock lower-level APIs (draw_string, keys, RF, DMR, codeplug). This is a 2-instruction redirect and leaves the serial/CPS path and codeplug format completely untouched. See §5.

---

## 1. Boot → application superloop

### 1.1 Reset / CRT startup (library glue, not app logic)

```
Reset 0x08002AC0: SystemInit(0x0801DA2D) ; then bx __main(0x080029E1)
__main 0x080029E0: bl 0x080029E8 (__scatterload / RW+ZI init, RLE decompressor @0x08002A1E)
                   bl 0x08002AA0 (__rt_entry)
__rt_entry 0x08002AA0: sequence of ARM C-lib inits, then:
                   bl 0x0802136C   <-- the real application main / superloop
```

The `0x08002AA0..0x08002D18` cluster is ARM compiler runtime (heap/stack setup, `bkpt 0xAB` semihosting stubs, the ADC ISR tail). The application proper is **`app_main @0x0802136C`**.

### 1.2 `app_main @0x0802136C` — the top-level superloop  ★ HARD ENTRY POINT

```
0x0802136C  movs r4,#0
0x0802136E  bl 0x0801DAD0                       ; low-level HW/clock/periph bring-up
0x08021372  ldr r0,=0x08002800 ; ldr r1,=0xE000ED08 ; str r0,[r1]  ; VTOR = app vector base
0x08021378  bl 0x08021024                       ; init B
0x0802137C  movs r0,#0xC8 ; bl 0x08007946       ; init C (display/boot?)
0x08021382  bl 0x080127D4                       ; init D
0x08021386  bl 0x08003060                       ; init E (codeplug/settings load)
0x0802138A  b  0x08021414                       ; -> jump to loop top
--- LOOP TOP ---
0x0802138C  if (*(u8*)0x20000C54) bl 0x0801A38C  ; reboot flag -> NVIC_SystemReset
0x08021396  modeA = *(u8*)0x20000B66            ; serial/session mode gate
            modeB = *(u8*)0x20000C12
            spiMode = *(u8*)0x20000C57
            if (modeA==0 && modeB!=2 && modeB!=4 && spiMode==0)
0x080213B2      bl 0x080207DC                    ; ★ NORMAL UI TICK (radio running)
            else  ...                            ; PC-programming / SPI-write session paths:
0x080213C2      modeB==2 -> bl 0x08019A7C        ; CPS mode handler
0x080213E2      modeB==4 -> bl 0x0801F84C        ; serial framer
0x080213EE      modeA!=0 -> bl 0x0801F84C ; bl 0x0801F540 ; drain FM100B rx (0x200082EF, 0x08006CB8)
0x0802140C  bl 0x0801F854                        ; serial poll (every iteration)
0x08021410  bl 0x0801FE50                        ; housekeeping (every iteration)
0x08021414  b  0x0802138C                        ; loop
```

**Interpretation.** The superloop first honours a reboot request, then branches on **serial-session state**: when the radio is *not* in a PC-programming / SPI-write session (`0x20000B66==0`, `0x20000C12∉{2,4}`, `0x20000C57==0`), it runs the **normal UI tick `0x080207DC`**. Otherwise it services the CPS/serial paths. `0x0801F854` (serial poll) and `0x0801FE50` (housekeeping) run unconditionally every pass.

> **Boundary note (respect the CPS/codeplug contract).** The serial session vars `0x20000B66 / 0x20000C12 / 0x20000C57 / 0x20000C54` and the handlers `0x08019A7C / 0x0801F84C / 0x0801F540 / 0x0801F854` are the **CPS protocol + SPI region-write engine** (documented in RT-4D_RE_Report §4). A UI rewrite must leave this entire `else` branch and the two unconditional serial calls **exactly as-is** — that is the serial/CPS boundary. Only replace what happens *inside* the normal UI tick `0x080207DC`.

| vaddr | name | signature | notes |
|---|---|---|---|
| 0x0802136C | `app_main` | `void app_main(void) __attribute__((noreturn))` | The application superloop. Sets VTOR, runs inits, then loops. **Do not relocate** — reset path branches here. |
| 0x0801DAD0 | `hw_init` | `void hw_init(void)` | clock/peripheral bring-up (called first) |
| 0x08003060 | `codeplug_load_init` | `void(void)` | last init; loads settings/channels from SPI (candidate) |
| 0x0801A38C | `nvic_system_reset` | `void(void) noreturn` | writes AIRCR `0x05FA0004` (reboot). Gated by `0x20000C54`. |
| 0x080207DC | `ui_tick_normal` | `void(void)` | **the normal-mode UI scheduler** (see §2) |
| 0x0801F854 | `serial_poll` | `void(void)` | runs every loop; part of CPS path — keep |
| 0x0801FE50 | `housekeeping` | `void(void)` | runs every loop (battery/timers) |

---

## 2. `ui_tick_normal @0x080207DC` — the cooperative UI scheduler

This is **not** the state machine itself; it is a fixed list of periodic subsystems, several gated by down-counters so they run at different rates. The screen draw + key dispatch are two of its calls.

```
0x080207DE  bl 0x0801F84C   ; serial framer (shared)
0x080207E2  bl 0x0801F9C0   ; ? (reads 0x20000C8A menu-key state, 0x200029BB struct)
0x080207E6  bl 0x0801E1BC   ; ★ ui_draw_dispatch  (SCREEN DRAW — hook here)
0x080207EA  bl 0x0801E050   ; ui_sidekey_dispatch (side/long-press hotkeys — see §3.3)
0x080207EE  bl 0x0801E3F8   ; build display line buffer (reads 0x200008B3)
0x080207F2  bl 0x0801FAC8   ; ...
0x080207F6  bl 0x0801F504
0x080207FA  bl 0x0801FDA4
0x080207FE  bl 0x0801FDDC
0x08020802  bl 0x0801FE0C
0x08020806  bl 0x0801DFD0
--- period-gated tasks: counter at 0x20000BF1.. reloads to a period when it hits 0 ---
0x0802080A  if(--tick@0x20000BF1==0){reload 1;   bl 0x0801E6EC(key?) ...}   see note
0x08020816  bl 0x0801E6EC   ; ★ ui_process_key   (SCREEN INPUT — hook here)
0x0802081A  bl 0x08020288
   ... 0x20000BF2 (reload 4), 0x20000BF3 (reload 0xA), 0x20000BF5 (0xC8),
       0x20000BF6 (0x1F4), 0x20000BF8 (0x3E8): slower periodic tasks (RSSI, battery, scan, etc.)
0x080208DC  return
```

Concretely, the **two dispatch calls you care about** are both unconditional every UI pass:
- `0x080207E6  bl 0x0801E1BC`  → screen **draw** dispatch
- `0x08020816  bl 0x0801E6EC`  → screen **key** dispatch

(Down-counter reloads observed: `0x20000BF1`→1, `0x20000BF2`→4, `0x20000BF3`→0xA, `0x20000BF5`→0xC8, `0x20000BF6`→0x1F4, `0x20000BF8`→0x3E8 — these throttle the slower periodic tasks; the two dispatchers themselves are not throttled.)

---

## 3. The UI state machine

### 3.1 The state variable

```
g_screen  = *(uint8_t*)0x200008B3   ; current screen id, 0..11 (0x0B)
g_screen_prev = *(uint8_t*)0x200008B2   ; previous screen (used for restore/back)
```

Both dispatchers guard with `cmp g_screen,#0x0C ; bhs <default>` before the `tbb`, so **valid ids are 0..11**.

### 3.2 The two mirror dispatch tables (draw + input)

Both are `tbb [pc,r0]` byte-offset jump tables indexed by `g_screen`. They are **positionally parallel**: index *i* in the draw table and index *i* in the input table are the same screen.

**DRAW dispatcher** `ui_draw_dispatch @0x0801E1BC`:
```
0x0801E1BE  bl 0x080136E4                 ; clear per-field dirty flags (row @0x20002512)
0x0801E1C2  r0 = *(u8*)0x200008B3
0x0801E1C6  cmp r0,#0x0C ; bhs 0x0801E228 (default/no-op)
0x0801E1CA  tbb [pc,r0]                   ; table @0x0801E1CE
```

**INPUT dispatcher** `ui_process_key @0x0801E6EC` (tbb inside at `0x0801E780`):
```
0x0801E6EE  bl 0x08005A14                 ; keypad scan/debounce
0x0801E6F4  if(*(u8*)0x20000B5A==0) return ; keystate (0x20000B57+3) == no-key -> bail
0x0801E6FC  if(*(u8*)0x20000B59==0xFF) return ; keycode (0x20000B57+2) == none -> bail
            ... global lock / special-mode guards ...
0x0801E778  r0 = *(u8*)0x200008B3
0x0801E77C  cmp r0,#0x0C ; bhs 0x0801E804 (default)
0x0801E780  tbb [pc,r0]                   ; table @0x0801E784
   each case: r2=0x20000B57; r1=[r2,#3](keystate); r0=[r2,#2](keycode); bl <handler>
0x0801E806  after dispatch: *(u8*)(0x20000B57+2) = 0xFF  ; consume keycode
```

The **key event struct** is at `0x20000B57`: byte +2 = keycode, byte +3 = keystate/edge (1 = press/repeat). Handlers receive `(r0=keycode, r1=keystate)`.

### 3.3 Screen table — id → {draw handler, input handler}

Verified by decoding both `tbb` tables (bytes are half-word offsets from the table base):

| id | draw handler | input handler | inferred screen | evidence |
|---:|---|---|---|---|
| 0 | `0x08013BD8` | `0x08017F60` | **Home / VFO-A main** (default landing) | most `strb g_screen,#0` "return home" sites; `0x08013BD8` reads big status struct `0x200009C3+0x42` |
| 1 | *(default no-op `0x0801E228` / input `0x0801E804`)* | — | **blank / transient** | table byte 0x2D→no-op; input 0x40→no-op |
| 2 | `0x08013980` | `0x08007B10` | **VFO/standby key screen** | `0x08007B10` handles MENU key (10) → sets g_screen=0xA (menu entry, §3.4); EXIT/side keys |
| 3 | `0x08013A44` | `0x0800FE3C` | **screen w/ icon @`0x0802505C`** (freq-input / dial) | draws bitmap via `0x08008D62`; input checks `0x20000855` |
| 4 | `0x08014978` | `0x0802074C` | **screen w/ icon @`0x08025115`** | bitmap blit; input digit `0xC` handling |
| 5 | `0x08013940` | `0x08007784` | **numeric entry A** (0–F) | input: `cmp r4,#0xF; bl 0x08012EF8` (hex digit) |
| 6 | `0x080139EC` | `0x08007CD0` | **numeric entry B** (0–9) | input: `cmp r4,#9; bl 0x08012F78` (dec digit) |
| 7 | `0x08013804` | `0x08007E68`→`0x08017F60` | **alt of screen 0** | input forwards to id-0 handler `0x08017F60` |
| 8 | `0x08013B6C` | `0x08007D…`/via `0x0801E7E4→0x0800F930` | **list/scroll screen** | draw calls `0x080085D6`; several handlers special-case `g_screen==8` (`0x0800F930`) |
| 9 | `0x08013F7C` | *(input tbl byte 0x33→no-op region `0x0801E7EA`)* | **status/info screen** | draw reads `0x20000A3D+0x39`, `0x20000A7B` |
| **10 (0xA)** | **`0x080142C0`** | **`0x08017294`** | **MENU system** ★ | draw = the menu render loop (facts §Display); input = full menu key handler (largest, `sub sp,#0x64`) |
| 11 (0xB) | `0x08014104` | `0x0801D3B0` | **SMS / editor** (text) | draw blits chars at fixed cols; input handles 0–9 (`cmp r4,#9`) |

Notes:
- **Standby "home" screen (id 0/7)** is the radio's idle/operating screen (frequency, channel, RX/TX, DMR-rx overlay). The full home rendering also runs through the period-gated tasks and `0x0801E3F8` (line-buffer builder) — the dispatched draw handler `0x08013BD8` does the incremental field redraw.
- **id 1** is a genuine no-op slot (both tables route it to the shared "do nothing" tail). Treat as "transition/blank".
- All input handlers share the uniform prototype **`void screen_key(uint8_t keycode, uint8_t keystate)`**.

### 3.4 How transitions happen (state writes)

Screen changes are plain byte stores `strb rN, [=0x200008B3]`. Enumerated immediate-write sites (subset; `movs rN,#imm` immediately before the `strb`):

| new id | example write sites | meaning |
|---:|---|---|
| 0 | `0x08003490, 0x080094AA, 0x0800AA70, 0x0800AE4C, 0x0800B200, 0x0801E120, 0x0801F06C, 0x0801F81E, …` (many) | return to Home / EXIT |
| 1 | `0x080094AE, 0x080095DC, 0x08009760, 0x0801E5DA, 0x0801F698, …` | enter transient/blank |
| 2 | `0x0801A2BE` | enter VFO/standby key screen |
| 3 | `0x0800B112, 0x08018344, 0x0801A2DE` | enter freq-input/dial |
| 4 | `0x0800BC58, 0x0801E15A` | enter screen 4 |
| 5 | `0x08009842` | enter numeric-entry A |
| 7 | `0x0801A66C` | enter alt-home |
| 8 | `0x0800AF0A` | enter list/scroll |
| 9 | `0x080094D2` | enter status/info |
| **10 (0xA)** | **`0x0800B92A`** (from Home MENU key, §below) | **enter MENU** |
| 11 (0xB) | `0x0800B85C` | enter SMS/editor |
| 0x11 | `0x080094A4` | (id 17 — value out of 0..11 range; likely a sub-mode byte, not a screen; used by a specialized editor) |
| 0x2A | `0x08009A9C` | (id 42 — same: sub-mode marker, not a screen dispatch id) |

**Canonical transition example — Home → Menu** (in the id-2 standby key handler `0x08007B10`, MENU key path lands in `0x0800B900`):
```
0x0800B91C  bl 0x0801AD9C            ; menu-open side effects (build top-level list)
0x0800B926  movs r0,#0xA
0x0800B928  ldr r1,=0x200008B3
0x0800B92A  strb r0,[r1]             ; g_screen = 10 (MENU)
```
So **navigation = write the target id to `0x200008B3`** (optionally saving the old value to `0x200008B2` for "back"), plus per-screen enter side-effects. A custom router replicates exactly this.

---

## 4. How a screen is (re)drawn each loop

The draw model is **incremental / dirty-flag driven**, not full-frame:

1. `ui_draw_dispatch @0x0801E1BC` first calls `0x080136E4`, which walks a dirty-flag row at `0x20002512` (loop of 8+) and force-marks fields dirty on screen entry.
2. It then `tbb`-dispatches to the current screen's redraw routine (§3.3). Each routine reads its per-field "changed?" bytes (e.g. `0x200008F5`, `0x20000914`, `0x20000A84`) and only when set calls the text/glyph primitives:
   - `draw_string @0x08008A50` — `void draw_string(u8 y_page /*r0*/, u8 x /*r1*/, const char* s /*r2*/, u8 len /*r3*/, u8 mode /*[sp+0x28]*/)`; mode 0=normal,1=inverse,2=outline. (Confirmed head: `mov sl,r0; mov r7,r1; mov r5,r2; mov fp,r3`.)
   - `0x08008D62` — bitmap/icon blitter (`draw_bitmap(mode,x,y,const u8* bmp)`)
   - `0x080089AC`, `0x080085D6`, `0x08008798` — box/line/clear helpers.
3. The framebuffer is flushed to the LCD over SPI2 by the period-gated tasks; the ASCII glyph blitter `0x08007FB8` and wide/GBK blitter `0x08008454` pull font bitmaps from SPI flash (per facts).

**Consequence for a rewrite:** because draw is gated behind dirty flags and a `tbb` on `g_screen`, replacing the dispatched routine (or the dispatcher call) cleanly takes over rendering for that screen without fighting the stock partial-redraw logic — as long as your code marks the whole area dirty / clears+redraws each frame itself.

---

## 5. Recommended HOOK POINTS for a custom UI router

Goal: our code owns **rendering + navigation + which key does what**, while calling stock lower-level APIs (draw_string `0x08008A50`, keypad `0x08005A14`, RF/DMR/codeplug helpers, and — untouched — the serial/CPS engine). Three options, most-preferred first.

### Option A (recommended): redirect the two scheduler dispatch calls
Patch the two `bl` instructions in `ui_tick_normal`:

| patch site | stock instr | change to |
|---|---|---|
| **`0x080207E6`** | `bl 0x0801E1BC` (ui_draw_dispatch) | `bl my_draw_router` |
| **`0x08020816`** | `bl 0x0801E6EC` (ui_process_key) | `bl my_key_router` |

- Your `my_key_router` reads the same key struct at `0x20000B57` (+2 keycode, +3 keystate) — call stock `0x08005A14` first if you want the stock debounce, or read raw. After handling, write `0xFF` to `0x20000B57+2` to consume, exactly as stock does at `0x0801E806`.
- Your `my_draw_router` renders via `draw_string @0x08008A50` and the blit/clear helpers, keyed on your own screen model. You may keep or ignore `g_screen@0x200008B3`.
- **Everything else in the superloop and scheduler is preserved**, so RF, DMR RX, scan, battery, and the entire serial/CPS + SPI region-write path (`0x080213B8` else-branch, `0x0801F854`, `0x0801FE50`) keep working unchanged. This is the minimal, cleanest cut: **2 instructions**.
- Keep `0x080207EA bl 0x0801E050` (side-key/long-press handler) if you still want stock side-key semantics, or repoint it too for full control.

### Option B: replace the two `tbb` jump tables (per-screen, incremental)
Repoint individual entries in the draw table (`@0x0801E1CE`, 12 bytes) and input table (`@0x0801E784`, 12 bytes) to your own handlers, one screen at a time. Because entries are **1-byte half-word offsets from the table base**, a target must be within `+0..+0x1FE` of the base; to jump far, keep a stock case as a 2-instruction trampoline (`b.w my_handler`) inside range. This lets you migrate screens gradually while stock screens still work. More fiddly than Option A.

### Option C: own the screen id + provide new handlers
Keep the dispatchers, but treat `0x200008B3` as your state var and point all 12 draw/input slots at your dispatch trampolines. Effectively Option B for all 12 at once; no advantage over Option A.

### Lower-level APIs to reuse (stable call targets)
| purpose | vaddr | prototype |
|---|---|---|
| draw text | `0x08008A50` | `draw_string(u8 y_page, u8 x, const char* s, u8 len, u8 mode@sp+0x28)` |
| draw icon/bitmap | `0x08008D62` | `draw_bitmap(u8 mode, u8 x, u8 y, const u8* bmp)` |
| ascii glyph blit | `0x08007FB8` | (per facts; SPI font @0x19C000) |
| wide/GBK glyph blit | `0x08008454` | (per facts; SPI font @0x19E000) |
| keypad scan/debounce | `0x08005A14` | `void keypad_scan(void)` (fills `0x20000B57`) |
| SPI codeplug read | `0x08021828` | `spi_read(dst, byteaddr, len)` — **keep format** |
| menu-open helper | `0x0801AD9C` | builds top-level menu list (call if reusing stock menu data) |
| reboot | `0x0801A38C` | `nvic_system_reset()` |

**Do NOT touch** (serial/CPS + codeplug boundary — hard constraint): the superloop else-branch `0x080213B8..0x0802140A`, `serial_poll 0x0801F854`, the framer/dispatcher `0x0801F84C / 0x08019790 / 0x080188D4`, and the SPI region-write engine. These implement the stock CPS protocol and the on-flash codeplug format; leaving them byte-identical is what keeps the stock Radtel CPS working.

---

## 6. Key RAM state variables (UI)

| addr | width | name | role |
|---|---|---|---|
| `0x200008B3` | u8 | `g_screen` | current UI screen id (0..11) — **the state machine selector** |
| `0x200008B2` | u8 | `g_screen_prev` | previous screen (back/restore) |
| `0x20000B57` | struct | `g_key` | key event: +2 keycode, +3 keystate(1=press) |
| `0x20000C3D` | u8 | `g_sidekey` | side/long-press keycode consumed by `0x0801E050` |
| `0x20000BF1..BF8` | u8/u16 | scheduler down-counters | throttle slow periodic tasks in `ui_tick_normal` |
| `0x20002512` | u8[8+] | dirty-flag row | per-field "needs redraw" flags (cleared by `0x080136E4`) |
| `0x20000C54` | u8 | reboot request | superloop → `nvic_system_reset` |
| `0x20000B66 / 0x20000C12 / 0x20000C57` | u8 | serial-session mode gates | select UI vs CPS/SPI-write path (**do not repurpose**) |

---

## 7. Confidence

- **HIGH** — superloop (`0x0802136C`), normal-UI scheduler (`0x080207DC`), the single screen-state var `0x200008B3`, and the two mirror `tbb` dispatchers (draw `0x0801E1BC`, input `0x0801E6EC`) with their 12-entry tables. All directly disassembled and cross-checked (55 xrefs to the state var; both tbb tables decoded; the Home→Menu transition traced end-to-end).
- **HIGH** — the recommended hook (patch `bl` at `0x080207E6` and `0x08020816`); both call sites verified in the scheduler disassembly, and the serial/CPS boundary is cleanly separated in the superloop.
- **MEDIUM** — the *English names* assigned to screen ids 3/4/5/6/8/9/11: the dispatch structure and handler vaddrs are certain, but exact screen semantics are inferred from handler behaviour (digit ranges, bitmap vs text, forwarding) rather than from a label string on each. ids 0/7 (Home), 2 (standby-key), 10 (Menu), 11 (SMS/editor) are well-anchored.