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.

5 files changed, 224 insertions, 0 deletions

diff --git a/cpu-docs/manifests/EspCustomIsa.md b/cpu-docs/manifests/EspCustomIsa.md
new file mode 100644
index 0000000..8a5fd4c
--- /dev/null
+++ b/cpu-docs/manifests/EspCustomIsa.md
@@ -0,0 +1,86 @@
+# EspCustomIsa — Espressif-specific ESP32-P4 CPU ISA: PIE/HWLP vendor extensions, LP core, cache/MMU, custom CSRs, toolchain
+
+## Key facts established for this project
+
+**Exact `-march` for ESP32-P4 silicon rev < v3 (this project's v1.3 part), read out of ESP-IDF v6.0.2
+`components/soc/project_include.cmake:19-83`:**
+
+```
+-march=rv32imafc_zicsr_zifencei_zaamo_zalrsc_xesploop_xespv2p1  -mabi=ilp32f  -mtune=esp-base
+```
+
+Composition, line by line: base `rv32imafc_zicsr_zifencei_zaamo_zalrsc` (L20); `_zcb_zcmp_zcmt`
+**suppressed** because `CONFIG_ESP32P4_SELECTS_REV_LESS_V3` (L47); `_xesploop` from
+`SOC_CPU_HAS_HWLOOP` (L59-61); `_xespv` + `2p1` — the `2p1` pinned *because* rev < v3 (L63-68);
+`_xespdsp` only if `SOC_CPU_HAS_DSP`, which ESP32-P4 does **not** define (L70-72). GCC normalises this
+to the ELF attribute string found verbatim in IDF's prebuilt P4 libraries
+(`components/openthread/lib/esp32p4/libopenthread_br.a`):
+`rv32i2p1_m2p0_a2p1_f2p2_c2p0_zicsr2p0_zifencei2p0_zmmul1p0_zaamo1p0_zalrsc1p0_zca1p0_zcf1p0_xesploop1p0_xespv2p1`.
+
+`xesppie` — the name in the task brief — is the **historical** spelling. `riscv32-esp-elf-gcc 15.2.0`
+rejects it outright (`extension 'xesppie' starts with 'x' but is unsupported non-standard extension`);
+the accepted names are `xespv2p1`, `xespv2p2`, `xesploop`/`xesploop1p0`, `xespdsp`. The old name
+survives only in ESP-IDF's gdbstub (`components/esp_gdbstub/src/port/riscv/target_xml.c:88`,
+`"org.gnu.gdb.riscv.xesppie"`) and in `components/esp_gdbstub/test_gdbstub_host/rv_decode/xesppie.S`
+(header comment still says `-march=rv32ixesppie`).
+
+**PIE mnemonics used by `examples/pie.zig`** (all eight verified present in both documents cited below):
+`esp.vld.128.ip`, `esp.vst.128.ip`, `esp.zero.qacc`, `esp.vmulas.s8.qacc`,
+`esp.st.qacc.l.l.128.ip`, `esp.st.qacc.l.h.128.ip`, `esp.st.qacc.h.l.128.ip`, `esp.st.qacc.h.h.128.ip`.
+Enable CSR is `0x7F2` (`CSR_PIE_STATE_REG`, `components/riscv/include/riscv/csr_pie.h:19`).
+
+**GCC exposes no PIE intrinsics.** `strings` over `cc1` and `cc1plus` in
+`/home/goblin/.espressif/tools/riscv32-esp-elf/esp-15.2.0_20251204/riscv32-esp-elf/libexec/gcc/riscv32-esp-elf/15.2.0/`
+yields zero `__builtin_riscv_esp*` / `esppie` symbols — only the `-march` tokens `xespv`, `xesploop`,
+`xespdsp`. The extension is assembler-only: 410 distinct `esp.*` mnemonics live in the opcode table of
+the dedicated assembler `riscv32-esp-elf/riscv32-esp-elf/bin/as-xespv2p1` (sibling `as-xespv2p2`,
+`objdump-xespv2p1`, `objdump-xespv2p2`). This independently confirms `examples/pie.zig`'s premise that
+hand-written `.insn` words are the only route, under Espressif's own GCC as much as under stock Zig.
+
+## Obtained
+
+| file | title | version / date | source URL | bytes | pages | sha256 (first 16) | relevance |
+|---|---|---|---|---|---|---|---|
+| espressif-custom-isa/esp32p4-pie-simd_instruction-reference_esp-dl_2026-07-15.md | ESP32-P4 SIMD Instruction Reference | esp-dl master @ 1def9a2dff008fe1ae96c249490683147fce26bc, 2026-07-15 | https://raw.githubusercontent.com/espressif/esp-dl/master/tools/agents/skills/esp32p4-pie-simd/references/instructions.md | 47644 | 907 lines / 346 instruction rows | 76576a92f85fb46a | The only standalone vendor PIE reference: "Register Architecture" (q0–q7, QACC_H/QACC_L 256-bit each, SAR, SAR_BYTE, rounding-mode `rm_exc`), then Read / Write / Data Exchange / Arithmetic / Comparison / Bitwise Logical / Shift / FFT Dedicated instruction tables — covers all 8 mnemonics this project emits (L141 VLD.128.IP, L222 VST.128.IP, L240-243 ST.QACC.{H,L}.{H,L}.128.IP, L339 ZERO.QACC, L490 VMULAS.S8.QACC) |
+
+**Non-PDF fallback, declared explicitly as the rules require.** No PDF of the PIE instruction set
+exists as a standalone Espressif document — the only PDF carrying it is the ESP32-P4 TRM, which is
+`espressif-silicon/`'s lane (see "Belongs elsewhere"). This `.md` is the official `.md` spec source
+fallback: vendor-authored, in `github.com/espressif/esp-dl`, no mirror involved.
+
+**Fidelity check against the TRM, so the reader can trust it.** I diffed entries against
+`espressif-silicon/esp32p4_technical-reference-manual_en_pre-release-v0.7.pdf` ch.4. The `.md`'s
+`ESP.VMULAS.S8.QACC` line — "16 × S8 mul, accumulate 32-bit to QACC_H/L (saturated to 32-bit signed)" —
+reproduces TRM §4.7.2.23's description exactly. Caveat worth knowing: the `.md` is a *condensation*
+written for agent consumption, so it drops operands and bit-level Operation pseudocode. It gives
+`ESP.VMULAS.S8.QACC qx, qy` where TRM §4.7.2.23 syntax is `ESP.VMULAS.S8.QACC qx,qy,sat`, and it
+carries **no instruction encodings at all**. It documents 346 mnemonics against the assembler's 410.
+For encodings (which is what `.insn` needs) the TRM figures, or `as-xespv2p1` as an oracle the way
+`tools/encode.sh` already uses it, remain the only sources.
+
+## Not obtained
+
+| wanted | why not | best known pointer |
+|---|---|---|
+| PIE instruction-set spec with **encodings** (item 1) | Exists, but only as ESP32-P4 TRM ch.4 — a PDF owned by `espressif-silicon/`. Not refetched per lane rule. | `cpu-docs/espressif-silicon/esp32p4_technical-reference-manual_en_pre-release-v0.7.pdf` ch.4 "Processor Instruction Extensions (PIE)" p.210 (§4.7.2.x per-instruction: syntax + Description + Operation + encoding figure; §4.7.2.23 = ESP.VMULAS.S8.QACC), plus §2.7.2 "Processor Instruction Extension" p.127. Upstream: https://www.espressif.com/sites/default/files/documentation/esp32-p4_technical_reference_manual_en.pdf . Local pre-existing copy: `/home/goblin/00-projects/0x4200.cafe/01-esp32p4-m3/docs/esp32-p4_technical_reference_manual_en.pdf`. **Warning: the rev-matched v1.3 TRM omits this chapter entirely** (confirmed by EspSilicon: its "Release Status at a Glance" lists ch.3 Processor Instruction Extensions as "[to be added later]" and in-document numbering skips it), so for PIE the generic v0.7 manual must be used even though the part is v1.3 silicon. |
+| HWLP / hardware-loop (`xesploop1p0`) spec | No standalone document anywhere; TRM only. | TRM v0.7 §2.7.1 "Hardware Loop" p.119 (2.7.1.1 Overview, .2 Features, .3 Functional Description, .4 Instructions/Operations/Modes Supported in HWLP, .5 HWLP Constraints, .6-.7 Register Summary/Description) and §2.7.1.8 "HWLP Instructions" p.126. CSRs: `esp-idf/components/riscv/include/riscv/csr_hwlp.h` — `CSR_HWLP_STATE_REG 0x7F1` (states OFF/INITIAL/CLEAN/DIRTY), `CSR_LOOP0_START_ADDR 0x7C6`, `CSR_LOOP0_END_ADDR 0x7C7`, `CSR_LOOP0_COUNT 0x7C8`, `CSR_LOOP1_*` 0x7C9-0x7CB. Local: `/home/goblin/esp/esp-idf/components/riscv/include/riscv/csr_hwlp.h`. Upstream: https://github.com/espressif/esp-idf/blob/master/components/riscv/include/riscv/csr_hwlp.h . Errata to respect: `SOC_CPU_HAS_HWLOOP_STATE_BUG` — "HWLOOP state doesn't go to DIRTY after executing the last instruction of a loop" (`components/soc/esp32p4/include/soc/soc_caps.h:198`). |
+| LP core (low-power RISC-V) ISA + programming model, standalone (item 2) | No standalone Espressif document exists; the material is split between the TRM's LP CPU chapter and the ESP-IDF guide, both other agents' lanes. | **ISA string (verified, and it is *not* the HP string):** `-march=rv32imac_zicsr_zifencei_zaamo_zalrsc`, no FPU, no vendor extensions — `esp-idf/components/ulp/cmake/toolchain-lp-core-riscv.cmake:8,10,12,14` (C/CXX/ASM/LINK all four). Local: `/home/goblin/esp/esp-idf/components/ulp/cmake/toolchain-lp-core-riscv.cmake`; upstream https://github.com/espressif/esp-idf/blob/master/components/ulp/cmake/toolchain-lp-core-riscv.cmake . **Interrupt/wakeup model:** `components/ulp/lp_core/lp_core/include/ulp_lp_core_interrupts.h` (`ulp_lp_core_intr_enable`/`_disable`, per-source ISR weak symbols) and `ulp_lp_core_utils.h`; driver side `components/ulp/lp_core/lp_core.c`. **Caps:** `components/soc/esp32p4/include/soc/soc_caps.h:57-58` (`SOC_ULP_SUPPORTED`, `SOC_LP_CORE_SUPPORTED`), `:769-771` (`SOC_LP_CORE_SUPPORT_ETM`, `_LP_ADC`, `_STORE_LOAD_EXCEPTIONS`). **Prose spec:** rev-matched `espressif-silicon/esp32-p4-chip-revision-v1.3_technical_reference_manual_en.pdf` ch.3 "Low-Power CPU" p.189 (use this one, not generic v0.7 where LP CPU is ch.5 p.633). |
+| Cache + MMU document, PDF (item 3) | Espressif publishes no separate cache/MMU document; TRM chapters plus ROM headers are authoritative. | **Prose:** rev-matched v1.3 TRM ch.7 "System and Memory" p.450 — §7.3.1 Address Mapping p.451, §7.3.3.1 External Memory Address Mapping p.456, §7.3.3.2 Cache p.457, §7.3.3.3 Cache Operations p.458 (generic v0.7 equivalent: ch.9 p.901, §9.3.3.2 Cache p.909). **ROM `Cache_*` API:** `esp-idf/components/esp_rom/esp32p4/include/esp32p4/rom/cache.h` — 1611 lines, **117** distinct `Cache_*` entry points covering the L1-per-core-ICache / L1-DCache / L2-Cache hierarchy this part actually has (`Cache_Enable_L1_CORE0_ICache`, `Cache_Enable_L1_CORE1_ICache`, `Cache_Enable_L1_DCache`, `Cache_Enable_L2_Cache`, `Cache_Clean_Addr`/`_All`/`_Gid`, `Cache_*_Autoload`, `Cache_*_PreLock`). Note the path in the brief is stale for v6.0.2: `components/esp_rom/include/esp32p4/rom/cache.h` does **not** exist; the header moved under `components/esp_rom/esp32p4/`. Local: `/home/goblin/esp/esp-idf/components/esp_rom/esp32p4/include/esp32p4/rom/cache.h`; upstream https://github.com/espressif/esp-idf/blob/master/components/esp_rom/esp32p4/include/esp32p4/rom/cache.h . **The 64 KiB flash-MMU page rule this project exploits:** hard-wired, not configurable — `components/hal/esp32p4/include/hal/mmu_ll.h:129` returns `MMU_PAGE_64KB` unconditionally and `:140` asserts `size == MMU_PAGE_64KB`. Image-side consumer: `components/bootloader_support/src/esp_image_format.c:690` (`__builtin_mul_overflow(max_pages, SPI_FLASH_MMU_PAGE_SIZE, &max_image_len)`) and `:865-885` (`SOC_MMU_PAGE_SIZE_CONFIGURABLE`, page-size-mismatch path). |
+| Espressif CSR / interrupt-controller doc beyond the TRM (item 4) | No such document is published; ESP-IDF headers are the only machine-checkable source, and they settle the questions asked. | **`INTPRI` does not exist on the ESP32-P4** — verified negative: zero hits for `INTPRI` under `components/soc/esp32p4/`, whereas ESP32-C6 has `register/soc/intpri_reg.h` + `intpri_struct.h`. The P4 uses a CLIC instead. **Non-standard CLIC on rev < v3, i.e. this part** — `components/soc/esp32p4/include/soc/interrupt_reg.h:30-44`, guarded by `CONFIG_ESP32P4_SELECTS_REV_LESS_V3`, comment verbatim: "The ESP32-P4 implements a non-standard version of the CLIC: - The interrupt threshold is configured via a memory-mapped register instead of a CSR - The mintstatus CSR is at 0x346 instead of 0xFB1 as per the official specification" → `INTTHRESH_STANDARD 0`, `MINTSTATUS_CSR 0x346`. Standard-CLIC values for rev ≥ v3 in `components/riscv/include/riscv/csr_clic.h:39-43` (`MINTSTATUS 0xFB1`, `MINTTHRESH 0x347`, `UINTSTATUS 0xCB1`, `UINTTHRESH 0x047`); `MTVT_CSR 0x307` (:34), `RV_EXTERNAL_INT_COUNT 32` / `RV_EXTERNAL_INT_OFFSET 16` (:28-29). **mtvec is vectored, mode = 3:** `MTVEC_MODE_CSR 3` (csr_clic.h:22) is OR-ed into every write by `rv_utils_set_mtvec` (`components/riscv/include/riscv/rv_utils.h:168-177`, "Set MODE field to treat XTVEC as a vector base address"). CLIC register layout: `components/soc/esp32p4/include/soc/clic_reg.h` (`CLIC_INT_CONFIG_REG`, `NMBITS`, `MNLBITS`, `NVBITS`, `CLIC_EXT_INTR_NUM_OFFSET 16`). **`mpcer`/`mpcmr` are NOT on the P4** — verified negative: `SOC_CPU_HAS_CSR_PC` is defined only for esp32c2/c3/c6/h2/h21 `soc_caps.h`, never esp32p4, so the `CSR_PCER_MACHINE 0x7e0` / `CSR_PCMR_MACHINE 0x7e1` counters gated at `rv_utils.h:44-50` are absent and the P4 falls to standard `mcycle`/`minstret` (`rv_utils.h:122,135`). Other vendor CSRs present: `csr_pie.h` `0x7F2`; `csr_hwlp.h` `0x7F1`,`0x7C6`-`0x7CB`; `csr_dsp.h` `CSR_DSP_STATE_REG 0x7f3`, `XACC_L 0x806`, `XACC_H 0x807`, `SAR 0x809`, `STATUS 0x80a`. |
+| riscv32-esp-elf toolchain doc covering the custom `-march` and its ABI implications (item 5) | Espressif publishes no toolchain reference manual, in PDF or otherwise; the `-march` string is documented only by the ESP-IDF build code above. GitHub release notes are the authoritative changelog but never state the vendor `-march` syntax. | Release index: https://github.com/espressif/crosstool-NG/releases . Installed build `esp-15.2.0_20251204` (published 2025-12-05) — its notes are PIE-relevant but shallow: "Added esp.vsl.32 instruction support for backward compatibility". Latest is `esp-16.1.0_20260609` (published 2026-06-10), which removes the `rv32imafc_zicsr_zifencei_zaamo_zalrsc_zcb_zcmp_zcmt` multilib — irrelevant here since rev < v3 already suppresses `_zcb_zcmp_zcmt`. ABI is stated only as the flags in `components/soc/project_include.cmake:75-83`: `-mabi=ilp32f` when `SOC_CPU_HAS_FPU`, `-mtune=esp-base`. Multilib layout on disk (no `xesp*` variant exists — vendor extensions add no multilib, hence no ABI split): `/home/goblin/.espressif/tools/riscv32-esp-elf/esp-15.2.0_20251204/riscv32-esp-elf/riscv32-esp-elf/lib/`. Tooling doc page that exists but does not cover `-march`: https://docs.espressif.com/projects/esp-idf/en/stable/esp32p4/api-guides/tools/idf-tools.html |
+| LLVM-side PIE definitions (`RISCVInstrInfoESP32P4.td`, intrinsics headers) | Checked and not usable as a document: `espressif/llvm-project` (branch `xtensa_release_19.1.2`) ships the stock upstream `llvm/docs/RISCVUsage.rst` with no `Xesppie`/`Xespv` section, and any `.td` file is code, which this task forbids copying. Consistent with `examples/pie.zig`'s claim that Espressif's own LLVM cannot assemble these mnemonics. | https://github.com/espressif/llvm-project — searched `llvm/docs/RISCVUsage.rst` (fetched, 26699 bytes, no vendor-extension entry). |
+| An esp-dsp guide PDF documenting PIE | Provably absent: `https://docs.espressif.com/projects/esp-dsp/en/latest/` serves HTTP 200 with **zero** `.pdf` hrefs, and all four plausible docs.espressif.com PDF paths return 404 (`esp-dsp-en-master.pdf`, `esp-dsp-en-master-esp32.pdf`, `esp32/esp-dsp-en-master-esp32.pdf`, `esp32p4/esp-dsp-en-master-esp32p4.pdf`). esp-dsp has no PDF build. | https://docs.espressif.com/projects/esp-dsp/en/latest/ (HTML only) |
+
+### Searches run for a standalone PIE instruction-set document
+
+Recorded so the negative result is auditable. (1) `espressif.com/en/support/documents/technical-documents` full PDF index scraped (824888 bytes, ~40 `.pdf` hrefs enumerated): the only ESP32-P4 entries are datasheet, TRM, `esp32-p4-chip-revision-v1.3_{datasheet,technical_reference_manual}`, and `esp32-p4-chip-revision-v3.x_user_guide` — **no** PIE/ISA/instruction-set document. (2) `docs.espressif.com/projects/esp-dsp` — no PDF build (four 404s above). (3) Web search for the literal mnemonics `ESP.VMULAS` / `ESP.VLD.128.IP` — surfaced only the esp-dl reference I fetched, an Espressif developer-portal blog post, third-party blogs, and datasheet-mirror copies of the *ESP32-S3* TRM; all rejected except the esp-dl reference. (4) GitHub `espressif/esp-dl/tools/agents/skills/` enumerated via API: `esp32p4-pie-simd/{SKILL.md, references/{instructions.md, examples.md}}` — `instructions.md` taken; `SKILL.md` is agent prose and `examples.md` is example code, both out of scope for a source archive. (5) `espressif/llvm-project` docs (above). (6) Installed toolchain swept for any bundled manual: zero `.pdf`, `.info`, `.1`, or `.html` files under `riscv32-esp-elf/`, only two unrelated GCC `include-fixed` READMEs. **Conclusion: no standalone PIE instruction-set document is published; TRM ch.4 is the sole encoding-complete spec, and the esp-dl `.md` is the sole standalone reference.**
+
+Non-vendor and blog sources deliberately rejected: `developer.espressif.com/blog/2024/12/pie-introduction/` (Espressif-official but a blog post, excluded per the brief's "blog-free official doc"), `bitbanksoftware.blogspot.com`, `esp32.com` forum, `skillsmp.com`, and the `waveshare`/`hackaday` mirrors of the ESP32-S3 TRM (mirror + wrong chip).
+
+## Belongs elsewhere
+
+- **ESP32-P4 TRM (generic, Pre-release v0.7) ch.4 "Processor Instruction Extensions (PIE)" p.210, §2.7.1 Hardware Loop p.119, §2.7.1.8 HWLP Instructions p.126, §2.7.2 Processor Instruction Extension p.127** — the encoding-complete PIE/HWLP spec, and the single most important document for `examples/pie.zig`. Fetched by `espressif-silicon/` as `esp32p4_technical-reference-manual_en_pre-release-v0.7.pdf`; not duplicated here.
+- **ESP32-P4 chip-revision-v1.3 TRM (Pre-release v0.4) ch.3 "Low-Power CPU" p.189 and ch.7 "System and Memory" p.450** — rev-correct LP-core and cache/MMU chapters for this project's silicon. `espressif-silicon/`.
+- **ESP32-P4 Chip Revision v3.x User Guide** (`https://www.espressif.com/sites/default/files/documentation/esp32-p4-chip-revision-v3.x_user_guide_en.pdf`) — spotted in the espressif.com index while searching; likely documents the rev-v3 ISA/CLIC deltas that `CONFIG_ESP32P4_SELECTS_REV_LESS_V3` and the `xespv2p1`→`xespv2p2` bump straddle. Chip-level revision doc → `espressif-silicon/`.
+- **ESP-IDF Programming Guide (ESP32-P4) "ULP LP-Core Coprocessor Programming"** — https://docs.espressif.com/projects/esp-idf/en/stable/esp32p4/api-reference/system/ulp-lp-core.html , part of the ESP-IDF PDF → `espressif-software/`.
+- **ESP-IDF Programming Guide "Speed Optimization"** — https://docs.espressif.com/projects/esp-idf/en/stable/esp32p4/api-guides/performance/speed.html , the only guide page discussing PIE-related build flags; inside the ESP-IDF PDF → `espressif-software/`.
diff --git a/cpu-docs/manifests/EspSilicon.md b/cpu-docs/manifests/EspSilicon.md
new file mode 100644
index 0000000..c3a5544
--- /dev/null
+++ b/cpu-docs/manifests/EspSilicon.md
@@ -0,0 +1,28 @@
+# EspSilicon — ESP32-P4 chip-level primary documentation from Espressif (silicon rev v1.3 / pre-v3 focus)
+
+## Obtained
+
+| file | title | version / date | source URL | bytes | pages | sha256 (first 16) | relevance |
+|---|---|---|---|---|---|---|---|
+| espressif-silicon/esp32-p4-chip-revision-v1.3_technical-reference-manual_en_pre-release-v0.4.pdf | ESP32-P4 Chip Revision v1.3 Technical Reference Manual | Pre-release v0.4, 2026-06-11 | https://www.espressif.com/sites/default/files/documentation/esp32-p4-chip-revision-v1.3_technical_reference_manual_en.pdf | 20786220 | 2975 | ae1fa2a411776760 | **Rev-matched pre-v3 TRM (EOL-watermarked).** ch.1 High-Performance CPU p.60 (§1.4 Address Map p.62, §1.5 CSRs p.63 w/ register summary+description, §1.6 RISC-V standard extensions M/C/F/Zc/A p.94-99, §1.9 Interrupt Controller p.111 → §1.9.2 CLIC p.111 / §1.9.2.2 CLIC CSRs / §1.9.2.3 Interrupt Mapping / §1.9.2.5 Interrupt Level and Priority Encoding / §1.9.2.6-7 CLIC memory-mapped regs p.113-115, §1.9.3 CLINT p.118); ch.2 RISC-V Trace Encoder p.159; ch.3 Low-Power CPU p.189; ch.7 System and Memory p.450 (§7.3.1 Address Mapping p.451, §7.3.2 Internal Memory p.454, §7.3.3.1 External Memory Address Mapping p.456 = flash/PSRAM windows 0x4000_0000-0x43FF_FFFF & 0x4800_0000-0x4BFF_FFFF cacheable + 0x8000_0000/0x8800_0000 direct, mapped via MMU, §7.3.3.2 Cache p.457, §7.3.3.3 Cache Operations p.458, §7.3.4 DMA Address Space p.459, §7.3.5 Modules/Peripherals Address Mapping p.460); ch.8 eFuse Controller p.464; ch.10 Reset and Clock p.612; ch.11 Chip Boot Control p.750 (boot-mode control; no separate boot-ROM chapter); ch.12 Interrupt Matrix p.755 (per-core HP CPU0/CPU1 register sets §12.5-12.6); ch.14 Low-Power Management p.952; ch.15 System Timer p.1033; ch.16 Timer Group (TIMG) p.1058; ch.17 Watchdog Timers (WDT) p.1083; ch.18 RTC Timer p.1098; ch.19 Permission Control (PMS) p.1112; ch.20 System Registers (SYSREG) p.1209; ch.21 Debug Assistant p.1301; ch.22 LP Mailbox p.1361 |
+| espressif-silicon/esp32-p4-chip-revision-v1.3_datasheet_en_v1.2.pdf | ESP32-P4 Chip Revision v1.3 Datasheet | v1.2, 2026-06-16 | https://www.espressif.com/sites/default/files/documentation/esp32-p4-chip-revision-v1.3_datasheet_en.pdf | 1603774 | 94 | b2b0ae6fb8e92d23 | Rev-v1.3 spec baseline: HP = 32-bit RISC-V dual-core **RV32IMAFC** (states "supports standard RV32IMAFCZc extensions") up to **360 MHz default** (400 MHz only on request), LP core **RV32IMAC**; on-chip memory 128 KB HP ROM + 16 KB LP ROM + 768 KB HP L2MEM + 8 KB SPM @360 MHz; in-package 16 or 32 MB PSRAM (Table 5-9 PSRAM Specifications); §3 ROM message printing control (Tables 3-5 UART0 / 3-6 USB Serial-JTAG) for boot-log routing; §1 series comparison + revision history (whole doc is the v1.3/EOL line: ESP32-P4NRW16/32 → EOL) |
+| espressif-silicon/esp32-p4_soc-errata_en_v1.3.pdf | ESP32-P4 Series SoC Errata | v1.3 (index release 2026-07-10; PDF build 2026-08-23) | https://docs.espressif.com/projects/esp-chip-errata/en/latest/esp32p4/esp-chip-errata-en-master-esp32p4.pdf | 144853 | 19 | 5fd0fec5b306873a | 13 errata. §1.1 vM.X revision scheme; §1.2 runtime chip-rev detection via **EFUSE_RD_MAC_SPI_SYS_2_REG[23] + [5:0]** (Table 1.1 gives the exact bit pattern for v1.3 vs v0.0/v1.0/v3.0/v3.1/v3.2); §1.4 ESP-IDF release compatibility; §2 Errata Summary p.3; §3.3-3.5 MSPI-749 load-access-fault on power-on/deep-sleep wake, MSPI-750 PSRAM unaligned DMA stale data, MSPI-751 address-overlap timing; §3.6/3.7/3.8 ROM-764 secure-boot bad buffer addr, ROM-770 secure-download flash power-on failure, ROM-816 hang on double flash power-on — all boot-ROM issues live on v1.3 silicon; §3.10 DMA-767, §3.11 APM-560 |
+| espressif-silicon/esp32-p4-chip-revision-v3.x_user-guide_en_v1.0.pdf | ESP32-P4 Chip Revision v3.x User Guide | v1.0, 2026-03-11 | https://www.espressif.com/sites/default/files/documentation/esp32-p4-chip-revision-v3.x_user_guide_en.pdf | 476336 | 13 | 9329de55ef88f310 | Chip-revision/compatibility doc; §1 "Design Changes in Chip Revision v3.x" is the definitive list of what v1.3 silicon **lacks**: HP CPU max 360 (not 400) MHz, **no Zb extension**, PMP entries fewer than 32, no user-mode interrupt delegation and no Interrupt-Matrix remapping, unfixed EXT_ILL_CSR bit-0 FPU behaviour, slower/less-compliant CLIC CSR access, different HW-loop counter width (v3.x = 24-bit), and cached region mapping starting from the **top** of L2MEM (v3.x moved it to the bottom) — plus §1 lists the v1.3 bugs fixed later (MSPI-749/750/751, ROM-764/770, Analog-765, DMA-767, APM-560); §2 upgrade impact, §4 ordering info |
+| espressif-silicon/esp32-p4_technical-reference-manual_en_pre-release-v0.7.pdf | ESP32-P4 Technical Reference Manual | Pre-release v0.7, 2026-08-20 | https://www.espressif.com/sites/default/files/documentation/esp32-p4_technical_reference_manual_en.pdf | 23537234 | 3701 | 622fe9625d19cf00 | Placed by LocalHarvest; I verified it byte-identical (full sha256 match) to current upstream, so not re-downloaded. This is the **v3.x-line** manual, kept because the rev-v1.3 TRM omits the ISA-extension chapter: ch.4 **Processor Instruction Extensions (PIE)** p.210 plus §2.7.1 Hardware Loop p.119 / §2.7.1.2 HWLP Instructions p.126 / §2.7.2 Processor Instruction Extension p.127 exist ONLY here. Other verified in-document chapters (numbering differs from both the v1.3 TRM and this manual's own "Release Status" list, which counts a non-existent eFuse chapter): ch.1 Bus Architecture p.65 (absent from v1.3 TRM), ch.2 HP CPU p.68 (§2.9 Interrupt Controller p.130, §2.9.2 CLIC p.130, §2.9.2.2 CLIC CSRs p.130), ch.5 LP CPU p.633, ch.9 System and Memory p.901 (§9.3.1 Address Mapping p.902, §9.3.2 Internal Memory p.905, §9.3.3.1 External Memory Address Mapping p.909, §9.3.3.2 Cache p.909, §9.3.3.3 Cache Operations p.910, §9.4 eFuse Controller p.916 — eFuse is a *section* here, not a chapter), ch.11 Reset and Clock p.1081, ch.12 Chip Boot Control p.1219, ch.13 Interrupt Matrix p.1224, ch.15 Low-Power Management p.1425, ch.16 System Timer p.1507, ch.17 TIMG p.1532, ch.18 WDT p.1557, ch.19 RTC Timer p.1572, ch.21 SYSREG p.1687, ch.23 AXI Performance Monitor p.1853; register details must be cross-checked against the v1.3 TRM before use on this silicon |
+| espressif-silicon/esp32-p4_datasheet_en_pre-release-v0.7.pdf | ESP32-P4 Series Datasheet | Pre-release v0.7, 2026-07-14 | https://www.espressif.com/sites/default/files/documentation/esp32-p4_datasheet_en.pdf | 1576185 | 102 | fb4f3e91cc2ac519 | Placed by LocalHarvest; verified byte-identical to current upstream, not re-downloaded. **v3.x-line only** — its §1.3 "Chip Revision" covers v3.x and explicitly defers rev-identification/older revisions to the SoC Errata and the v3.x User Guide, so it does **not** carry a v1.3 row; quotes 400 MHz RV32IMAFC (+Zc), LP RV32IMAC, 128 KB HP ROM / 768 KB L2MEM (200 MHz) / 8 KB SPM @400 MHz. Use the rev-v1.3 datasheet above for this project's silicon |
+
+## Not obtained
+
+| wanted | why not | best known pointer |
+|---|---|---|
+| Standalone `esp32-p4_errata_en.pdf` on espressif.com | No such file exists. The filtered ESP32-P4 document index lists "ESP32-P4 Series SoC Errata" v1.3 whose only link is the esp-chip-errata docs project HTML page; no `/sites/default/files/documentation/*errata*.pdf` is served for any chip. I fetched the vendor-official PDF build of that same document instead (see Obtained), so the content is archived — only the hypothetical filename is missing. | https://docs.espressif.com/projects/esp-chip-errata/en/latest/esp32p4/index.html |
+| ESP32-P4 Chip Revision v1.x User Guide (a v1.3-side counterpart to the v3.x guide) | Not published. The ESP32-P4-filtered document index contains exactly one chip-revision user guide, for v3.x; there is no v1.x/v1.3 equivalent. The v3.x guide covers the delta in the other direction and is archived above. | https://www.espressif.com/en/support/documents/technical-documents (filter Chip = ESP32-P4) |
+| ESP32-P4 Consolidated Pin Overview v1.2 (datasheet appendix) | Published only as `.xlsx`; no PDF exists anywhere official. It is a pin-mux/IO table and carries nothing about bootloader, memory map, interrupts, timers, CSRs, or instructions, so it fails the relevance bar for this archive. | https://www.espressif.com/sites/default/files/documentation/ESP32-P4%20Appendix%20Consolidated%20Pin%20Overview.xlsx |
+| ESP32-P4 Hardware Design Guidelines v1.9; ESP32-P4 Test Tools and Guidelines; ESP32-P4 Series Product Packaging Information | Deliberately excluded: assignment bars hardware-design/PCB-layout/RF and board-production documents. | https://www.espressif.com/en/support/documents/technical-documents |
+
+## Belongs elsewhere
+
+- ESP-IDF Programming Guide for ESP32-P4 (SDK stable v6.0.2 / v5.5.x), esptool.py Programming Guide, ROM bootloader + flash image format, OpenOCD/GDB manuals — should be fetched by `espressif-software/`
+- Vendor SIMD/PIE and HWLP instruction encodings — the source document (generic TRM v0.7, ch.4 PIE p.210 and §2.7.1 HWLP p.119) is archived here in `espressif-silicon/`, but the extension-specific extraction/spec work belongs to `espressif-custom-isa/`; note the rev-v1.3 TRM lists ch.3 "Processor Instruction Extensions" as "[to be added later]" and omits it entirely, so PIE must be cited from the v0.7 TRM
+- RISC-V unprivileged/privileged ISA, Zc, debug spec, and the fast-interrupt/CLIC draft specification — should be fetched by `riscv-isa/`
+- Board/module documents already present at `01-esp32p4-m3/docs/` (JC-ESP32P4-M3 dev-board PDFs, ESP32-C6-MINI-1 module datasheet) — owned by LocalHarvest; out of scope here
diff --git a/cpu-docs/manifests/EspSoftware.md b/cpu-docs/manifests/EspSoftware.md
new file mode 100644
index 0000000..4bbbae5
--- /dev/null
+++ b/cpu-docs/manifests/EspSoftware.md
@@ -0,0 +1,30 @@
+# EspSoftware — Espressif software-side primary docs: boot ROM/bootloader, image format, startup, memory, interrupts, time, flashing, debugging
+
+## Obtained
+
+| file | title | version / date | source URL | bytes | pages | sha256 (first 16) | relevance |
+|---|---|---|---|---|---|---|---|
+| espressif-software/esp-idf-programming-guide_esp32p4_en_v5.3.2.pdf | ESP-IDF Programming Guide — ESP32-P4 | v5.3.2, 2024-12-06 | https://docs.espressif.com/projects/esp-idf/en/v5.3.2/esp32p4/esp-idf-en-v5.3.2-esp32p4.pdf | 13656675 | 2262 | adf06f5531a5c845 | verified TOC pages: 2.9.1 App Image Format p.1364, 2.9.2 Bootloader Image Format p.1370, Heap Memory Allocation p.1593, Interrupt Allocation p.1648, System Time p.1748, ULP LP-Core Coprocessor Programming p.1760, 4.2 Application Startup Flow p.1803 (4.2.1 First/4.2.2 Second Stage Bootloader p.1804), 4.3 Bootloader p.1806, 4.13 JTAG Debugging p.1873, 4.14 Linker Script Generation p.1914, 4.16 Memory Types p.1933, 4.18 Partition Tables p.1938, 5.2.1 Flash Encryption p.2016, 5.2.2 Secure Boot V2 p.2031 |
+| espressif-software/esp-idf-programming-guide_esp32p4_en_v6.0.2_html.zip | ESP-IDF Programming Guide — ESP32-P4 (official offline HTML bundle) | v6.0.2 (current stable, matches `src/soc.zig`) | https://docs.espressif.com/projects/esp-idf/en/v6.0.2/esp32p4/esp-idf-en-v6.0.2.zip | 51594786 | 393 html pages (zip verified `unzip -t` OK) | d3f0f339d4a86a04 | non-PDF fallback: Espressif stopped publishing PDFs after v5.3.2, so v6.0.2 (the version this project cross-references) exists only as the official HTML zip linked in the docs footer; same chapters as above (api-guides/startup, app_image_format, memory-types, interrupt-allocation, system-time, jtag-debugging, ulp-lp-core) |
+| espressif-software/esptool_serial-protocol_esp32p4_v5.3.1.html | esptool Documentation — Serial Protocol (ESP32-P4 target render) | esptool v5.3.1, released 2026-06-29 | https://docs.espressif.com/projects/esptool/en/latest/esp32p4/advanced-topics/serial-protocol.html | 55340 | n/a | a00a70719b10fbd3 | ROM serial loader: SLIP framing, packet/command format, ESP_SYNC/ESP_MEM_*/ESP_FLASH_BEGIN-DATA-END, stub loader, `tools/rom.zig` reference |
+| espressif-software/esptool_firmware-image-format_esp32p4_v5.3.1.html | esptool Documentation — Firmware Image Format (ESP32-P4 render) | esptool v5.3.1, 2026-06-29 | https://docs.espressif.com/projects/esptool/en/latest/esp32p4/advanced-topics/firmware-image-format.html | 16750 | n/a | f9b6269b5d9f3601 | ESP image v1 header, extended header, segment headers, checksum + SHA256 append; `tools/image.zig` reference |
+| espressif-software/esptool_boot-mode-selection_esp32p4_v5.3.1.html | esptool Documentation — Boot Mode Selection (ESP32-P4 render) | esptool v5.3.1, 2026-06-29 | https://docs.espressif.com/projects/esptool/en/latest/esp32p4/advanced-topics/boot-mode-selection.html | 30917 | n/a | 100fdf423ba92cc0 | strapping pins, download/UART boot vs SPI boot, ROM boot log messages |
+| espressif-software/esptool_serial-protocol_v5.3.1.rst | esptool docs source (canonical reStructuredText) | tag v5.3.1 | https://raw.githubusercontent.com/espressif/esptool/v5.3.1/docs/en/advanced-topics/serial-protocol.rst | 76409 | n/a | 016dbe246a0c0edf | version-pinned canonical source of the above (unresolved `IDF_TARGET_*` substitutions) |
+| espressif-software/esptool_firmware-image-format_v5.3.1.rst | esptool docs source (canonical reStructuredText) | tag v5.3.1 | https://raw.githubusercontent.com/espressif/esptool/v5.3.1/docs/en/advanced-topics/firmware-image-format.rst | 15433 | n/a | 1f0cfe32a766b8ab | pinned canonical image-format spec source |
+| espressif-software/esptool_boot-mode-selection_v5.3.1.rst | esptool docs source (canonical reStructuredText) | tag v5.3.1 | https://raw.githubusercontent.com/espressif/esptool/v5.3.1/docs/en/advanced-topics/boot-mode-selection.rst | 21887 | n/a | 567510a46d727a51 | pinned canonical boot-mode spec source |
+
+## Not obtained
+
+| wanted | why not | best known pointer |
+|---|---|---|
+| ESP-IDF Programming Guide PDF for v6.x (esp32p4) | Espressif no longer builds PDFs: every `esp-idf-en-<v>-esp32p4.pdf` guess returns 404 for v5.3.3 and all v5.4/v5.5/v6.0.x; the v6.0.2 page footer offers only "Download HTML" (zip). Newest PDF that exists is v5.3.2, obtained above; v6.0.2 taken as HTML zip. | https://docs.espressif.com/projects/esp-idf/en/v6.0.2/esp32p4/ (footer link `esp-idf-en-v6.0.2.zip`) |
+| esptool documentation offline PDF | No PDF or HTML-zip artifact published for the esptool docs project (all `esptool-en-*.pdf` name patterns 404, no footer download link). Fell back to official rendered HTML + pinned `.rst` sources. | https://docs.espressif.com/projects/esptool/en/latest/esp32p4/ |
+| openocd-esp32 documentation PDF | The `docs.espressif.com/projects/openocd-esp32/` project is retired — `/en/latest/` and `/en/latest/esp32p4/index.html` both return the ReadTheDocs 404 page (deleted, not saved). JTAG/OpenOCD material now lives in the ESP-IDF guide chapter 4.13 (obtained). | https://github.com/espressif/openocd-esp32 (repo `README`/`doc/`) |
+| ESP32-P4 boot ROM / mask ROM description document | No prose document exists. Espressif publishes only the ROM ELF symbol tables and ROM linker scripts; per instructions no code was copied. Local authoritative copies: ROM ELF `/home/goblin/.espressif/tools/esp-rom-elfs/20241011/esp32p4_rev0_rom.elf`; ROM symbol/linker scripts `/home/goblin/esp/esp-idf/components/esp_rom/esp32p4/ld/` (`esp32p4.rom.ld`, `esp32p4.rom.api.ld`, `esp32p4.rom.systimer.ld`, `esp32p4.rom.version.ld`, `esp32p4.rom.eco5.*`, plus LP-core `esp32p4lp.rom.*.ld`). | https://github.com/espressif/esp-rom-elfs ; https://github.com/espressif/esp-idf/tree/master/components/esp_rom/esp32p4/ld |
+| Standalone "ESP32-P4 Serial Protocol" / "Boot Mode Selection" / secure-boot application-note PDFs | Espressif does not publish these as standalone PDFs for ESP32-P4; the content is only in the esptool docs (obtained) and ESP-IDF guide ch. 5.2 (obtained). | https://www.espressif.com/en/support/documents/technical-documents |
+
+## Belongs elsewhere
+
+- ESP32-P4 Technical Reference Manual and Datasheet — `espressif-silicon/` (also already local at `01-esp32p4-m3/docs/`)
+- RISC-V unprivileged/privileged/debug specifications — `riscv-isa/`
+- Espressif custom ISA extension (`xesppie` / PIE) and LP-core ISA documents — `espressif-custom-isa/`
diff --git a/cpu-docs/manifests/LocalHarvest.md b/cpu-docs/manifests/LocalHarvest.md
new file mode 100644
index 0000000..469dde8
--- /dev/null
+++ b/cpu-docs/manifests/LocalHarvest.md
@@ -0,0 +1,45 @@
+# LocalHarvest — machine-local primary documents copied into the archive
+
+## Obtained
+
+| file | title | version / date | source URL | bytes | pages | sha256 (first 16) | relevance |
+|---|---|---|---|---|---|---|---|
+| espressif-silicon/esp32-p4_technical-reference-manual_en_pre-release-v0.7.pdf | ESP32-P4 Technical Reference Manual | Pre-release v0.7, PDF built 2026-08-20 | local copy: /home/goblin/00-projects/0x4200.cafe/01-esp32p4-m3/docs/esp32-p4_technical_reference_manual_en.pdf (orig. docs.espressif.com) | 23537234 | 3701 | 622fe9625d19cf00 | ch.2 High-Performance CPU (CSRs), ch.4 Processor Instruction Extensions (PIE), ch.5 Low-Power CPU, ch.9 System and Memory (memory map/cache), ch.13 Chip Boot Control, ch.14 Interrupt Matrix, ch.17 System Timer, ch.18 Timer Group, ch.19 Watchdog Timers, ch.3 RISC-V Trace Encoder |
+| espressif-silicon/esp32-p4_datasheet_en_pre-release-v0.7.pdf | ESP32-P4 Series Datasheet | Pre-release v0.7, PDF built 2026-07-14 | local copy: /home/goblin/00-projects/0x4200.cafe/01-esp32p4-m3/docs/esp32-p4_datasheet_en.pdf (orig. docs.espressif.com) | 1576185 | 102 | fb4f3e91cc2ac519 | Product Overview (HP dual-core RISC-V + LP core), §1 pin/package, §4.1.4.6 Low-Power Management, in-package PSRAM (16/32 MB) sizing for flash/PSRAM mapping |
+
+Both were verified with `file` (PDF document, version 1.5), `pdfinfo` (page counts above) and `pdftotext -f 1 -l 3` (title + "Pre-release v0.7" text). Destination directory was empty at copy time, so neither is a duplicate; EspSilicon was notified of the names and sha256s over hub so any newer upstream revision lands under its own rev-suffixed name rather than overwriting these.
+
+## Not obtained
+
+| wanted | why not | best known pointer |
+|---|---|---|
+| RISC-V unprivileged/privileged/debug/psABI specs | no RISC-V specification PDF exists anywhere on this machine (bounded `find -maxdepth 6 -iname '*.pdf'` over 0x4200.cafe, ~/esp, ~/.espressif, ~/Downloads, ~/05-genizah; ~/Documents does not exist) | RiscvSpecs agent, upstream github.com/riscv |
+| ESP-IDF / esptool / OpenOCD manuals as PDF | not present locally; the ESP-IDF checkout ships only reStructuredText sources, and the only PDFs under ~/esp/esp-idf are a Unity assertions cheat sheet and a logo asset | EspSoftware agent, docs.espressif.com PDF builds |
+| ESP32-P4 errata / ECO sheet | no local copy | EspSilicon agent |
+
+## Belongs elsewhere
+
+- ESP32-P4 TRM/datasheet at a revision newer than Pre-release v0.7 — `espressif-silicon/`, owned by EspSilicon (upstream fetch).
+- ESP-IDF Programming Guide, esptool, OpenOCD-ESP32 manuals — `espressif-software/`, owned by EspSoftware.
+- RISC-V unprivileged/privileged/debug specs and psABI — `riscv-isa/`, owned by RiscvSpecs.
+- PIE / Xesppie custom-instruction and LP-core documentation extracted upstream — `espressif-custom-isa/`, owned by EspCustomIsa.
+
+## Board-level, deliberately excluded
+
+Present on disk, not CPU documentation, not copied:
+
+- /home/goblin/00-projects/0x4200.cafe/01-esp32p4-m3/docs/JC-ESP32P4-M3-DEV_getting-started.pdf
+- /home/goblin/00-projects/0x4200.cafe/01-esp32p4-m3/docs/JC-ESP32P4-M3-DEV_Specifications-EN.pdf
+- /home/goblin/00-projects/0x4200.cafe/01-esp32p4-m3/docs/JC-ESP32P4-M3_schematic.pdf
+- /home/goblin/00-projects/0x4200.cafe/01-esp32p4-m3/docs/esp32-c6-mini-1_mini-1u_datasheet_en.pdf (companion Wi-Fi module, not the P4 CPU)
+- /home/goblin/00-projects/0x4200.cafe/01-esp32p4-m3/docs/board-top-callouts.jpg and /home/goblin/00-projects/0x4200.cafe/01-esp32p4-m3/docs/schematics/*.png
+
+## Local non-document sources
+
+Code/reference material, authoritative but not documents — must NOT be copied into the archive:
+
+- /home/goblin/esp/esp-idf — ESP-IDF checkout, `git describe` = `v6.0.2` (HEAD 7101770d); reference implementation of startup, image format, cache/MMU setup, interrupt allocation.
+- /home/goblin/esp/esp-idf/components/esp_rom/esp32p4/ld/esp32p4.rom.ld — mask-ROM symbol addresses for the HP core; sibling files `esp32p4.rom.api.ld`, `esp32p4.rom.eco5*.ld` (ECO5 silicon variants), `esp32p4.rom.systimer.ld`, `esp32p4.rom.version.ld`, and `esp32p4lp.rom*.ld` for the LP core.
+- /home/goblin/.espressif/tools/esp-rom-elfs/20241011/esp32p4_rev0_rom.elf — full boot-ROM ELF with symbols; disassemble for ROM loader protocol and entry points.
+- /home/goblin/esp/esp-idf/components/soc/esp32p4/register/hw_ver1/soc/ — the `hw_ver1` (pre-v3 silicon) register headers this project's revision needs; includes `cache_reg.h`, `assist_debug_reg.h`, `efuse_reg.h`, and the matching `*_struct.h` bitfield definitions.
+- /home/goblin/.espressif/tools/riscv32-esp-elf/esp-15.2.0_20251204/ — installed toolchain, `riscv32-esp-elf-gcc (crosstool-NG esp-15.2.0_20251204) 15.2.0`; ground truth for the arch string and psABI behaviour. Note: this compiler *rejects* `xesppie` ("starts with 'x' but is unsupported non-standard extension"); the real rev<v3 string is `-march=rv32imafc_zicsr_zifencei_zaamo_zalrsc_xesploop_xespv2p1 -mabi=ilp32f` — see `manifests/EspCustomIsa.md`.
diff --git a/cpu-docs/manifests/RiscvSpecs.md b/cpu-docs/manifests/RiscvSpecs.md
new file mode 100644
index 0000000..58ef78e
--- /dev/null
+++ b/cpu-docs/manifests/RiscvSpecs.md
@@ -0,0 +1,35 @@
+# RiscvSpecs — official RISC-V International specifications for the ESP32-P4 HP core (RV32IMAFC_Zicsr_Zifencei, M/U modes, PMP, debug)
+
+## Obtained
+
+| file | title | version / date | source URL | bytes | pages | sha256 (first 16) | relevance |
+|---|---|---|---|---|---|---|---|
+| riscv-isa/riscv-unprivileged-isa_vol1_ratified_20250508.pdf | The RISC-V Instruction Set Manual Volume I: Unprivileged Architecture | 20250508, Ratified (release tag `20250508`, published 2025-05-12) | https://github.com/riscv/riscv-isa-manual/releases/download/20250508/riscv-unprivileged-20250508.pdf | 4643378 | 727 | cef2e63c08c6f82c | Ch.2 RV32I base, Ch.5 Zifencei, Ch.6 Zicsr, Ch.7.1 Zicntr (cycle/time/instret, CSR 0xC00–0xC1F with high halves at 0xC80–0xC9F, RDCYCLE/RDCYCLEH), Ch.12 M, Ch.13 A, Ch.20 F single-precision, Ch.27 C compressed, Ch.28 Zc* |
+| riscv-isa/riscv-privileged-architecture_vol2_ratified_20250508.pdf | The RISC-V Instruction Set Manual: Volume II: Privileged Architecture | 20250508, Ratified (release tag `20250508`, published 2025-05-12) | https://github.com/riscv/riscv-isa-manual/releases/download/20250508/riscv-privileged-20250508.pdf | 1372206 | 221 | d0228bbecc76943a | Ch.2.2 CSR listing, Ch.3.1.7 mtvec, 3.1.9 mip/mie, 3.1.10 Hardware Performance Monitor (mcycle), 3.1.12 mcountinhibit, 3.1.14 mepc, 3.1.15 mcause, 3.1.16 mtval, 3.2.1 mtime/mtimecmp, 3.3.2 trap-return (mret), 3.4 Reset, 3.5 NMI, 3.7 Physical Memory Protection (3.7.1 PMP CSRs) |
+| riscv-isa/riscv-external-debug-support_v1.0_20250221.pdf | The RISC-V Debug Specification | 1.0, Ratified, revised 2025-02-21 (release tag `1.0`) | https://github.com/riscv/riscv-debug-spec/releases/download/1.0/riscv-debug-specification.pdf | 2495279 | 119 | ce2787b25233a610 | Ch.3 Debug Module (3.1 DMI, 3.7 abstract commands, 3.8 program buffer, 3.13 version detection, 3.14 DM registers), Ch.4 Sdext (4.1 Debug Mode, 4.5 single step, 4.10 virtual debug registers), Ch.5 Sdtrig triggers (5.7 trigger registers), Ch.6.1 JTAG DTM + dtmcs/dmi, 6.1.7 JTAG connector; 1.2.1.2–1.2.1.4 lists the incompatible changes from 0.13 that Espressif's OpenOCD must work around |
+| riscv-isa/riscv-external-debug-support_v0.13.2_20190322.pdf | RISC-V External Debug Support | 0.13.2, 2019-03-22 (repo commit d5029366, built PDF `riscv-debug-release.pdf`) | https://riscv.org/wp-content/uploads/2019/03/riscv-debug-release.pdf | 818053 | 94 | f203abb93ee2ad60 | **The version ESP32-P4 actually implements** — TRM states "Debug module (DM) compliant with … RISC-V External Debug Support Version 0.13.2" for the HP DM and "Version 0.13" for the LP DM. Ch.3 Debug Module (3.12 DM registers dmstatus@0x11/dmcontrol@0x10/command@0x17/progbuf0@0x20), Ch.4 core debug registers (dcsr/dpc), Ch.5 Trigger Module, Ch.6 JTAG DTM (dmi@0x11) |
+| riscv-isa/riscv-elf-psabi_riscv-abi_draft-20260813.pdf | RISC-V ABIs Specification (psABI: calling convention + ELF) | v1.1, 2026-08-13, "Pre-release" (release tag `draft-20260813-01017c3`) | https://github.com/riscv-non-isa/riscv-elf-psabi-doc/releases/download/draft-20260813-01017c343cd6d89ed4d1d568b1c75fac79d2a689/riscv-abi.pdf | 526941 | 118 | ff94b93578a5ee44 | Ch.1.1/1.3 integer + FP register convention, Ch.2.1/2.2 integer and hardware-FP calling convention, Ch.2.7/2.8 named ABIs (ilp32/ilp32f), Ch.5 code models (medlow/medany), Ch.9.1 ELF file header + e_flags, Ch.9.4 relocations (used by the hand-written linker script and LLD), Ch.9.6 sections, Ch.9.7 program header table, Ch.9.11.1 layout of `.riscv.attributes` |
+| riscv-isa/riscv-fast-interrupt_clic_draft-v0.10_20250324.pdf | Core-Local Interrupt Controller (CLIC) RISC-V Privileged Architecture Extensions | v0.10, 2025-03-17, **Draft** (release tag `v0.10`, published 2025-03-24 — newest release carrying `clic.pdf`) | https://github.com/riscv/riscv-fast-interrupt/releases/download/v0.10/clic.pdf | 434674 | 69 | ddb80f16aecb98ff | Ch.2 CLIC overview + preemption, Ch.3 `smclic` M-mode extension (3.1 level/priority, 3.2 clicintip, 3.3 clicintie, 3.4 clicintattr, 3.5 clicintctl, 3.8 CLIC CSRs incl. mintthresh/mnxti, 3.9 reset, 3.10 interrupt operation), Ch.5 `smclicshv` selective hardware vectoring, Ch.6 CLIC parameters — the architectural model behind the P4's CLIC/INTPRI |
+| riscv-isa/riscv-fast-interrupt_aclic_draft-v0.20_20260731.pdf | Advanced Core-Local Interrupt Controller (ACLIC) RISC-V Privileged Architecture Extensions | v0.20, 2026-07-31, "Stable" but unratified draft (release tag `v0.20`) | https://github.com/riscv/riscv-fast-interrupt/releases/download/v0.20/aclic-v0.20.pdf | 282310 | 38 | 1892f06fd863fe73 | Successor document to CLIC in the same task-group repo; current draft register/CSR model for core-local fast interrupts. Secondary to the v0.10 CLIC PDF for P4 work — the P4 predates it |
+| riscv-isa/riscv-assembly-programmers-manual_v0.0.1_20250205.pdf | RISC-V Assembly Programmer's Manual | tag `v0.0.1`, 2025-02-05 (document self-labels "v0.0.0, Development state") | https://github.com/riscv-non-isa/riscv-asm-manual/releases/download/v0.0.1/riscv-asm.pdf | 238665 | 50 | 2edf43ff39c0ca47 | Ch.1 command-line arguments, Ch.2.1/2.2 general + control register naming, plus assembler directives/relocation-modifier syntax used in hand-written startup asm and linker-script-adjacent code |
+| riscv-isa/riscv-code-size-reduction_zc_v1.0.4-3_20231026.pdf | Zc* code-size-reduction extension specification | v1.0.4-3, 2023-10-26 (release tag `v1.0.4-3`, riscvarchive) | https://github.com/riscvarchive/riscv-code-size-reduction/releases/download/v1.0.4-3/Zc-1.0.4-3.pdf | 916986 | 60 | 62cea3875763904b | Standalone Zc* doc; §1.1 change history records the `C implies Zca/Zcf/Zcd` and `misa.C` rules that matter when naming the P4's `c` extension in a target triple. Superseded in-tree by Vol I Ch.28 — low priority |
+| riscv-isa/riscv-plic_v1.0.0_20230312.pdf | RISC-V Platform-Level Interrupt Controller Specification | 1.0.0, 3/2023, Ratified (release tag `1.0.0`) | https://github.com/riscv/riscv-plic-spec/releases/download/1.0.0/riscv-plic-1.0.0.pdf | 545211 | 18 | 82644c7701601baa | Low relevance — ESP32-P4 uses its own interrupt matrix + CLIC-style controller, not a PLIC; kept only as the contrast point referenced by CLIC §1.3 |
+| riscv-isa/riscv-aclint_v1.0-rc4_20220114.pdf | RISC-V Advanced Core Local Interruptor Specification | 1.0-rc4, 2022-01-10, **Draft** (release tag `v1.0-rc4`, riscvarchive; never ratified) | https://github.com/riscvarchive/riscv-aclint/releases/download/v1.0-rc4/riscv-aclint-1.0-rc4.pdf | 133041 | 11 | fb7f1473470fbc2a | Low relevance — Ch.2 MTIMER (mtime/mtimecmp) and Ch.3 MSWI describe the CLINT-style timer the P4 does *not* use (it has systimer/TIMG instead); useful only when comparing against Vol II §3.2.1 |
+
+All 11 files verified: `file` reports "PDF document", `pdfinfo` parses (page counts above), and `pdftotext -f 1 -l 2` shows the expected title and version string on page 1 (e.g. "Version 20250508: This document is in Ratified state.", "Version 1.0, Revised 2025-02-21: Ratified", "RISC-V External Debug Support / Version 0.13.2"). Total directory size 12 MB.
+
+## Not obtained
+
+| wanted | why not | best known pointer |
+|---|---|---|
+| Debug spec 0.13.2 as a GitHub *release* asset | No release exists for 0.13.2 in `riscv/riscv-debug-spec` (oldest release with an asset is `task_group_vote`, 2018). The obtained file is the official built PDF from riscv.org; it is byte-identical (818053 bytes, sha256 f203abb93ee2ad60) to the repo-hosted `riscv-debug-release.pdf` at the 0.13.2 commit, so provenance is confirmed against github.com/riscv | https://github.com/riscv/riscv-debug-spec/raw/4e0bb0fc2d843473db2356623792c6b7603b94d4/riscv-debug-release.pdf |
+| Separate "ELF psABI" PDF distinct from `riscv-abi.pdf` | Does not exist: the repo publishes a single merged artifact ("RISC-V ABIs Specification") whose Ch.9 *is* the ELF psABI. Only `draft-YYYYMMDD-<sha>` releases are published — there is no ratified/non-draft psABI release, so the newest draft was taken | https://github.com/riscv-non-isa/riscv-elf-psabi-doc/releases |
+| Ratified CLIC / fast-interrupt spec | None exists. The task group has only ever published drafts; releases `v0.9`–`v0.10` carry `clic.pdf`, and `v0.16`–`v0.20` replaced it with `aclic.pdf`. Both newest artifacts of each lineage were taken and are labelled drafts above | https://github.com/riscv/riscv-fast-interrupt/releases (v0.10 = last `clic.pdf`; v0.20 = newest `aclic.pdf`) |
+| Newer-than-20250508 ratified ISA manual | Not available. All 700+ newer tags in `riscv/riscv-isa-manual` are automated nightly `riscv-isa-release-<sha>-<date>` builds of the in-development merged `riscv-spec.pdf` (latest 2026-08-24), which are unratified. `20250508` is the newest ratified release and the only recent one shipping split Vol I / Vol II PDFs | https://github.com/riscv/riscv-isa-manual/releases/tag/20250508 |
+| Ratified ACLINT 1.0 | Never ratified; repo moved to `riscvarchive` with `v1.0-rc4` (2022) as the final artifact. rc4 fetched and marked low relevance | https://github.com/riscvarchive/riscv-aclint/releases/tag/v1.0-rc4 |
+
+## Belongs elsewhere
+
+- ESP32-P4 Technical Reference Manual (its "RISC-V CPU", "Interrupt Matrix", "CLIC/INTPRI" and "Debug" chapters state DM compliance with debug spec 0.13.2) — should be fetched by `espressif-silicon/`
+- Espressif OpenOCD / JTAG debugging manual and GDB usage docs — should be fetched by `espressif-software/`
+- Espressif `Xesppie` / PIE custom-instruction documentation and the LP-core (`rv32imac`-class) ISA notes — should be fetched by `espressif-custom-isa/`