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