doc: describe the ARM7 memory-read operating context

The ARM7TDMI memory read (cpu_read/cpu_halt/cpu_resume) works; document
when and how:
- tutorial: rewrite the "CPU targets" section from "structure only" to a
  working cpu_read walkthrough (dump LPC2103 flash to Intel HEX), state
  the operating envelope (power-on -> one halt -> dump; reads clobber
  r0..r14/PC, no context save/restore, so resume isn't clean and a
  re-halt in the same session can time out -> power-cycle), plus a
  troubleshooting row for the sys-speed timeout.
- CLAUDE.md: roadmap phase 7 + ARM-debug note now say the read works
  (flash dump validated), with context save/restore + arm_flash write as
  the remaining steps.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

doc/tutorial.md

@@ -490,16 +490,55 @@ bs_explorer> program 0 design.svf     # prog=svf  -> plays the SVF
 (`bscan_load_bitstream` + `flash_write`/`flash_verify`); `arm_flash`
 routes to the ARM backend.
 
-### CPU targets (ARM7/9) — structure only
+### CPU targets (ARM7/9): reading memory over JTAG
 
 The registry also describes **CPUs** (`kind: cpu`): an ARM debug
 transport (`debug: embeddedice`), work-RAM and an on-chip flash region.
-`target_list` shows them and `program` routes `prog: arm_flash` to the
-ARM backend — but that backend (halt the core over JTAG, load a RAM
-flasher, program internal flash) is **not implemented yet**. An Olimex
-ARM-USB-OCD is an FT2232, so it opens with the existing FTDI driver via
-the `arm-usb-ocd` probe profile. See the ARM-debug design note in
-`CLAUDE.md`.
+An Olimex ARM-USB-OCD is an FT2232, so it opens with the existing FTDI
+driver via the `arm-usb-ocd` probe profile.
+
+For an ARM7TDMI core (EmbeddedICE) three commands work today:
+
+```
+bs_explorer> jtag_open 0 arm-usb-ocd
+bs_explorer> jtag_scan                       # IDCODE, e.g. 0x4F1F0F0F (LPC2103)
+bs_explorer> cpu_read 0 0x0 0x8000 flash.hex hex   # dump 32 KB flash to Intel HEX
+bs_explorer> cpu_halt 0                       # halt only (DBGACK)
+bs_explorer> cpu_resume 0                     # release from debug
+```
+
+`cpu_read <dev> <addr> <len> <file> <bin|hex>` halts the core, reads
+memory by **instruction injection** (halt via EmbeddedICE, switch a
+Thumb-state core to ARM, then a system-speed `LDMIA` reads real memory),
+and writes the bytes as raw binary or Intel HEX. Omit `<file>` for a
+console hex-dump. Validated by dumping an LPC2103's full 32 KB flash and
+round-tripping the `.hex` through `objcopy` (all records/checksums valid,
+correct ARM vector table). Debug-speed core-register read/write also
+works (it is how the address is set up and the loaded words are read
+back).
+
+**Operating context — when it works, and the limits.** Reading is
+reliable in this flow:
+
+- **One halt per power-cycle.** The intended sequence is *power on the
+  board → `jtag_scan` → one `cpu_read` (which halts, reads, leaves the
+  core halted)*. A single `cpu_read` call dumps any length in one halt
+  (it reads in 14-register blocks internally), so dumping all of flash is
+  one command.
+- **Reads clobber r0–r14 and the PC**, and there is **no register
+  context save/restore yet**. So `cpu_resume` cannot cleanly continue the
+  original firmware, and a *second* `cpu_read` (or `cpu_halt`) in the
+  same session re-halts an already-halted, register-clobbered core, which
+  is messy and can time out (`sys-speed access timed out`). If that
+  happens, **power-cycle the board** and run one `cpu_read` again.
+- ARM7TDMI only so far (the EmbeddedICE scan-chain debug). Cortex-M
+  (ADIv5/SWD) is a different transport.
+
+The why-and-how of the cycle-exact JTAG timing this relies on is in the
+ARM-debug design note in `CLAUDE.md`. The next step toward clean resume
+and repeated reads is register **context save/restore**; the `arm_flash`
+*write* backend (program internal flash via a RAM loader) builds on that
+and is not implemented yet.
 
 ## Troubleshooting cheat sheet
 
@@ -515,6 +554,7 @@ the `arm-usb-ocd` probe profile. See the ARM-debug design note in
 | Detected fine, then reads turn to garbage / `0x00000000` mid-session | Target board lost power — JTAG floats (the USB probe stays enumerated regardless). Re-power the board. |
 | FT4232H FlashPro: `jtag_scan` finds 0 devices | JTAG is on channel A (index 0) and needs `ADBUS4` high-Z — open with the profile: `jtag_open 0 flashpro`. |
 | `svf_play` mismatches only on the very first compare | FTDI link warm-up; `svf_play` handles it, but a bare `bscan_shift_dr` straight after `jtag_open` may need a `jtag_scan` first. |
+| `cpu_read`: `sys-speed access timed out` | The core was re-halted in a degraded state (a previous `cpu_read`/`cpu_halt` left it halted with clobbered registers). Power-cycle the board, then run one `cpu_read`. |
 
 ## Where to go from here