Archive the vendor and ISA documents this port was read against

`cpu-docs/` holds the documents behind the reverse-engineering in this repo, and
`cpu-docs/manifests/` records each source URL with a sha256, a byte count and a
page count. The manifests ARE the archive as far as this history is concerned:
121 MB of vendor PDFs are ignored, exactly as `/zig-pkg/` is, because a re-fetch
is one command away and the manifest makes a drifted document detectable.

The small text sources stay tracked instead of ignored, because Espressif
publishes them in no other form - the esptool serial protocol, firmware image
format and boot-mode selection pages, and the P4's custom PIE/SIMD instruction
reference. There is no PDF to re-fetch in their place.

1 files changed, 151 insertions, 0 deletions

diff --git a/cpu-docs/README.md b/cpu-docs/README.md
new file mode 100644
index 0000000..a4a8784
--- /dev/null
+++ b/cpu-docs/README.md
@@ -0,0 +1,151 @@
+# cpu-docs — source documentation for the ESP32-P4's CPU
+
+Primary documents only. Nothing here is written by hand except this index and the per-collector
+manifests in `manifests/`; every other file is a vendor- or standards-body-official artifact,
+fetched from its own site and verified (`file` + `pdfinfo` + first-page title/version check).
+18 PDFs, one official HTML bundle, 7 text sources; 121 MB. The PDFs and the zip are deliberately
+*untracked* (`.gitignore`) — this index and `manifests/` carry every source URL with a sha256, byte
+count and page count, so the archive is re-fetchable and drift is detectable, and 121 MB of
+third-party documents stay out of the repository history. Caveat worth knowing: the two TRMs and
+both datasheets are **pre-release** documents served from *fixed* filenames, so espressif.com will
+one day return different bytes at the same URL. The recorded hashes will detect that; they cannot
+recover the superseded revision. If keeping these exact revisions matters more than a clean
+history, drop the `/cpu-docs/**/*.pdf` rule and raise `jj config set --repo
+snapshot.max-new-file-size 52m`.
+
+## The part
+
+| | |
+|---|---|
+| SoC | Espressif ESP32-P4, silicon revision **v1.3** (pre-v3, ESP-IDF register set `hw_ver1`) |
+| HP CPU | dual-core 32-bit RISC-V, **RV32IMAFC** (+Zc), 360 MHz default on this revision |
+| LP CPU | single-core **RV32IMAC**, no FPU, no vendor extensions |
+| custom ISA | `xespv2p1` (PIE, 128-bit SIMD/DSP) and `xesploop` (hardware loop) |
+| ESP-IDF `-march` for rev < v3 | `rv32imafc_zicsr_zifencei_zaamo_zalrsc_xesploop_xespv2p1 -mabi=ilp32f -mtune=esp-base` |
+| debug module | RISC-V External Debug Support **0.13.2** (HP DM), 0.13 (LP DM) |
+| interrupt controller | RISC-V **CLIC** + CLINT per core, behind the SoC Interrupt Matrix. There is no `INTPRI` on this chip — that is C3/S3-era naming |
+
+## Two traps before you cite anything
+
+**1. Espressif maintains two concurrent ESP32-P4 manual lines, and the generic one is the wrong
+silicon.** `esp32-p4_technical-reference-manual_en_pre-release-v0.7.pdf` documents **v3.x**
+silicon. The register- and feature-correct book for this board is
+`esp32-p4-chip-revision-v1.3_technical-reference-manual_en_pre-release-v0.4.pdf`. Both are archived.
+`esp32-p4-chip-revision-v3.x_user-guide_en_v1.0.pdf` §1 is the authoritative delta list: on v1.3
+the max HP clock is 360 not 400 MHz, there is no Zb, there are fewer than 32 PMP entries, there is
+no user-mode interrupt delegation and no Interrupt-Matrix remapping, CLIC CSR access is slower and
+less compliant, the hardware-loop counter is narrower, and the cached region maps from the **top**
+of L2MEM rather than the bottom.
+
+**2. The PIE chapter exists only in the wrong-revision manual.** The rev-v1.3 TRM lists its
+Processor Instruction Extensions chapter as "[to be added later]" and omits it from the body
+entirely. PIE must therefore be cited from the v0.7 TRM ch.4 (p.210) plus §2.7.1 Hardware Loop
+(p.119) — the only encoding-complete source anywhere. Related: `xesppie` is a dead arch-string
+name; `riscv32-esp-elf-gcc` 15.2.0 rejects it outright.
+
+## Which document answers which question
+
+| question | document | where |
+|---|---|---|
+| memory map, address spaces, cache, flash/PSRAM MMU windows | rev-v1.3 TRM | ch.7 System and Memory p.450 — §7.3.1 Address Mapping, §7.3.3.1 External Memory Address Mapping p.456, §7.3.3.2 Cache p.457. No separate MMU or Cache chapter exists |
+| CSRs the core implements | rev-v1.3 TRM | ch.1 §1.5 CSRs p.63 (summary + per-register description); §1.4 Address Map p.62 |
+| which standard extensions, and their behaviour | rev-v1.3 TRM ch.1 §1.6 p.94–99, then RISC-V Vol I | M ch.12, A ch.13, F ch.20, C ch.27, Zc ch.28, Zicsr ch.6, Zifencei ch.5 |
+| `cycle`/`cycleh` (CSR 0xC00/0xC80), `mcycle` | RISC-V Vol I ch.7.1 Zicntr; Vol II §3.1.10 | the counters `src/soc.zig:cycles()` reads |
+| traps, `mtvec`/`mepc`/`mcause`, PMP, reset, NMI | RISC-V Vol II | §3.1.7, §3.1.14, §3.1.15, §3.7, §3.4, §3.5 |
+| interrupts: CLIC, CLINT, priority/level encoding | rev-v1.3 TRM ch.1 §1.9 p.111 (§1.9.2 CLIC, §1.9.3 CLINT p.118); ch.12 Interrupt Matrix p.755 | architectural model in `riscv-fast-interrupt_clic_draft-v0.10` ch.3 `smclic` |
+| timers | rev-v1.3 TRM | ch.15 System Timer p.1033, ch.16 Timer Group p.1058, ch.17 Watchdog Timers p.1083 (the RTC WDT the bootloader leaves armed) |
+| boot: strapping, boot modes, ROM log routing | rev-v1.3 TRM ch.11 Chip Boot Control p.750; rev-v1.3 datasheet §3 (Tables 3-5/3-6 UART0 vs USB Serial-JTAG); `esptool_boot-mode-selection_*` | |
+| ROM serial loader protocol (SLIP, `ESP_SYNC`, `FLASH_BEGIN/DATA/END`) | `esptool_serial-protocol_v5.3.1.rst` | what `tools/rom.zig` implements |
+| flash image format, header, checksum, SHA-256 | `esptool_firmware-image-format_v5.3.1.rst`; ESP-IDF guide §2.9.1 p.1364, §2.9.2 p.1370 | what `tools/image.zig` implements |
+| startup flow, second-stage bootloader, memory types, interrupt allocation, system time, LP-core, linker scripts, JTAG | ESP-IDF Programming Guide v5.3.2 PDF | p.1803 / p.1806 / p.1933 / p.1648 / p.1748 / p.1760 / p.1914 / p.1873 |
+| PIE / SIMD instruction semantics | v0.7 TRM ch.4 p.210 (encodings) + `esp32p4-pie-simd_instruction-reference_esp-dl_2026-07-15.md` (346 mnemonics, no encodings) | covers all 8 mnemonics used by `examples/pie.zig`; enable via CSR 0x7F2 `CSR_PIE_STATE_REG` |
+| LP core programming model | rev-v1.3 TRM ch.3 Low-Power CPU p.189 (**not** v0.7 ch.5); ESP-IDF guide ULP LP-Core p.1760 | `-march=rv32imac_zicsr_zifencei_zaamo_zalrsc` |
+| silicon bugs, and detecting rev v1.3 at runtime | `esp32-p4_soc-errata_en_v1.3.pdf` | §1.2 + Table 1.1 give the exact `EFUSE_RD_MAC_SPI_SYS_2_REG[23]`/`[5:0]` pattern; ROM-764/770/816 are boot-ROM bugs live on v1.3 |
+| debug port, triggers, JTAG DTM | `riscv-external-debug-support_v0.13.2` (the version P4 implements); 1.0 for the incompatibility list §1.2.1.2–1.2.1.4 | |
+| calling convention, `e_flags`, relocations, `.riscv.attributes` | `riscv-elf-psabi_riscv-abi_draft-20260813.pdf` | §1.1/§1.3, §2.7–2.8 ilp32f, §5 code models, §9.4, §9.11.1 |
+
+## Index
+
+### `espressif-silicon/`
+
+| file | version / date | pp | sha256:16 | source |
+|---|---|---|---|---|
+| `esp32-p4-chip-revision-v1.3_technical-reference-manual_en_pre-release-v0.4.pdf` | Pre-release v0.4, 2026-06-11 | 2975 | `ae1fa2a411776760` | espressif.com |
+| `esp32-p4-chip-revision-v1.3_datasheet_en_v1.2.pdf` | v1.2, 2026-06-16 | 94 | `b2b0ae6fb8e92d23` | espressif.com |
+| `esp32-p4_soc-errata_en_v1.3.pdf` | v1.3, PDF build 2026-08-23 | 19 | `5fd0fec5b306873a` | docs.espressif.com/projects/esp-chip-errata |
+| `esp32-p4-chip-revision-v3.x_user-guide_en_v1.0.pdf` | v1.0, 2026-03-11 | 13 | `9329de55ef88f310` | espressif.com |
+| `esp32-p4_technical-reference-manual_en_pre-release-v0.7.pdf` | Pre-release v0.7, 2026-08-20 | 3701 | `622fe9625d19cf00` | local copy, byte-identical to upstream |
+| `esp32-p4_datasheet_en_pre-release-v0.7.pdf` | Pre-release v0.7, 2026-07-14 | 102 | `fb4f3e91cc2ac519` | local copy, byte-identical to upstream |
+
+### `espressif-software/`
+
+| file | version / date | pp | sha256:16 | source |
+|---|---|---|---|---|
+| `esp-idf-programming-guide_esp32p4_en_v5.3.2.pdf` | v5.3.2, 2024-12-06 | 2262 | `adf06f5531a5c845` | docs.espressif.com |
+| `esp-idf-programming-guide_esp32p4_en_v6.0.2_html.zip` | v6.0.2 (the version `src/soc.zig` cites) | 393 html | `d3f0f339d4a86a04` | docs.espressif.com |
+| `esptool_serial-protocol_v5.3.1.rst` + `_esp32p4_v5.3.1.html` | esptool v5.3.1, 2026-06-29 | — | `016dbe246a0c0edf` / `a00a70719b10fbd3` | github.com/espressif/esptool @ v5.3.1 + rendered page |
+| `esptool_firmware-image-format_v5.3.1.rst` + `.html` | esptool v5.3.1 | — | `1f0cfe32a766b8ab` / `f9b6269b5d9f3601` | same |
+| `esptool_boot-mode-selection_v5.3.1.rst` + `.html` | esptool v5.3.1 | — | `567510a46d727a51` / `100fdf423ba92cc0` | same |
+
+Espressif stopped building ESP-IDF PDFs after v5.3.2; v6.0.2 exists only as the official HTML zip.
+esptool has no PDF or zip artifact at all, hence the rendered HTML plus the version-pinned `.rst`
+sources it is generated from. The `openocd-esp32` docs project is retired — `/en/latest/` 404s for
+every target — so JTAG material comes from the ESP-IDF guide ch.4.13 instead.
+
+### `riscv-isa/`
+
+| file | version / date | pp | sha256:16 |
+|---|---|---|---|
+| `riscv-unprivileged-isa_vol1_ratified_20250508.pdf` | 20250508, **ratified** | 727 | `cef2e63c08c6f82c` |
+| `riscv-privileged-architecture_vol2_ratified_20250508.pdf` | 20250508, **ratified** | 221 | `d0228bbecc76943a` |
+| `riscv-external-debug-support_v0.13.2_20190322.pdf` | 0.13.2, 2019-03-22 — *the version P4 implements* | 94 | `f203abb93ee2ad60` |
+| `riscv-external-debug-support_v1.0_20250221.pdf` | 1.0, ratified 2025-02-21 | 119 | `ce2787b25233a610` |
+| `riscv-elf-psabi_riscv-abi_draft-20260813.pdf` | v1.1 pre-release | 118 | `ff94b93578a5ee44` |
+| `riscv-fast-interrupt_clic_draft-v0.10_20250324.pdf` | v0.10 **draft** — last release carrying `clic.pdf` | 69 | `ddb80f16aecb98ff` |
+| `riscv-fast-interrupt_aclic_draft-v0.20_20260731.pdf` | v0.20 **draft** — CLIC's successor document | 38 | `1892f06fd863fe73` |
+| `riscv-assembly-programmers-manual_v0.0.1_20250205.pdf` | v0.0.1 | 50 | `2edf43ff39c0ca47` |
+| `riscv-code-size-reduction_zc_v1.0.4-3_20231026.pdf` | v1.0.4-3 | 60 | `62cea3875763904b` |
+| `riscv-plic_v1.0.0_20230312.pdf` | 1.0.0 ratified — low relevance, contrast only | 18 | `82644c7701601baa` |
+| `riscv-aclint_v1.0-rc4_20220114.pdf` | 1.0-rc4 draft — low relevance, P4 uses systimer/TIMG | 11 | `fb7f1473470fbc2a` |
+
+20250508 is the newest *ratified* ISA manual; every later tag is an unratified nightly build of the
+merged in-development spec. The fast-interrupt task group has never ratified anything, so both
+CLIC and ACLIC are drafts. The 0.13.2 debug PDF came from riscv.org and was `cmp`-verified
+byte-identical to `riscv/riscv-debug-spec@4e0bb0fc:riscv-debug-release.pdf`.
+
+### `espressif-custom-isa/`
+
+| file | version / date | sha256:16 | source |
+|---|---|---|---|
+| `esp32p4-pie-simd_instruction-reference_esp-dl_2026-07-15.md` | `espressif/esp-dl` master @ `1def9a2d`, 2026-07-15 | `76576a92f85fb46a` | github.com/espressif/esp-dl |
+
+No standalone PIE PDF exists; this is the only vendor reference document for the extension outside
+the TRM. It condenses for machine consumption: 346 mnemonics against the assembler's 410, no
+instruction encodings, and it drops the `sat` operand the TRM's syntax carries. Encodings come from
+the v0.7 TRM ch.4 figures or from Espressif's `as` with `-march=…xespv2p1`.
+
+## Not obtained
+
+Summarised; each collector's manifest carries the evidence and the best pointer.
+
+* No ESP32-P4 boot-ROM prose document exists anywhere. The authoritative artifacts are the ROM ELF
+  and the ROM linker scripts (paths in `manifests/LocalHarvest.md`); code was deliberately not
+  copied into this archive.
+* No standalone LP-core ISA document. Its arch string was verified from
+  `components/ulp/cmake/toolchain-lp-core-riscv.cmake`.
+* No ESP-IDF v6.x PDF, no esptool PDF, no OpenOCD docs project — see `espressif-software/` above.
+* ESP32-P4 Consolidated Pin Overview is `.xlsx` only, and is pin-mux material, so out of scope.
+* Hardware design guidelines, packaging, RF certification, and all board-level documents
+  (JC-ESP32P4-M3 dev-kit PDFs, schematics, the ESP32-C6-MINI-1 companion-module datasheet) are out
+  of scope; they remain at `../../01-esp32p4-m3/docs/` and are listed in `manifests/LocalHarvest.md`.
+
+## Provenance
+
+`manifests/` holds one file per collector — `EspSilicon`, `EspSoftware`, `RiscvSpecs`,
+`EspCustomIsa`, `LocalHarvest` — each with full URLs, byte counts, page counts, sha256 prefixes,
+verified chapter/page numbers, and what it failed to find and why. Re-verify the archive with:
+
+```
+find . -name '*.pdf' -exec sh -c 'pdfinfo "$1" >/dev/null || echo "BAD $1"' _ {} \;
+sha256sum $(find . -type f ! -path './manifests/*' | sort) | cut -c1-16
+```