From 9ab0cbb93dd7678dcc8e86e164325e7d1b8ea7c6 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 25 Aug 2026 15:42:03 -0300 Subject: 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. --- cpu-docs/manifests/EspCustomIsa.md | 86 ++++++++++++++++++++++++++++++++++++++ cpu-docs/manifests/EspSilicon.md | 28 +++++++++++++ cpu-docs/manifests/EspSoftware.md | 30 +++++++++++++ cpu-docs/manifests/LocalHarvest.md | 45 ++++++++++++++++++++ cpu-docs/manifests/RiscvSpecs.md | 35 ++++++++++++++++ 5 files changed, 224 insertions(+) create mode 100644 cpu-docs/manifests/EspCustomIsa.md create mode 100644 cpu-docs/manifests/EspSilicon.md create mode 100644 cpu-docs/manifests/EspSoftware.md create mode 100644 cpu-docs/manifests/LocalHarvest.md create mode 100644 cpu-docs/manifests/RiscvSpecs.md (limited to 'cpu-docs/manifests') 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--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` 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--` 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/` -- cgit v1.3