mirror of
https://github.com/retroSoC/retroSoC.git
synced 2026-11-04 22:32:36 +00:00
docs: add environment reference and enhance publication validation
- Introduced to define the development environment and validate runtime/platform contracts. - Enhanced with to ensure change markers adhere to publication rules. - Updated to integrate boot acceptance checks and ensure dependencies are correctly managed. - Added tests for environment validation, publication change scope, and CI stages to prevent regression and ensure compliance with publication standards. - Implemented checks in to validate the presence of development environment dependencies. - Refactored existing tests to improve coverage and ensure accurate validation of publication claims and software configurations.
This commit is contained in:
97 files changed
+2180
-801
No files matched your search
+69
-22
@@ -21,8 +21,8 @@ register/bitfield and software reference chapters. Each actual IP starts on a
|
||||
new page; UART/SDIO instances share their common register descriptions.
|
||||
CPU ISA/CSR manuals remain outside this publication's scope.
|
||||
|
||||
The 2026-09-22 refresh binds v0.5 DRAFT to reviewed dev commit
|
||||
`ca4b06d30456599a2d3fd676d832f8d4dd2f78af`. NPU has an independent chapter
|
||||
The current 2026-09-22 refresh retains v0.5 DRAFT and binds it to reviewed dev commit
|
||||
`c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b`. NPU retains its independent chapter
|
||||
after APU. The reviewed contract contains 42 IP chapters and 109 frozen entries;
|
||||
the nine-category Overview contains 45 labels. Existing register anchors remain
|
||||
stable. The main reference stays IHP130 PRODUCT / 32 KiB SRAM, with the dedicated
|
||||
@@ -43,6 +43,22 @@ an integrated eight-beat AXI64 DMA limit; its reusable DMA default is not the
|
||||
deployed limit. Native Linux NPU/ASoC support is not inferred from HP smoke code.
|
||||
CI workflow outcomes are a separately scoped snapshot, including failures and
|
||||
skipped downstream tests; they do not populate per-IP hardware pass records.
|
||||
The current presentation round compares against the retained 779-page PDF with
|
||||
SHA-256 `25257e5243e945401c8a214d4043819cf802a7fa2d22b04d83b513ce9075647b`.
|
||||
It uses `v05-emphasis-` markers for the cover contact, partial Functional mark
|
||||
and selected body emphasis. Earlier `v05-refresh-` boot/mailbox, APU, environment
|
||||
and navigation corrections remain historical. The version and document date are retained. This presentation is built directly
|
||||
from the reviewed current dev checkout; its complete source SHA and timestamped
|
||||
CI observations identify the build. Runtime-library/bootstrap increments were
|
||||
reviewed separately and do not change the hardware interfaces.
|
||||
|
||||
The cover stores the author name and email separately; PDF author metadata keeps
|
||||
the name. Artifact marks explicitly support empty, left-half and full states.
|
||||
Body emphasis uses selected Inter Bold phrases, including explicit `**...**`
|
||||
spans in generated IP text, while code and diagram labels retain their own rules.
|
||||
See the [layout/content standard](datasheets/style.md) for exact geometry,
|
||||
emphasis scope and validation requirements. Rebuild all page-dependent records
|
||||
after typography changes and retain the previous PDF and actual test verdicts.
|
||||
|
||||
The full drawing layer uses bytefield 0.0.8, rivet 0.3.1, blockcell 0.1.0 and
|
||||
circuiteria 0.2.1. All 42 IP chapters and four system hardware figures use
|
||||
@@ -54,20 +70,20 @@ memory, descriptor examples, address windows, linker/load placement and budgets.
|
||||
Overview classification, access matrices, software flows, register bit layouts
|
||||
and WaveDrom keep their existing rendering.
|
||||
|
||||
Section 2.1.1 adds a compact functional overview drawn independently with locked
|
||||
Section 2.1.1 contains a compact functional overview drawn independently with locked
|
||||
CeTZ 0.5.2. It uses regular 9 pt text for ordinary labels, regular 8 pt text
|
||||
inside compact CDC/Gateway cells, and bold 9 pt bus/domain labels. Individually named PRODUCT IP/instance
|
||||
rows, external signal groups and explicit Gateway A/B fan-in. AXI32/AXI64
|
||||
labels appear only in bus-spine and bridge symbols. Clock-domain backgrounds
|
||||
are separate from IP categories. The original 45 Circuiteria figures continue
|
||||
to use their existing renderer; NPU adds one circuit, three binary layouts and two storage
|
||||
figures, bringing the inventory to 142 specialized figures.
|
||||
are separate from IP categories. All 46 Circuiteria figures retain their existing
|
||||
renderer. The 142 specialized figures include NPU's circuit, three binary layouts
|
||||
and two storage figures.
|
||||
|
||||
`soc_diagram_reference.py` checks the new `datasheets/soc-architecture.json`
|
||||
`soc_diagram_reference.py` checks `datasheets/soc-architecture.json`
|
||||
against PRODUCT IP coverage, selected RTL clock/interface bindings, gateway
|
||||
clients, stream routes, pin groups and alternate-function mappings. Its CeTZ
|
||||
renderer is `datasheets/soc-architecture.typ`. The new diagram is recorded under
|
||||
Introduction; the NPU node is tied to its new chapter and HP-domain background.
|
||||
renderer is `datasheets/soc-architecture.typ`. The diagram is recorded under
|
||||
Introduction; the NPU node is tied to its chapter and HP-domain background.
|
||||
`soc_diagram_geometry.py` supplies the exact paths and arrowheads to CeTZ and
|
||||
checks orthogonality, visible shafts, symbol avoidance and arrow clearance.
|
||||
The arrowheads are 1 x 0.8 mm with at least 1 mm visible shaft and 0.5 mm
|
||||
@@ -137,13 +153,23 @@ completeness, so the content and chapter reviews also record what was retained,
|
||||
updated or awaits evidence, with a concrete recommendation.
|
||||
|
||||
CI snapshots keep `status` separate from nullable `conclusion`. Queued/in-progress
|
||||
runs have no verdict. Refresh the snapshot for the document commit before final
|
||||
delivery; do not reuse a previous commit's formatting failure or passing outcome.
|
||||
runs have no verdict. Retain the complete source SHA, UTC check time, run URL and
|
||||
job/step scope. Refresh the snapshot for the document commit before final delivery;
|
||||
do not reuse a previous commit's formatting failure or passing outcome. Distinguish
|
||||
a failed prerequisite from skipped runtime stages and completed scoped tests.
|
||||
Historical GA2D/NPU records remain dated narrative references unless their raw
|
||||
artifacts, source, profile and stage can be verified. APU smoke subsets and tests
|
||||
that return early without tools/data are not full-corpus or sustained-audio passes.
|
||||
Previous local test counts remain historical, not this refresh's validation result.
|
||||
Publication tests/builds do not promote RTL maturity or physical qualification.
|
||||
|
||||
Source review follows the selected runtime stage through the complete terminal
|
||||
sequence. The `HP_LINUX_READY` marker is also used by freestanding acceptance
|
||||
payloads; it alone does not prove Linux readiness or completion of the later GA2D
|
||||
and cache-clean handoff. Keep mailbox offsets, event purposes, polling units and
|
||||
failure/reset ownership consistent in summaries, tables, diagrams and detailed
|
||||
prose. Source-binding checks complement this semantic review rather than replace it.
|
||||
|
||||
### System-use reference
|
||||
|
||||
The same reviewed snapshot also includes configuration/feature availability,
|
||||
@@ -165,7 +191,8 @@ configuration, HAL, boot loader and Linux platform files.
|
||||
Implementation, test availability and reviewed successful runs are separate
|
||||
states. A Linux device-tree node or bare-metal HAL is not native driver support.
|
||||
The supplied initial console uses SBI. The loader's DMA failure path falls back
|
||||
to software copy/CRC; its final Linux-ready wait has no firmware-local deadline.
|
||||
to software copy/CRC. Its ready/result/cache waits use bounded polling iterations;
|
||||
the initial ready message does not complete the later acceptance and ownership return.
|
||||
CRC is not authentication. Power isolation, qualified entropy, physical ratings
|
||||
and production APU codec support are not inferred from controller capabilities.
|
||||
|
||||
@@ -306,12 +333,14 @@ offline. The compiler is invoked with system fonts disabled, only the media font
|
||||
directory and the verified package cache. No root Makefile target or automatic
|
||||
publication workflow is added.
|
||||
|
||||
If other work has advanced the hardware beyond `source_revision`, retain those
|
||||
changes and use an isolated checkout matching the reviewed snapshot with the
|
||||
publication changes applied there. Do not bypass the snapshot check or advance
|
||||
the advertised hardware revision to make a document build pass. Keep managed
|
||||
source checkouts inside that checkout so source-path containment remains valid;
|
||||
record the isolated publication checkout and input hashes in the build manifest.
|
||||
If the requested baseline is current `dev`, review the complete increment from
|
||||
the previous publication SHA, update the source identity and CI observation,
|
||||
then build directly in that checkout while preserving unrelated local changes.
|
||||
Do not advance the advertised revision merely to silence a snapshot error.
|
||||
Use an isolated checkout only when retaining an older reviewed snapshot is
|
||||
actually required by the task. Its managed inputs must remain inside that
|
||||
checkout, and its path/input hashes belong in the build manifest. Do not bypass
|
||||
the source check in either workflow; remove temporary checkouts when requested.
|
||||
|
||||
Output goes to `build/datasheet-mini-<YYYY-MM-DD-HH-MM>-<input-hash>/`:
|
||||
|
||||
@@ -385,10 +414,21 @@ the main lock. A normal build never commits, pushes, or changes asset revisions.
|
||||
|
||||
## Updating technical content
|
||||
|
||||
1. Review the current dev RTL and committed configurations; set the exact
|
||||
reviewed SHA in `mini.json`. The builder rejects changed technical sources
|
||||
Follow [CONTRIBUTING.md](../CONTRIBUTING.md) and the
|
||||
[Git workflow](../docs/git-workflow.md) when preparing publication contributions.
|
||||
Ordinary PRs target `dev` and default to merge commits; preserve unrelated history
|
||||
and use the repository PR template. These are maintenance instructions, not a
|
||||
product chapter.
|
||||
|
||||
1. Review the current dev RTL and committed configurations; set the complete
|
||||
reviewed SHA in `mini.json` and record the UTC source/CI observation time.
|
||||
Recheck dev before handoff and review any subsequent delta before advancing
|
||||
the snapshot. The builder rejects changed technical sources
|
||||
relative to this snapshot, including uncommitted tracked changes.
|
||||
2. Update explanatory prose and `ip-catalog.json`. Every allocated region,
|
||||
2. Assess every frozen chapter: retain adequate content, correct stale facts and
|
||||
record specific source/specification or evidence gaps. Reconcile Features,
|
||||
summaries, tables, detailed prose, diagrams and examples for the same fact.
|
||||
Update explanatory prose and `ip-catalog.json` only as needed. Every allocated region,
|
||||
including reserved ranges, and every LP IRQ must have exactly one owner in
|
||||
the publication catalog. Keep still-integrated IPs and their child headings.
|
||||
3. Address, LP IRQ, GPIO, pad and access-policy data come from existing canonical
|
||||
@@ -397,7 +437,14 @@ the main lock. A normal build never commits, pushes, or changes asset revisions.
|
||||
JPEG occupies AXI64 slot 6; APU advertises WAV/FLAC job/transport infrastructure
|
||||
while MP3 remains unsupported and KWS requires the P7 configuration; full production qualification is not established. Managed-IP links use their locked
|
||||
upstream commits, not nonexistent main-repository blob paths.
|
||||
5. Compile, check, render all pages and inspect 100% scale and grayscale.
|
||||
5. Record official commercial reference identity, version, release/check dates
|
||||
and the organization adopted in the content review. Keep release-specific
|
||||
source/baseline/marker decisions there and long-lived maintenance rules in
|
||||
`datasheets/style.md`. Do not borrow device specifications or qualification.
|
||||
6. Compile, check, render all pages and inspect 100% scale and grayscale. Verify
|
||||
the existing document-map links and current-round change ranges against the
|
||||
previous delivered PDF. Report current checks with their actual scope and
|
||||
outcomes; do not reuse prior test totals as a current pass.
|
||||
|
||||
### Deliberately unfilled specifications
|
||||
|
||||
|
||||
@@ -0,0 +1,301 @@
|
||||
"""Reviewed HP boot phases and mailbox semantics for the publication only."""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Callable
|
||||
|
||||
from publications.implementation_reference import without_comments
|
||||
|
||||
|
||||
BOOT_SOURCE = "app/apps/hp_boot/main.c"
|
||||
READY_SOURCE = "app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp"
|
||||
HAL_SOURCE = "crt/src/hal/hp_mailbox.c"
|
||||
STATUS_SOURCE = "crt/include/retrosoc/core/status.h"
|
||||
REGISTER_SOURCE = "rtl/ip/peripheral/hp_mailbox_define.svh"
|
||||
MAILBOX_SOURCE = "rtl/ip/peripheral/apb4_hp_mailbox.sv"
|
||||
MAP_SOURCE = "rtl/mini/address_map/memory_map.json"
|
||||
SOURCES = {BOOT_SOURCE, READY_SOURCE, HAL_SOURCE, STATUS_SOURCE, REGISTER_SOURCE, MAILBOX_SOURCE, MAP_SOURCE}
|
||||
NPU_DEFINES = ("RS_NPU_P5_ACCEPTANCE", "RS_NPU_P6_ACCEPTANCE")
|
||||
|
||||
|
||||
def compact(source: str) -> str:
|
||||
return re.sub(r"\s+", "", without_comments(source))
|
||||
|
||||
|
||||
def uint_constants(source: str) -> dict[str, int]:
|
||||
return {name: int(value, 0) for name, value in re.findall(
|
||||
r"^#define\s+(\w+)\s+UINT32_C\((0x[\da-fA-F]+|\d+)\)\s*$", source, re.M)}
|
||||
|
||||
|
||||
def ready_mailbox(root: Path) -> list[dict]:
|
||||
"""Resolve rootfs writes to register purposes, rather than positional labels."""
|
||||
hal = (root / HAL_SOURCE).read_text(encoding="utf-8")
|
||||
rtl = (root / REGISTER_SOURCE).read_text(encoding="utf-8")
|
||||
offsets = {name: int(value, 16) for name, value in re.findall(
|
||||
r"^`define\s+APB4_HP_MAILBOX__(\w+)\s+12'h([\da-fA-F]+)\s*$", rtl, re.M)}
|
||||
constants = uint_constants(hal)
|
||||
registers = ("HP_EVENT", "HP_ARG0", "HP_SEQUENCE", "HP_DOORBELL")
|
||||
if not set(registers) <= offsets.keys():
|
||||
raise ValueError("missing HP ready mailbox registers")
|
||||
for register in registers[:-1]:
|
||||
if constants.get(f"RS_HP_MAILBOX_{register}_OFFSET") != offsets[register]:
|
||||
raise ValueError("HP ready mailbox HAL/RTL offset mismatch")
|
||||
hal_bindings = (
|
||||
"message->code = *rs_hp_mailbox_register(RS_HP_MAILBOX_HP_EVENT_OFFSET);",
|
||||
"message->argument = *rs_hp_mailbox_register(RS_HP_MAILBOX_HP_ARG0_OFFSET);",
|
||||
"sequence = *rs_hp_mailbox_register(RS_HP_MAILBOX_HP_SEQUENCE_OFFSET);",
|
||||
"message->sequence = sequence;",
|
||||
"RS_SOC_APB4_HP_MAILBOX_BASE + offset",
|
||||
)
|
||||
if any(compact(binding) not in compact(hal) for binding in hal_bindings):
|
||||
raise ValueError("HP ready mailbox HAL field semantics changed")
|
||||
mailbox = (root / MAILBOX_SOURCE).read_text(encoding="utf-8")
|
||||
if "`APB4_HP_MAILBOX__HP_DOORBELL:s_lp_intr_state_d=1'b1;" not in compact(mailbox):
|
||||
raise ValueError("HP ready doorbell no longer requests the LP interrupt")
|
||||
address_map = json.loads((root / MAP_SOURCE).read_text(encoding="utf-8"))
|
||||
windows = [row for row in address_map["regions"] if row["symbol"] == "APB4_HP_MAILBOX"]
|
||||
if len(windows) != 1:
|
||||
raise ValueError("missing or ambiguous HP mailbox address window")
|
||||
base = int(windows[0]["base"], 0)
|
||||
boot_constants = uint_constants((root / BOOT_SOURCE).read_text(encoding="utf-8"))
|
||||
expected_values = [boot_constants[key] for key in (
|
||||
"RS_HP_BOOT_READY_EVENT", "RS_HP_BOOT_READY_ARG", "RS_HP_BOOT_MAILBOX_READY_SEQUENCE")] + [1]
|
||||
ready = (root / READY_SOURCE).read_text(encoding="utf-8")
|
||||
writes = [(int(address, 0), int(value, 0)) for address, value in re.findall(
|
||||
r"^\s*devmem\s+(0x[\da-fA-F]+)\s+32\s+(0x[\da-fA-F]+)\s*$", ready, re.M)]
|
||||
expected = [(base + offsets[register], value)
|
||||
for register, value in zip(registers, expected_values, strict=True)]
|
||||
if writes != expected or sum(line.lstrip().startswith("devmem ") for line in ready.splitlines()) != len(writes):
|
||||
raise ValueError("Linux ready mailbox sequence changed")
|
||||
message = 'echo "retroSoC HP Linux ready"'
|
||||
if message not in ready or ready.index(message) > ready.index("devmem"):
|
||||
raise ValueError("Linux ready message/publication order changed")
|
||||
# A newly added responder invalidates the documented ready-only service gap.
|
||||
shell_lines = [line.strip() for line in ready.splitlines()
|
||||
if line.strip() and not line.lstrip().startswith("#")]
|
||||
scaffold = ['case "$1" in', "start)", message, ";;", "esac"]
|
||||
if [line for line in shell_lines if not line.startswith("devmem ")] != scaffold:
|
||||
raise ValueError("Linux ready-only service changed; review its acceptance coverage")
|
||||
purposes = {"HP_EVENT": "Linux-ready event", "HP_ARG0": "Ready-state argument",
|
||||
"HP_SEQUENCE": "Publication sequence", "HP_DOORBELL": "LP interrupt request"}
|
||||
register_by_address = {base + offsets[register]: register for register in registers}
|
||||
return [{"address": f"0x{address:08X}", "value": f"0x{value:08X}",
|
||||
"register": register_by_address[address], "purpose": purposes[register_by_address[address]]}
|
||||
for address, value in writes]
|
||||
|
||||
|
||||
def split_npu_conditions(body: str) -> tuple[str, list[tuple[str, str]]]:
|
||||
"""Keep unconditional acceptance separate from reviewed optional NPU blocks."""
|
||||
unconditional, blocks, current = [], [], []
|
||||
condition = None
|
||||
allowed = {f"defined({name})" for name in NPU_DEFINES}
|
||||
allowed.add("||".join(f"defined({name})" for name in NPU_DEFINES))
|
||||
for line in body.splitlines():
|
||||
directive = line.strip()
|
||||
if directive.startswith("#if "):
|
||||
if condition is not None or compact(directive[4:]) not in allowed:
|
||||
raise ValueError("HP boot optional NPU condition changed")
|
||||
condition = compact(directive[4:])
|
||||
current = []
|
||||
elif directive == "#endif":
|
||||
if condition is None:
|
||||
raise ValueError("unmatched HP boot preprocessor condition")
|
||||
blocks.append((condition, "\n".join(current)))
|
||||
condition = None
|
||||
elif directive.startswith("#"):
|
||||
raise ValueError("unreviewed HP boot preprocessor branch")
|
||||
elif condition is None:
|
||||
unconditional.append(line)
|
||||
else:
|
||||
current.append(line)
|
||||
if condition is not None:
|
||||
raise ValueError("unterminated HP boot optional NPU condition")
|
||||
return "\n".join(unconditional), blocks
|
||||
|
||||
|
||||
def validate_cache_handoff(source: str, main: str, function_body: Callable[[str, str], str]) -> None:
|
||||
"""Bind success to the complete positive cache/held branch, not call presence."""
|
||||
# Progress-only prints may change without changing the acceptance contract.
|
||||
without_progress = re.sub(r'\bprintf\("(?:\\.|[^"\\])*"\);', "", main)
|
||||
success_branch = compact("""
|
||||
if (rs_hp_boot_wait_cache_request()) {
|
||||
if (rs_hp_boot_wait_message(RS_HP_BOOT_GA2D_CACHE_EVENT, RS_HP_BOOT_GA2D_CACHE_ARG,
|
||||
RS_HP_BOOT_MAILBOX_CACHE_SEQUENCE)) {
|
||||
if (rs_resource_acknowledge_cache_clean() == RS_OK) {
|
||||
if (rs_hp_boot_wait_hp_held()) {
|
||||
cache_clean_completed = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
""")
|
||||
if without_progress.count(success_branch) != 1:
|
||||
raise ValueError("HP boot positive cache-handoff success guards changed")
|
||||
|
||||
expected_request = compact("""
|
||||
rs_resource_cache_status_t cache_status;
|
||||
for (uint32_t timeout = 0U; timeout < RS_HP_BOOT_EVENT_TIMEOUT; ++timeout) {
|
||||
if (rs_resource_get_cache_status(&cache_status) != RS_OK) {
|
||||
return false;
|
||||
}
|
||||
if (cache_status.request && !cache_status.clean) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
""")
|
||||
if compact(function_body(source, "rs_hp_boot_wait_cache_request")) != expected_request:
|
||||
raise ValueError("HP boot cache request/clean observation changed")
|
||||
|
||||
held, gated = split_npu_conditions(function_body(source, "rs_hp_boot_wait_hp_held"))
|
||||
expected_held = compact("""
|
||||
rs_sysctrl_hp_status_t hp_status;
|
||||
for (uint32_t timeout = 0U; timeout < RS_HP_BOOT_EVENT_TIMEOUT; ++timeout) {
|
||||
if ((rs_sysctrl_get_hp_status(&hp_status) == RS_OK) && hp_status.reset_asserted &&
|
||||
!hp_status.released && !hp_status.draining && !hp_status.forced_fault &&
|
||||
rs_hp_boot_ga2d_idle(RS_RESOURCE_OWNER_HP)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
""")
|
||||
expected_npu_condition = "||".join(f"defined({name})" for name in NPU_DEFINES)
|
||||
if compact(held) != expected_held:
|
||||
raise ValueError("HP boot held-state reset/release/drain/fault or safe-idle condition changed")
|
||||
if [(condition, compact(body)) for condition, body in gated] != [
|
||||
(expected_npu_condition, "&&rs_hp_boot_npu_idle(RS_RESOURCE_OWNER_HP)")]:
|
||||
raise ValueError("HP boot held-state NPU safe-idle condition changed")
|
||||
|
||||
expected_ga2d_idle = compact("""
|
||||
rs_ga2d_capability_t capability;
|
||||
rs_ga2d_status_t ga2d_status;
|
||||
rs_resource_status_t resource_status;
|
||||
return (rs_ga2d_get_capability(&capability) == RS_OK) &&
|
||||
(capability.features == RS_GA2D_CAPABILITY_P5) &&
|
||||
(capability.limits == RS_GA2D_LIMITS_P5) &&
|
||||
(capability.formats == RS_GA2D_FORMAT_CAPABILITY_P5) &&
|
||||
(rs_ga2d_get_status(&ga2d_status) == RS_OK) && !ga2d_status.busy &&
|
||||
!ga2d_status.draining && !ga2d_status.error && !ga2d_status.aborted &&
|
||||
!ga2d_status.recovery_required && ga2d_status.data_ready &&
|
||||
(rs_resource_get_status(RS_RESOURCE_GA2D, &resource_status) == RS_OK) &&
|
||||
(resource_status.owner == expected_owner) && resource_status.idle &&
|
||||
!resource_status.fault && !resource_status.blocked && !resource_status.quiesced &&
|
||||
!resource_status.in_reset;
|
||||
""")
|
||||
expected_npu_idle = compact("""
|
||||
rs_npu_status_t npu_status;
|
||||
rs_resource_status_t resource_status;
|
||||
return (rs_npu_get_status(&npu_status) == RS_OK) &&
|
||||
((npu_status.flags &
|
||||
(RS_NPU_STATUS_BUSY | RS_NPU_STATUS_DRAINING | RS_NPU_STATUS_RECOVERING)) == 0U) &&
|
||||
(rs_resource_get_status(RS_RESOURCE_NPU, &resource_status) == RS_OK) &&
|
||||
(resource_status.owner == expected_owner) && resource_status.idle &&
|
||||
!resource_status.fault && !resource_status.blocked && !resource_status.quiesced &&
|
||||
!resource_status.in_reset;
|
||||
""")
|
||||
for name, expected in (("ga2d", expected_ga2d_idle), ("npu", expected_npu_idle)):
|
||||
if compact(function_body(source, f"rs_hp_boot_{name}_idle")) != expected:
|
||||
raise ValueError(f"HP boot {name} safe-idle predicate changed")
|
||||
|
||||
|
||||
def collect_boot_acceptance(root: Path, function_body: Callable[[str, str], str]) -> dict:
|
||||
source = (root / BOOT_SOURCE).read_text(encoding="utf-8")
|
||||
status = (root / STATUS_SOURCE).read_text(encoding="utf-8")
|
||||
default = re.findall(r"^#define\s+RS_TIMEOUT_DEFAULT\s+\(\(rs_timeout_t\)(\d+)U\)\s*$", status, re.M)
|
||||
multiplier = re.findall(r"^#define\s+RS_HP_BOOT_EVENT_TIMEOUT\s+"
|
||||
r"\(RS_TIMEOUT_DEFAULT\s*\*\s*UINT32_C\((\d+)\)\)\s*$", source, re.M)
|
||||
if len(default) != 1 or len(multiplier) != 1:
|
||||
raise ValueError("HP boot polling budget expression changed")
|
||||
iterations = int(default[0]) * int(multiplier[0])
|
||||
if iterations < 1 or iterations > 0xFFFFFFFF:
|
||||
raise ValueError("HP boot polling budget is not a positive uint32 bound")
|
||||
for name, bound in (
|
||||
("sdram", "RS_TIMEOUT_DEFAULT"), ("ga2d_idle", "RS_HP_BOOT_EVENT_TIMEOUT"),
|
||||
("npu_idle", "RS_HP_BOOT_EVENT_TIMEOUT"), ("message", "RS_HP_BOOT_EVENT_TIMEOUT"),
|
||||
("cache_request", "RS_HP_BOOT_EVENT_TIMEOUT"), ("hp_held", "RS_HP_BOOT_EVENT_TIMEOUT"),
|
||||
):
|
||||
body = compact(function_body(source, f"rs_hp_boot_wait_{name}"))
|
||||
loop = rf"for\((?:uint32_t)?timeout=0U;timeout<{bound};\+\+timeout\)"
|
||||
if len(re.findall(loop, body)) != 1 or body.count("for(") != 1:
|
||||
raise ValueError(f"HP boot {name} wait is no longer the reviewed bounded poll")
|
||||
if not body.endswith("returnfalse;") or "while(" in body or "do{" in body:
|
||||
raise ValueError(f"HP boot {name} wait termination changed")
|
||||
wait_body = compact(function_body(source, "rs_hp_boot_wait_message"))
|
||||
if ("if(message.sequence==sequence){return(message.code==code)&&(message.argument==argument);}" not in wait_body
|
||||
or "if(rs_hp_mailbox_receive_from_hp(&message)!=RS_OK){returnfalse;}" not in wait_body):
|
||||
raise ValueError("HP boot mailbox token/error matching changed")
|
||||
main, gated = split_npu_conditions(function_body(source, "main"))
|
||||
main = compact(main)
|
||||
phases = (
|
||||
"rs_hp_boot_read_header(&header);",
|
||||
"rs_hp_boot_dma_copy_entry(&header.entries[index])",
|
||||
"rs_resource_set_owner(RS_RESOURCE_GA2D,RS_RESOURCE_OWNER_HP,false)",
|
||||
"s_hp_boot_ga2d_owned_by_hp=true;",
|
||||
"rs_hp_boot_wait_ga2d_idle(RS_RESOURCE_OWNER_HP)",
|
||||
"rs_sysctrl_set_hp_release(true)",
|
||||
"rs_hp_boot_wait_message(RS_HP_BOOT_READY_EVENT,RS_HP_BOOT_READY_ARG,RS_HP_BOOT_MAILBOX_READY_SEQUENCE)",
|
||||
"message.code=RS_HP_BOOT_GA2D_START_COMMAND;",
|
||||
"rs_hp_mailbox_send_to_hp(&message)",
|
||||
"rs_hp_boot_wait_message(RS_HP_BOOT_GA2D_PASS_EVENT,RS_HP_BOOT_GA2D_PASS_ARG,RS_HP_BOOT_MAILBOX_RESULT_SEQUENCE)",
|
||||
"release_status=rs_sysctrl_set_hp_release(false);",
|
||||
"rs_hp_boot_wait_cache_request()",
|
||||
"rs_hp_boot_wait_message(RS_HP_BOOT_GA2D_CACHE_EVENT,RS_HP_BOOT_GA2D_CACHE_ARG,RS_HP_BOOT_MAILBOX_CACHE_SEQUENCE)",
|
||||
"rs_resource_acknowledge_cache_clean()",
|
||||
"rs_hp_boot_wait_hp_held()",
|
||||
"cache_clean_completed=true;",
|
||||
"if(!cache_clean_completed){rs_hp_boot_fail(UINT8_C(16));}",
|
||||
"rs_resource_set_owner(RS_RESOURCE_GA2D,RS_RESOURCE_OWNER_LP,false)",
|
||||
"s_hp_boot_ga2d_owned_by_hp=false;",
|
||||
"rs_hp_boot_wait_ga2d_idle(RS_RESOURCE_OWNER_LP)",
|
||||
"rs_test_finish(RS_TEST_PASSED,UINT8_C(0));",
|
||||
)
|
||||
cursor = 0
|
||||
for phase in phases:
|
||||
position = main.find(phase, cursor)
|
||||
if position < 0:
|
||||
raise ValueError(f"HP boot required phase or ordering changed: {phase}")
|
||||
cursor = position + len(phase)
|
||||
if (main.count("rs_test_finish(RS_TEST_PASSED,") != 1 or not main.endswith(phases[-1])
|
||||
or re.findall(r"cache_clean_completed=(true|false);", main) != ["false", "true"]
|
||||
or re.findall(r"s_hp_boot_ga2d_owned_by_hp=(true|false);", main) != ["true", "false"]):
|
||||
raise ValueError("HP boot terminal pass or cache completion changed")
|
||||
validate_cache_handoff(source, main, function_body)
|
||||
for condition, code in (
|
||||
("!" + phases[6], 11),
|
||||
(phases[8] + "!=RS_OK", 12),
|
||||
("!" + phases[9], 13),
|
||||
("!rs_hp_boot_wait_ga2d_idle(RS_RESOURCE_OWNER_HP)", 14),
|
||||
(phases[17] + "!=RS_OK", 17),
|
||||
("!rs_hp_boot_wait_ga2d_idle(RS_RESOURCE_OWNER_LP)", 17),
|
||||
):
|
||||
if f"if({condition}){{rs_hp_boot_fail(UINT8_C({code}));}}" not in main:
|
||||
raise ValueError("HP boot required completion condition changed")
|
||||
npu_condition = "||".join(f"defined({name})" for name in NPU_DEFINES)
|
||||
npu_blocks = compact("\n".join(body for condition, body in gated if condition == npu_condition))
|
||||
for owner in ("HP", "LP"):
|
||||
operation = f"rs_resource_set_owner(RS_RESOURCE_NPU,RS_RESOURCE_OWNER_{owner},false)"
|
||||
if operation not in npu_blocks or operation in main:
|
||||
raise ValueError("HP boot NPU ownership is no longer acceptance-conditional")
|
||||
fail = compact(function_body(source, "rs_hp_boot_fail"))
|
||||
guard = "if(!s_hp_boot_ga2d_owned_by_hp){(void)rs_sysctrl_set_hp_release(false);}"
|
||||
if (not fail.startswith(guard) or fail.count("rs_sysctrl_set_hp_release(") != 1
|
||||
or not fail.endswith("rs_test_finish(RS_TEST_FAILED,code);")):
|
||||
raise ValueError("HP boot failure reset ownership guard changed")
|
||||
ready_writes = ready_mailbox(root)
|
||||
constants = uint_constants(source)
|
||||
messages = []
|
||||
for title, event, argument, sequence in (
|
||||
("Initial ready", "READY_EVENT", "READY_ARG", "MAILBOX_READY_SEQUENCE"),
|
||||
("GA2D acceptance result", "GA2D_PASS_EVENT", "GA2D_PASS_ARG", "MAILBOX_RESULT_SEQUENCE"),
|
||||
("Cache-clean acknowledgement", "GA2D_CACHE_EVENT", "GA2D_CACHE_ARG", "MAILBOX_CACHE_SEQUENCE"),
|
||||
):
|
||||
messages.append({"title": title, "event": constants[f"RS_HP_BOOT_{event}"],
|
||||
"argument": constants[f"RS_HP_BOOT_{argument}"],
|
||||
"sequence": constants[f"RS_HP_BOOT_{sequence}"]})
|
||||
return {"default_poll_iterations": int(default[0]), "event_poll_multiplier": int(multiplier[0]),
|
||||
"event_poll_iterations": iterations, "npu_defines": list(NPU_DEFINES),
|
||||
"messages": messages, "ready_writes": ready_writes,
|
||||
"rootfs_ready_only": True, "terminal_requires_cache_handoff": True,
|
||||
"failure_reset_requires_no_hp_ga2d_owner": True}
|
||||
@@ -30,7 +30,7 @@ from publications.chapter_reference import collect_chapters # noqa: E402
|
||||
from publications.waveform_reference import collect_waveforms, source_paths as waveform_source_paths # noqa: E402
|
||||
from publications.system_reference import collect_system_reference, source_paths as system_source_paths # noqa: E402
|
||||
from publications.retrieval_reference import collect_retrieval # noqa: E402
|
||||
from publications.report_changes import page_ranges, repository_footer_pages # noqa: E402
|
||||
from publications.report_changes import page_ranges, repository_footer_pages, validate_change_scope # noqa: E402
|
||||
from publications.page_reference import ( # noqa: E402
|
||||
CLOSING_TITLE, PAGE_ROLES_FILE, collect_page_roles, read_page_roles,
|
||||
validate_footer_pages, validate_footer_text, validate_page_roles,
|
||||
@@ -433,6 +433,7 @@ def build(config: dict, lock: dict, executable: str, out: Path | None) -> Path:
|
||||
change_markers = [item for item in layout_items if isinstance(item, dict)
|
||||
and item.get("kind") in {"publication-change-start", "publication-change-end"}]
|
||||
# Pair/validate here; the final report also checks actual PDF pages and printed footers.
|
||||
validate_change_scope(change_markers, config)
|
||||
page_ranges(change_markers, max(item["page"] for item in change_markers))
|
||||
write_json(out / "change-markers.json", change_markers)
|
||||
manifest = {
|
||||
@@ -585,6 +586,7 @@ def check_pdf(pdf: Path, config: dict, data: dict) -> dict:
|
||||
marker_path = pdf.parent / "change-markers.json"
|
||||
if not marker_path.is_file() or manifest.get("change_markers_sha256") != sha256(marker_path):
|
||||
raise ValueError("PDF change markers missing or changed; rebuild before checking")
|
||||
validate_change_scope(read_json(marker_path), manifest["document"])
|
||||
page_ranges(read_json(marker_path), len(reader.pages))
|
||||
structure_path = pdf.parent / "document-structure.json"
|
||||
if not structure_path.is_file() or manifest.get("document_structure_sha256") != sha256(structure_path):
|
||||
|
||||
@@ -1,121 +1,126 @@
|
||||
# Mini datasheet chapter review - 2026-09-22
|
||||
# Mini datasheet chapter review - v0.5 presentation revision
|
||||
|
||||
Review snapshot: **v0.5 DRAFT**, 777 pages, IHP130 PRODUCT / 32 KiB SRAM.
|
||||
Reviewed source: `c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b`. Version/date: v0.5 DRAFT / 2026-09-22.
|
||||
Final PDF: **779 pages**; SHA-256 `a69d55cff0e9b8bb4625072ca494f33eec709871d0eb4003403a2ccc0f197c82`.
|
||||
|
||||
Hardware commit: `ca4b06d30456599a2d3fd676d832f8d4dd2f78af`. PDF SHA-256: `c8e18ba1a973ed409bf2fb3c2197cea427097c1b57760b04fb1e1c97a7ea26a6`.
|
||||
Baseline: 779 pages; SHA-256 `25257e5243e945401c8a214d4043819cf802a7fa2d22b04d83b513ce9075647b`. All **109 frozen entries / 42 IP chapters** and their anchors are retained.
|
||||
|
||||
The table covers all **109 frozen entries / 42 IP chapters**. Page numbers belong to this exact PDF. "Already covered" describes the documented subset, not complete protocol compliance or qualification. Implementation, default enable/capability, available tests, executed passes and physical evidence remain separate.
|
||||
Each row separates the retained implementation/evidence assessment from the presentation review. Key-phrase emphasis and the half-filled Functional mark do not promote any hardware or qualification claim. The six physical/board evidence gaps remain unresolved. Technical sources and tests are rebound to this build manifest; the full source lists and hashes are retained in the accompanying chapter-review JSON.
|
||||
|
||||
The recorded CI snapshot includes quality and ICS55 failures; no per-IP pass report is promoted by this review. The accompanying machine-readable `chapter-review.json` records complete source/test lists and diagram coverage. The [area review](content-review.md) and [layout/evidence standard](style.md) explain the review policy.
|
||||
CI observation: **2026-09-23T08:26:42Z**, for this exact source SHA. See the PDF evidence table and final validation report for actual statuses and local test results.
|
||||
|
||||
| # / page | Chapter | Implementation status | Document completeness / disposition | Evidence | Recommendation |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 / p. 1 | Product Brief | Current PRODUCT with executable NPU; APU default and P7 configuration conditions apply. MP3 is unsupported. | Updated in v0.5: NPU, APU profile differences, ten masters and 45 Overview labels; existing product structure retained. | Source/document review; see the separate validation record for actually executed tests. [mini.json](../../publications/datasheets/mini.json), [system-reference.json](../../publications/datasheets/system-reference.json), [product-use.typ](../../publications/datasheets/sections/product-use.typ) | Advance only with a reviewed snapshot; keep capability, default gate and qualification separate. |
|
||||
| 2 / p. 1 | Features | Current PRODUCT with executable NPU; APU default and P7 configuration conditions apply. MP3 is unsupported. | Updated in v0.5: NPU, APU profile differences, ten masters and 45 Overview labels; existing product structure retained. | Source/document review; see the separate validation record for actually executed tests. [mini.json](../../publications/datasheets/mini.json), [system-reference.json](../../publications/datasheets/system-reference.json), [product-use.typ](../../publications/datasheets/sections/product-use.typ) | Advance only with a reviewed snapshot; keep capability, default gate and qualification separate. |
|
||||
| 3 / p. 2 | Overview | Current PRODUCT with executable NPU; APU default and P7 configuration conditions apply. MP3 is unsupported. | Updated in v0.5: NPU, APU profile differences, ten masters and 45 Overview labels; existing product structure retained. | Source/document review; see the separate validation record for actually executed tests. [mini.json](../../publications/datasheets/mini.json), [system-reference.json](../../publications/datasheets/system-reference.json), [product-use.typ](../../publications/datasheets/sections/product-use.typ) | Advance only with a reviewed snapshot; keep capability, default gate and qualification separate. |
|
||||
| 4 / p. 3 | Product Configuration and Feature Availability | Current PRODUCT with executable NPU; APU default and P7 configuration conditions apply. MP3 is unsupported. | Updated in v0.5: NPU, APU profile differences, ten masters and 45 Overview labels; existing product structure retained. | Source/document review; see the separate validation record for actually executed tests. [mini.json](../../publications/datasheets/mini.json), [system-reference.json](../../publications/datasheets/system-reference.json), [product-use.typ](../../publications/datasheets/sections/product-use.typ) | Advance only with a reviewed snapshot; keep capability, default gate and qualification separate. |
|
||||
| 5 / p. 7 | Typical Applications and System Configurations | Current PRODUCT with executable NPU; APU default and P7 configuration conditions apply. MP3 is unsupported. | Updated in v0.5: NPU, APU profile differences, ten masters and 45 Overview labels; existing product structure retained. | Source/document review; see the separate validation record for actually executed tests. [mini.json](../../publications/datasheets/mini.json), [system-reference.json](../../publications/datasheets/system-reference.json), [product-use.typ](../../publications/datasheets/sections/product-use.typ) | Advance only with a reviewed snapshot; keep capability, default gate and qualification separate. |
|
||||
| 6 / p. 9 | Reading this datasheet | Document conventions, navigation and provenance; not an additional hardware capability. | Covered and retained: Existing reference complete for its declared scope; retained. | Source/document review; see the separate validation record for actually executed tests. [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
| 7 / p. 56 | System Architecture | Ten AXI data masters, seven-bit global IDs, GA2D master 8, NPU master 9 and JPEG 1R/1W admission. | Updated in v0.5: topology, access matrix, ID and credit descriptions. | Source/document review; see the separate validation record for actually executed tests. [axi4_data_crossbar.sv](../../rtl/mini/top/axi4_data_crossbar.sv), [architecture.typ](../../publications/datasheets/sections/architecture.typ), [bus-programming.typ](../../publications/datasheets/sections/bus-programming.typ) | Attach contention and recovery measurements before throughput claims. |
|
||||
| 8 / p. 56 | Introduction | Ten AXI data masters, seven-bit global IDs, GA2D master 8, NPU master 9 and JPEG 1R/1W admission. | Updated in v0.5: topology, access matrix, ID and credit descriptions. | Source/document review; see the separate validation record for actually executed tests. [axi4_data_crossbar.sv](../../rtl/mini/top/axi4_data_crossbar.sv), [architecture.typ](../../publications/datasheets/sections/architecture.typ), [bus-programming.typ](../../publications/datasheets/sections/bus-programming.typ) | Attach contention and recovery measurements before throughput claims. |
|
||||
| 9 / p. 60 | Interconnect | Ten AXI data masters, seven-bit global IDs, GA2D master 8, NPU master 9 and JPEG 1R/1W admission. | Updated in v0.5: topology, access matrix, ID and credit descriptions. | Source/document review; see the separate validation record for actually executed tests. [axi4_data_crossbar.sv](../../rtl/mini/top/axi4_data_crossbar.sv), [architecture.typ](../../publications/datasheets/sections/architecture.typ), [bus-programming.typ](../../publications/datasheets/sections/bus-programming.typ) | Attach contention and recovery measurements before throughput claims. |
|
||||
| 10 / p. 67 | Memory Attributes, Cache and DMA Coherency | Non-coherent data paths; software buffer ownership and maintenance are required. | Covered and retained: coherency rules; NPU and APU deployment refer to the same ownership and maintenance order. | Source/document review; see the separate validation record for actually executed tests. [memory-use.typ](../../publications/datasheets/sections/memory-use.typ), [system-reference.json](../../publications/datasheets/system-reference.json) | Preserve clean/invalidate and ownership order in each platform integration. |
|
||||
| 11 / p. 70 | Clock and Reset | Multiple clock domains, lifecycle gates and bridge drain/rearm paths; reference PLL disabled. | Covered and retained: clock/reset framework; NPU uses PCLK control with HP-native compute and DMA. | Source/document review; see the separate validation record for actually executed tests. [clock-programming.typ](../../publications/datasheets/sections/clock-programming.typ), [reset-summary.typ](../../publications/datasheets/sections/reset-summary.typ), [operating-states.typ](../../publications/datasheets/sections/operating-states.typ) | Qualify CDC/RDC, physical clocks and reset release on the selected implementation. |
|
||||
| 12 / p. 77 | Interrupt System | 64 LP vector positions: two local and 62 external; GA2D vector 32 / ordinal 30 / PLIC 11; NPU vector 33 / ordinal 31 / PLIC 12. | Updated in v0.5: route spaces and CSR-enabled external IRQ registration/dispatch. | Source/document review; see the separate validation record for actually executed tests. [routing-reference.typ](../../publications/datasheets/sections/routing-reference.typ), [software_reference.py](../../publications/software_reference.py), [system-reference.json](../../publications/datasheets/system-reference.json) | Preserve vector/ordinal/PLIC distinctions; no-CSR runtime remains unsupported. |
|
||||
| 13 / p. 79 | DMA Request, Interrupt and Event Routing | 64 LP vector positions: two local and 62 external; GA2D vector 32 / ordinal 30 / PLIC 11; NPU vector 33 / ordinal 31 / PLIC 12. | Updated in v0.5: route spaces and CSR-enabled external IRQ registration/dispatch. | Source/document review; see the separate validation record for actually executed tests. [routing-reference.typ](../../publications/datasheets/sections/routing-reference.typ), [software_reference.py](../../publications/software_reference.py), [system-reference.json](../../publications/datasheets/system-reference.json) | Preserve vector/ordinal/PLIC distinctions; no-CSR runtime remains unsupported. |
|
||||
| 14 / p. 82 | Multicore Operation and Resource Ownership | Ten shared resource slots with Resource ABI 1.2 and owner-routed faults/interrupts; access controls are not isolation certification. | Updated in v0.5: NPU resource 9 and ten-slot ownership; existing recovery, coexistence and authority rules retained. | Source/document review; see the separate validation record for actually executed tests. [system-management.typ](../../publications/datasheets/sections/system-management.typ), [coexistence-reference.typ](../../publications/datasheets/sections/coexistence-reference.typ), [system-reference.json](../../publications/datasheets/system-reference.json) | Validate handoff, stop/drain and concurrent workloads with exact firmware/profile reports. |
|
||||
| 15 / p. 84 | Peripheral Coexistence and Resource Conflicts | Ten shared resource slots with Resource ABI 1.2 and owner-routed faults/interrupts; access controls are not isolation certification. | Updated in v0.5: NPU resource 9 and ten-slot ownership; existing recovery, coexistence and authority rules retained. | Source/document review; see the separate validation record for actually executed tests. [system-management.typ](../../publications/datasheets/sections/system-management.typ), [coexistence-reference.typ](../../publications/datasheets/sections/coexistence-reference.typ), [system-reference.json](../../publications/datasheets/system-reference.json) | Validate handoff, stop/drain and concurrent workloads with exact firmware/profile reports. |
|
||||
| 16 / p. 86 | Security and Access-Control Boundaries | Ten shared resource slots with Resource ABI 1.2 and owner-routed faults/interrupts; access controls are not isolation certification. | Updated in v0.5: NPU resource 9 and ten-slot ownership; existing recovery, coexistence and authority rules retained. | Source/document review; see the separate validation record for actually executed tests. [system-management.typ](../../publications/datasheets/sections/system-management.typ), [coexistence-reference.typ](../../publications/datasheets/sections/coexistence-reference.typ), [system-reference.json](../../publications/datasheets/system-reference.json) | Validate handoff, stop/drain and concurrent workloads with exact firmware/profile reports. |
|
||||
| 17 / p. 87 | Debug, Diagnostics and Fault Recovery | Ten shared resource slots with Resource ABI 1.2 and owner-routed faults/interrupts; access controls are not isolation certification. | Updated in v0.5: NPU resource 9 and ten-slot ownership; existing recovery, coexistence and authority rules retained. | Source/document review; see the separate validation record for actually executed tests. [system-management.typ](../../publications/datasheets/sections/system-management.typ), [coexistence-reference.typ](../../publications/datasheets/sections/coexistence-reference.typ), [system-reference.json](../../publications/datasheets/system-reference.json) | Validate handoff, stop/drain and concurrent workloads with exact firmware/profile reports. |
|
||||
| 18 / p. 89 | Register Access and Programming Conventions | Source-defined MMIO and bounded protocol subsets; external compliance is not established. | Covered and retained: Reference already covered; current engine subset restrictions synchronized. | Source/document review; see the separate validation record for actually executed tests. [register-programming.typ](../../publications/datasheets/sections/register-programming.typ), [interface-subsets.typ](../../publications/datasheets/sections/interface-subsets.typ) | Retain width/strobe/error semantics and controller-specific limits. |
|
||||
| 19 / p. 91 | Interface Standards and Supported Subsets | Source-defined MMIO and bounded protocol subsets; external compliance is not established. | Covered and retained: Reference already covered; current engine subset restrictions synchronized. | Source/document review; see the separate validation record for actually executed tests. [register-programming.typ](../../publications/datasheets/sections/register-programming.typ), [interface-subsets.typ](../../publications/datasheets/sections/interface-subsets.typ) | Retain width/strobe/error semantics and controller-specific limits. |
|
||||
| 20 / p. 94 | Peripherals | 42 PRODUCT/MPW IP chapters; instances may share register banks. | Updated in v0.5: independent NPU immediately after APU; existing 41 IP chapters and register anchors retained. | Source/document review; see the separate validation record for actually executed tests. [chapter-index.json](../../publications/datasheets/chapter-index.json), [structure-contract.json](../../publications/datasheets/structure-contract.json), [ip-catalog.json](../../publications/datasheets/ip-catalog.json) | Keep stable register anchors and the reviewed 109-entry structure contract. |
|
||||
| 21 / p. 94 | XPI Universal Controller (XPI) | Integrated: Four chip-select slots and 16 programmable LUT sequences. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [xpi.h](../../crt/include/retrosoc/hal/xpi.h), [xpi.md](../../docs/ip/xpi.md), [xpi.c](../../publications/examples/xpi.c) | Retain the documented subset and prerequisites. External SDR SPI/QSPI flash; board-specific LUT and timing. Attach a matching scoped report before qualification. |
|
||||
| 22 / p. 114 | SPI SD Card Controller (SPISD) | Integrated: SD card SPI-mode command/data host. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [spisd.h](../../crt/include/retrosoc/hal/spisd.h), [spisd.md](../../docs/ip/spisd.md), [spisd.c](../../publications/examples/spisd.c) | Retain the documented subset and prerequisites. SPI-mode SD card; GPIO route and card supply. Attach a matching scoped report before qualification. |
|
||||
| 23 / p. 134 | SD Card Controller (SDIO0) | Integrated: Native one-bit/four-bit SDR operation. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [sdio.h](../../crt/include/retrosoc/hal/sdio.h), [sdio.md](../../docs/ip/sdio.md), [sdio.c](../../publications/examples/sdio.c) | Retain the documented subset and prerequisites. SD card and shared GPIO route. Attach a matching scoped report before qualification. |
|
||||
| 24 / p. 156 | On-Chip Memory (OCM / SRAM) | Integrated: 32 KiB in the reference profile, using eight 4 KiB banks. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [onchip_sram.h](../../crt/include/retrosoc/hal/onchip_sram.h), [onchip-sram.md](../../docs/ip/onchip-sram.md), [sram.c](../../publications/examples/sram.c) | Retain the documented subset and prerequisites. Selected technology SRAM macro; 32 KiB in the reference profile. Attach a matching scoped report before qualification. |
|
||||
| 25 / p. 163 | PSRAM Controller (PSRAM) | Integrated: Four ESP-PSRAM64H devices addressable through a 32 MiB window. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [psram.h](../../crt/include/retrosoc/hal/psram.h), [psram.md](../../docs/ip/psram.md), [psram.c](../../publications/examples/psram.c) | Retain the documented subset and prerequisites. External QPI PSRAM; mutually exclusive with OPI on shared memory pads. Attach a matching scoped report before qualification. |
|
||||
| 26 / p. 182 | OPI PSRAM / HyperBus-Style Controller | Partial: One octal DDR memory interface and one selected protocol profile. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [opipsram.h](../../crt/include/retrosoc/hal/opipsram.h), [opipsram.md](../../docs/ip/opipsram.md), [opipsram.c](../../publications/examples/opipsram.c) | Retain the documented subset and prerequisites. Compatible octal/HyperBus-style device; shared pads and board timing qualification. Attach a matching scoped report before qualification. |
|
||||
| 27 / p. 200 | SDRAM Controller (SDRAM) | Integrated: Fixed 64 MiB, x16 SDR geometry with bank/row tracking. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [sdram.h](../../crt/include/retrosoc/hal/sdram.h), [sdram.md](../../docs/ip/sdram.md), [sdram.c](../../publications/examples/sdram.c) | Retain the documented subset and prerequisites. External x16 SDR SDRAM; initialization and refresh timings. Attach a matching scoped report before qualification. |
|
||||
| 28 / p. 212 | General-Purpose Input Output (GPIO) | Integrated: 32 bidirectional GPIOs with administration and restricted user windows. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [gpio.h](../../crt/include/retrosoc/hal/gpio.h), [gpio.md](../../docs/ip/gpio.md), [gpio.c](../../publications/examples/gpio.c) | Retain the documented subset and prerequisites. Selected pad library and approved pin routing. Attach a matching scoped report before qualification. |
|
||||
| 29 / p. 229 | Direct Memory Access (DMA) | Integrated: Eight channel contexts share a 32-bit AXI master. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [dma.h](../../crt/include/retrosoc/hal/dma.h), [dma.md](../../docs/ip/dma.md), [dma.c](../../publications/examples/dma.c) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 30 / p. 245 | General-Purpose Timer (TIM0, TIM1) | Integrated: Two 32-bit general-purpose timers. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [timer.h](../../crt/include/retrosoc/hal/timer.h), [timer.md](../../docs/ip/timer.md), [timer.c](../../publications/examples/timer.c) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 31 / p. 252 | Real-Time Clock (RTC) | Integrated: 64-bit seconds and 1/256-second subsecond time. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [rtc.h](../../crt/include/retrosoc/hal/rtc.h), [rtc.c](../../publications/examples/rtc.c), [datasheet.md](../../rtl/managed/clusterip/rtc/doc/datasheet.md) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 32 / p. 266 | Watchdog (WDG) | Integrated: Independent-clock window watchdog. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [datasheet.md](../../rtl/managed/clusterip/wdg/doc/datasheet.md), [wdg_pkg.sv](../../rtl/managed/clusterip/wdg/rtl/wdg_pkg.sv), [wdg_reg.sv](../../rtl/managed/clusterip/wdg/rtl/wdg_reg.sv) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 33 / p. 276 | Pulse Width Modulation (PWM) | Integrated: Two timers, four output channels and two operators. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [pwm.h](../../crt/include/retrosoc/hal/pwm.h), [pwm.c](../../publications/examples/pwm.c), [datasheet.md](../../rtl/managed/clusterip/pwm/doc/datasheet.md) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 34 / p. 301 | Management Console (UART0) | Integrated: 64-byte TX and RX FIFOs; fractional baud-rate generator. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [uart.h](../../crt/include/retrosoc/hal/uart.h), [uart.md](../../docs/ip/uart.md), [uart.c](../../publications/examples/uart.c) | Retain the documented subset and prerequisites. Management serial connection; optional DMA/flow-control routing. Attach a matching scoped report before qualification. |
|
||||
| 35 / p. 314 | Application Console (UART1) | Integrated: 64-byte TX and RX FIFOs; fractional baud-rate generator. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [README.md](../../app/ports/linux/README.md), [retrosoc_hp.dts](../../app/ports/linux/linux/retrosoc_hp.dts), [uart.h](../../crt/include/retrosoc/hal/uart.h) | Retain the documented subset and prerequisites. Dedicated console TX/RX; no connected DMA or RTS/CTS. Attach a matching scoped report before qualification. |
|
||||
| 36 / p. 316 | Inter-Integrated Circuit (I2C) | Integrated: Two controller instances with 7-bit and 10-bit addressing. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [i2c.h](../../crt/include/retrosoc/hal/i2c.h), [i2c.md](../../docs/ip/i2c.md), [i2c.c](../../publications/examples/i2c.c) | Retain the documented subset and prerequisites. External bus pull-ups and compatible target voltages. Attach a matching scoped report before qualification. |
|
||||
| 37 / p. 330 | WS2812 LED Interface | Integrated: 24-bit GRB transmission on one GPIO alternate function. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [ws2812.h](../../crt/include/retrosoc/hal/ws2812.h), [ws2812.md](../../docs/ip/ws2812.md), [ws2812.c](../../publications/examples/ws2812.c) | Retain the documented subset and prerequisites. Compatible LED chain and approved level/supply interface. Attach a matching scoped report before qualification. |
|
||||
| 38 / p. 339 | Personal System/2 (PS2) | Integrated: Bidirectional open-drain host interface. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [ps2.h](../../crt/include/retrosoc/hal/ps2.h), [ps2.c](../../publications/examples/ps2.c), [datasheet.md](../../rtl/managed/clusterip/ps2/doc/datasheet.md) | Retain the documented subset and prerequisites. Open-drain interface and board pull-ups. Attach a matching scoped report before qualification. |
|
||||
| 39 / p. 349 | SDIO Controller (SDIO1) | Integrated: Native one-bit/four-bit SDR operation. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [sdio.h](../../crt/include/retrosoc/hal/sdio.h), [sdio.md](../../docs/ip/sdio.md), [sdio.c](../../publications/examples/sdio.c) | Retain the documented subset and prerequisites. SD card and dedicated pads; generic FPGA mapping pending. Attach a matching scoped report before qualification. |
|
||||
| 40 / p. 353 | USB 2.0 Dual-Role Controller | Integrated: Dual-role digital controller with external 8-bit ULPI PHY. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [usb2.h](../../crt/include/retrosoc/hal/usb2.h), [usb2.md](../../docs/ip/usb2.md), [usb2.c](../../publications/examples/usb2.c) | Retain the documented subset and prerequisites. External ULPI PHY, 60 MHz interface clock, VBUS/role circuitry. Attach a matching scoped report before qualification. |
|
||||
| 41 / p. 386 | Architecture Information (ARCHINFO) | Integrated: Read-only identity, configuration and topology discovery. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [archinfo.c](../../publications/examples/archinfo.c), [datasheet.md](../../rtl/managed/clusterip/archinfo/doc/datasheet.md), [archinfo_reg.sv](../../rtl/managed/clusterip/archinfo/rtl/archinfo_reg.sv) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 42 / p. 395 | System Controller (SYSCTRL) | Integrated: Root-managed configuration, HP lifecycle and clock requests. | Updated in v0.5: current implementation details and generated register fields; existing reference structure retained. | Tests available; 0 matching per-IP pass reports attached. [sysctrl.h](../../crt/include/retrosoc/hal/sysctrl.h), [sysctrl.md](../../docs/ip/sysctrl.md), [sysctrl.c](../../publications/examples/sysctrl.c) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 43 / p. 416 | Reset Clock Unit (RCU) | Integrated: AON-controlled requests and clock/reset policy. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [clock.h](../../crt/include/retrosoc/hal/clock.h), [pll-clock-control.md](../../docs/pll-clock-control.md), [rcu.c](../../publications/examples/rcu.c) | Retain the documented subset and prerequisites. Reference PLL disabled; any physical PLL/backend needs separate qualification. Attach a matching scoped report before qualification. |
|
||||
| 44 / p. 418 | Management Local Interrupts (CLINT) | Integrated: Per-hart software interrupts and 64-bit timer compare. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [clint.h](../../crt/include/retrosoc/hal/clint.h), [clint.md](../../docs/ip/clint.md), [clint.c](../../publications/examples/clint.c) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 45 / p. 423 | HP Local Interrupt Controller (ACLINT) | Integrated: Two addressable hart slots; HP consumes slot 1. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [retrosoc_hp.dts](../../app/ports/linux/linux/retrosoc_hp.dts), [platform.c](../../app/ports/linux/opensbi/retrosoc_hp/platform.c), [clint.md](../../docs/ip/clint.md) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 46 / p. 427 | HP Platform-Level Interrupt Controller (PLIC) | Integrated: 32 source IDs, with source 0 reserved. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [retrosoc_hp.dts](../../app/ports/linux/linux/retrosoc_hp.dts), [platform.c](../../app/ports/linux/opensbi/retrosoc_hp/platform.c), [hp-platform.md](../../docs/ip/hp-platform.md) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 47 / p. 431 | LP/HP Mailbox | Integrated: Separate LP-to-HP and HP-to-LP payload banks. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [README.md](../../app/ports/linux/README.md), [retrosoc_hp.dts](../../app/ports/linux/linux/retrosoc_hp.dts), [hp_mailbox.h](../../crt/include/retrosoc/hal/hp_mailbox.h) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 48 / p. 439 | Resource Controller | Partial: Ten independently managed shared resources; resource 8 owns the active P5 GA2D direct 2D engine and IRQ route. | Updated in v0.5: current implementation details and generated register fields; existing reference structure retained. | Tests available; 0 matching per-IP pass reports attached. [resource.h](../../crt/include/retrosoc/hal/resource.h), [resource-controller.md](../../docs/ip/resource-controller.md), [resource.c](../../publications/examples/resource.c) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 49 / p. 446 | Fabric Monitor | Integrated: Ten master and six target observation banks; bank 8 observes active P5 GA2D direct 2D traffic. | Updated in v0.5: current implementation details and generated register fields; existing reference structure retained. | Tests available; 0 matching per-IP pass reports attached. [fabric_monitor.h](../../crt/include/retrosoc/hal/fabric_monitor.h), [fabric-monitor.md](../../docs/ip/fabric-monitor.md), [monitor.c](../../publications/examples/monitor.c) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 50 / p. 460 | Inter-Integrated Circuit Sound (I2S) | Integrated: Stereo master TX/RX with independent audio clock. | Covered and retained: formats, clocks, FIFOs and route/flush cooperation; APU RX use remains conditional on the selected P7 profile. | Tests available; 0 matching per-IP pass reports attached. [i2s.h](../../crt/include/retrosoc/hal/i2s.h), [i2s.md](../../docs/ip/i2s.md), [i2s.c](../../publications/examples/i2s.c) | Retain the documented subset and prerequisites. External audio clock and codec; stereo master operation. Attach a matching scoped report before qualification. |
|
||||
| 51 / p. 469 | Digital Video Port (DVP) | Integrated: 8-bit parallel RGB565/YUV422 capture. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [dvp.h](../../crt/include/retrosoc/hal/dvp.h), [dvp.md](../../docs/ip/dvp.md), [dvp.c](../../publications/examples/dvp.c) | Retain the documented subset and prerequisites. Parallel camera, sensor configuration and pixel clock. Attach a matching scoped report before qualification. |
|
||||
| 52 / p. 480 | JPEG Encoder / Decoder | Partial: 8-bit Baseline Sequential JPEG encode or decode. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [jpeg.h](../../crt/include/retrosoc/hal/jpeg.h), [jpeg.md](../../docs/ip/jpeg.md), [jpeg.c](../../publications/examples/jpeg.c) | Retain the documented subset and prerequisites. Native slot-6 payload admission has one normal read and one normal write credit at class 8; standalone codec behavior and end-to-end system qualification remain separate scopes. Attach a matching scoped report before qualification. |
|
||||
| 53 / p. 504 | 2D Graphics Accelerator (GA2D) | Integrated: P5 direct single-job FILL, COPY, CONVERT, opaque alpha BLEND, A8 masks and exact background/destination in-place composition. | Updated in v0.5: Updated P6 coverage and performance semantics; covered P5 operations, formats, rounding, bounds, ownership, lifecycle and HAL retained. | Tests available; 0 matching per-IP pass reports attached. [ga2d.md](../../docs/ip/ga2d.md), [apb4_ga2d.sv](../../rtl/ip/multimedia/apb4_ga2d.sv), [ga2d_core.sv](../../rtl/ip/multimedia/ga2d_core.sv) | P6 test sources and dated records already exist. Attach current-commit full-product contention, workload throughput and physical closure reports; preserve the documented subset. |
|
||||
| 54 / p. 524 | Audio Processing Unit (APU, partial) | Partial: WAV/FLAC image and job/stream execution; fixed KWS is enabled only in the P7 acceptance configuration. MP3 remains unsupported. | Updated in v0.5: Updated default/P7 capability 0x1BD/0x1FD and digest, quiesced loading, LP-to-HP ownership/cache transfer and smoke/full/concurrent acceptance; APUMC and job ABI retained. | Tests available; 0 matching per-IP pass reports attached. [Makefile](../../Makefile), [main.c](../../app/apps/apu_release/main.c), [main.c](../../app/ports/hp-apu/main.c) | Keep MP3 unsupported; use the explicit P7 configuration for fixed KWS. Attach full corpus and concurrent/lifecycle reports; describe inferred KWS storage until macros are implemented. |
|
||||
| 55 / p. 570 | Neural Processing Unit (NPU) | Integrated: Eight INT8 operators with native HP descriptor/DMA execution and private local SRAM. | Updated in v0.5: added complete NPU chapter, eight implemented operators, 64 dense/8 depthwise MACs, 64 KiB private banks, two accumulators, descriptor/parameters, 8-beat DMA, lifecycle waveforms, HAL and compiler boundaries. | Tests available; 0 matching per-IP pass reports attached. [npu.h](../../crt/include/retrosoc/hal/npu.h), [npu_regs.h](../../crt/include/retrosoc/hal/npu_regs.h), [npu.c](../../crt/src/hal/npu.c) | Attach matching KWS/VWW raw reports including CPU preprocessing/Softmax and cache costs. Keep unknown-operator rejection, INT32 limits, abort/drain and private SRAM boundaries explicit; no arbitrary TFLite or certification claim. |
|
||||
| 56 / p. 595 | Crypto Controller | Integrated: AES-128/192/256, SHA-224/256 and raw RSA-2048. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Tests available; 0 matching per-IP pass reports attached. [crypto.h](../../crt/include/retrosoc/hal/crypto.h), [crypto.md](../../docs/ip/crypto.md), [crypto.c](../../publications/examples/crypto.c) | Retain the documented subset and prerequisites. LP-controlled buffers and key lifecycle; no secure key-store claim. Attach a matching scoped report before qualification. |
|
||||
| 57 / p. 617 | Cyclic Redundancy Check (CRC) | Integrated: Programmable 7-, 8-, 16- or 32-bit CRC. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [crc.h](../../crt/include/retrosoc/hal/crc.h), [crc.c](../../publications/examples/crc.c), [datasheet.md](../../rtl/managed/clusterip/crc/doc/datasheet.md) | Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 58 / p. 624 | Random Number Generator (RNG) | Partial: Entropy-source qualification, FIFO and continuous health checks. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [rng.h](../../crt/include/retrosoc/hal/rng.h), [rng.c](../../publications/examples/rng.c), [datasheet.md](../../rtl/managed/clusterip/rng/doc/datasheet.md) | Retain the documented subset and prerequisites. Entropy-source qualification absent; deterministic integration source. Attach a matching scoped report before qualification. |
|
||||
| 59 / p. 633 | Low-Bandwidth Extension (EXT-L) | Integrated: Fixed APB4 control and one interrupt. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [extension.h](../../crt/include/retrosoc/hal/extension.h), [extensions.md](../../docs/ip/extensions.md), [ext-l.c](../../publications/examples/ext-l.c) | Retain the documented subset and prerequisites. Fixed external APB target and lifecycle contract. Attach a matching scoped report before qualification. |
|
||||
| 60 / p. 635 | High-Bandwidth Extension (EXT-H) | Integrated: Fixed EXT-H control, ownership, bounds and lifecycle. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [extension.h](../../crt/include/retrosoc/hal/extension.h), [extensions.md](../../docs/ip/extensions.md), [extensions.c](../../publications/examples/extensions.c) | Retain the documented subset and prerequisites. Bounded external AXI master and ACL configuration. Attach a matching scoped report before qualification. |
|
||||
| 61 / p. 644 | Packaging | No matching characterized package, electrical, thermal or timing specification. | Evidence needed: Document framework covered; numerical specifications remain incomplete and explicit. | Source/document review; see the separate validation record for actually executed tests. [pins.typ](../../publications/datasheets/sections/pins.typ), [electrical-reference.typ](../../publications/datasheets/sections/electrical-reference.typ) | Supply package/board/corner/instrument evidence before publishing ratings. |
|
||||
| 62 / p. 653 | Electrical and Timing Specifications | No matching characterized package, electrical, thermal or timing specification. | Evidence needed: Document framework covered; numerical specifications remain incomplete and explicit. | Source/document review; see the separate validation record for actually executed tests. [pins.typ](../../publications/datasheets/sections/pins.typ), [electrical-reference.typ](../../publications/datasheets/sections/electrical-reference.typ) | Supply package/board/corner/instrument evidence before publishing ratings. |
|
||||
| 63 / p. 656 | Software | Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. | Covered and retained: Existing startup, ownership, bundle and diagnostics reference retained; NPU deployment, APU P7 LP/HP acceptance and GA2D schema 3 semantics refreshed. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py) | Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 64 / p. 656 | Boot Configuration, Initialization and Recovery | Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. | Covered and retained: Existing startup, ownership, bundle and diagnostics reference retained; NPU deployment, APU P7 LP/HP acceptance and GA2D schema 3 semantics refreshed. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py) | Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 65 / p. 663 | Programming, Image Maintenance and Service Procedures | Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. | Covered and retained: Existing startup, ownership, bundle and diagnostics reference retained; NPU deployment, APU P7 LP/HP acceptance and GA2D schema 3 semantics refreshed. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py) | Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 66 / p. 665 | Runtime, SDK and Shell | Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. | Covered and retained: Existing startup, ownership, bundle and diagnostics reference retained; NPU deployment, APU P7 LP/HP acceptance and GA2D schema 3 semantics refreshed. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py) | Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 67 / p. 673 | Applications | Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. | Covered and retained: Existing startup, ownership, bundle and diagnostics reference retained; NPU deployment, APU P7 LP/HP acceptance and GA2D schema 3 semantics refreshed. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py) | Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 68 / p. 676 | Linux and Driver Status | Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. | Covered and retained: Existing startup, ownership, bundle and diagnostics reference retained; NPU deployment, APU P7 LP/HP acceptance and GA2D schema 3 semantics refreshed. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py) | Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 69 / p. 678 | Software Support and Validated Configurations | Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. | Covered and retained: Existing startup, ownership, bundle and diagnostics reference retained; NPU deployment, APU P7 LP/HP acceptance and GA2D schema 3 semantics refreshed. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py) | Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 70 / p. 682 | Implementation | Reproducible source and test flows exist; local execution and release qualification have separate scopes. | Covered and retained: Existing integration and simulation guide retained. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [regress.py](../../scripts/regress.py), [engineering.md](../../docs/engineering.md) | Run the selected committed profile with required tools and archive machine-readable verdicts. |
|
||||
| 71 / p. 682 | SoC Integration | Reproducible source and test flows exist; local execution and release qualification have separate scopes. | Covered and retained: Existing integration and simulation guide retained. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [regress.py](../../scripts/regress.py), [engineering.md](../../docs/engineering.md) | Run the selected committed profile with required tools and archive machine-readable verdicts. |
|
||||
| 72 / p. 683 | RTL Simulation | Reproducible source and test flows exist; local execution and release qualification have separate scopes. | Covered and retained: Existing integration and simulation guide retained. | Source/document review; see the separate validation record for actually executed tests. [software.typ](../../publications/datasheets/sections/software.typ), [regress.py](../../scripts/regress.py), [engineering.md](../../docs/engineering.md) | Run the selected committed profile with required tools and archive machine-readable verdicts. |
|
||||
| 73 / p. 684 | FPGA Verification | Board constraints/integration inputs exist; complete board acceptance evidence is not attached. | Evidence needed: Framework retained; missing board and route evidence remains explicit. | Source/document review; see the separate validation record for actually executed tests. [README.md](../../fpga/README.md), [software.typ](../../publications/datasheets/sections/software.typ), [electrical-reference.typ](../../publications/datasheets/sections/electrical-reference.typ) | Provide approved pin routes, board revision and external-device acceptance logs. |
|
||||
| 74 / p. 685 | Physical Design | Physical flow inputs exist; no matching synthesis/netlist/STA/signoff report is attached. | Evidence needed: Framework retained; no new PPA or physical pass claim. | Source/document review; see the separate validation record for actually executed tests. [README.md](../../physical/README.md), [software.typ](../../publications/datasheets/sections/software.typ), [release-verification.typ](../../publications/datasheets/sections/release-verification.typ) | Archive exact PDK/library/corner/constraints and complete physical reports. |
|
||||
| 75 / p. 686 | PCB Hardware | Board constraints/integration inputs exist; complete board acceptance evidence is not attached. | Evidence needed: Framework retained; missing board and route evidence remains explicit. | Source/document review; see the separate validation record for actually executed tests. [README.md](../../fpga/README.md), [software.typ](../../publications/datasheets/sections/software.typ), [electrical-reference.typ](../../publications/datasheets/sections/electrical-reference.typ) | Provide approved pin routes, board revision and external-device acceptance logs. |
|
||||
| 76 / p. 687 | Appendix: MPW Compatibility | Separate selectable MPW core/user-IP profile; not the fixed PRODUCT integration. | Covered and retained: Existing compatibility appendix retained. | Source/document review; see the separate validation record for actually executed tests. [mini-mpw.mk](../../configs/cluster/mini-mpw.mk), [appendices.typ](../../publications/datasheets/sections/appendices.typ), [README.md](../../rtl/mini/integration/README.md) | Keep MPW selection, reset and GPIO ownership separate from PRODUCT claims. |
|
||||
| 77 / p. 687 | SoC Template | Separate selectable MPW core/user-IP profile; not the fixed PRODUCT integration. | Covered and retained: Existing compatibility appendix retained. | Source/document review; see the separate validation record for actually executed tests. [mini-mpw.mk](../../configs/cluster/mini-mpw.mk), [appendices.typ](../../publications/datasheets/sections/appendices.typ), [README.md](../../rtl/mini/integration/README.md) | Keep MPW selection, reset and GPIO ownership separate from PRODUCT claims. |
|
||||
| 78 / p. 689 | MPW User Timer | MPW only: MPW-selectable timer and divider. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [user_ip.h](../../crt/include/retrosoc/hal/user_ip.h), [user-ip.md](../../docs/ip/user-ip.md), [mpw_timer.c](../../publications/examples/mpw_timer.c) | Retain the documented subset and prerequisites. MPW profile, selected user-IP manifest and pad ownership. Attach a matching scoped report before qualification. |
|
||||
| 79 / p. 692 | MPW User GPIO | MPW only: MPW-selectable user GPIO data and enables. | Covered and retained: function, protocol, registers and software; retained and regenerated from current sources. | Source reviewed; 0 matching per-IP pass reports attached. [user_ip.h](../../crt/include/retrosoc/hal/user_ip.h), [user-ip.md](../../docs/ip/user-ip.md), [mpw_gpio.c](../../publications/examples/mpw_gpio.c) | Retain the documented subset and prerequisites. MPW profile, selected user-IP manifest and pad ownership. Attach a matching scoped report before qualification. |
|
||||
| 80 / p. 695 | Appendix: Product Direction | Future family positioning and release milestones are not implemented product commitments. | Covered and retained: Roadmap context retained; no new schedule or derivative claim. | Source/document review; see the separate validation record for actually executed tests. [soc-family-positioning.md](../../docs/soc-family-positioning.md), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Publish commitments only after a reviewed implementation and release decision. |
|
||||
| 81 / p. 695 | Product Series | Future family positioning and release milestones are not implemented product commitments. | Covered and retained: Roadmap context retained; no new schedule or derivative claim. | Source/document review; see the separate validation record for actually executed tests. [soc-family-positioning.md](../../docs/soc-family-positioning.md), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Publish commitments only after a reviewed implementation and release decision. |
|
||||
| 82 / p. 696 | Roadmap | Future family positioning and release milestones are not implemented product commitments. | Covered and retained: Roadmap context retained; no new schedule or derivative claim. | Source/document review; see the separate validation record for actually executed tests. [soc-family-positioning.md](../../docs/soc-family-positioning.md), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Publish commitments only after a reviewed implementation and release decision. |
|
||||
| 83 / p. 697 | Technical Report | Commit-bound CI sampled at 2026-09-22T06:00:43Z: four workflow successes; quality and ICS55 failures. Quality formatting passed; fixtures failed. | Updated in v0.5: independent status and nullable conclusion, final UTC refresh and historical GA2D/NPU/APU evidence boundaries; no per-IP pass is promoted. | Source/document review; see the separate validation record for actually executed tests. [system-reference.json](../../publications/datasheets/system-reference.json), [release-verification.typ](../../publications/datasheets/sections/release-verification.typ), [dev_reference.py](../../publications/dev_reference.py) | Resolve failing prerequisites and attach scoped reports before broader qualification. |
|
||||
| 84 / p. 697 | Release Verification Summary | Commit-bound CI sampled at 2026-09-22T06:00:43Z: four workflow successes; quality and ICS55 failures. Quality formatting passed; fixtures failed. | Updated in v0.5: independent status and nullable conclusion, final UTC refresh and historical GA2D/NPU/APU evidence boundaries; no per-IP pass is promoted. | Source/document review; see the separate validation record for actually executed tests. [system-reference.json](../../publications/datasheets/system-reference.json), [release-verification.typ](../../publications/datasheets/sections/release-verification.typ), [dev_reference.py](../../publications/dev_reference.py) | Resolve failing prerequisites and attach scoped reports before broader qualification. |
|
||||
| 85 / p. 700 | Shuttle and Qualification Evidence | No matching silicon/shuttle/package characterization report supplied. | Evidence needed: Evidence checklist covered; measured values/photos remain unavailable. | Source/document review; see the separate validation record for actually executed tests. [appendices.typ](../../publications/datasheets/sections/appendices.typ), [release-verification.typ](../../publications/datasheets/sections/release-verification.typ) | Supply lot, die revision, package, setup and test conditions with each measurement. |
|
||||
| 86 / p. 701 | Performance and Power Characterization | Benchmark counters and workload definitions exist; no matching product performance/power result. | Updated in v0.5: GA2D five-operation/size/stride matrix and schema 3 counters; APU smoke/full/concurrent gates and NPU full-model boundaries. Existing methods retained. | Source/document review; see the separate validation record for actually executed tests. [performance-reference.typ](../../publications/datasheets/sections/performance-reference.typ), [system-reference.json](../../publications/datasheets/system-reference.json) | Measure CPU/engine clocks, bytes/pixels/jobs, memory traffic and power under stated conditions. |
|
||||
| 87 / p. 703 | Known Limitations and Revision Compatibility | Prototype maturity unchanged: MP3 unsupported, APU KWS requires P7, and NPU subset/model/corpus and physical evidence limits remain. | Updated in v0.5: Updated limitations and revision compatibility; implementation presence is distinct from qualification. | Source/document review; see the separate validation record for actually executed tests. [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [system-reference.json](../../publications/datasheets/system-reference.json) | Retire a limitation only with matching implementation and reviewed evidence. |
|
||||
| 88 / p. 703 | Implementation and Qualification Limitations | Prototype maturity unchanged: MP3 unsupported, APU KWS requires P7, and NPU subset/model/corpus and physical evidence limits remain. | Updated in v0.5: Updated limitations and revision compatibility; implementation presence is distinct from qualification. | Source/document review; see the separate validation record for actually executed tests. [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [system-reference.json](../../publications/datasheets/system-reference.json) | Retire a limitation only with matching implementation and reviewed evidence. |
|
||||
| 89 / p. 708 | Revision Identification and Compatibility | Prototype maturity unchanged: MP3 unsupported, APU KWS requires P7, and NPU subset/model/corpus and physical evidence limits remain. | Updated in v0.5: Updated limitations and revision compatibility; implementation presence is distinct from qualification. | Source/document review; see the separate validation record for actually executed tests. [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [system-reference.json](../../publications/datasheets/system-reference.json) | Retire a limitation only with matching implementation and reviewed evidence. |
|
||||
| 90 / p. 709 | Appendix: Software Memory and Buffer Requirements | Static linker and worked-buffer accounting; examples are not measured peak runtime usage. | Covered and retained: Existing memory accounting and examples retained. | Source/document review; see the separate validation record for actually executed tests. [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [memory-use.typ](../../publications/datasheets/sections/memory-use.typ), [README.md](../../crt/README.md) | Measure stack, heap-free working sets and application buffers on the actual workload. |
|
||||
| 91 / p. 709 | Linker Layout and Runtime Accounting | Static linker and worked-buffer accounting; examples are not measured peak runtime usage. | Covered and retained: Existing memory accounting and examples retained. | Source/document review; see the separate validation record for actually executed tests. [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [memory-use.typ](../../publications/datasheets/sections/memory-use.typ), [README.md](../../crt/README.md) | Measure stack, heap-free working sets and application buffers on the actual workload. |
|
||||
| 92 / p. 710 | Worked Buffer Budgets | Static linker and worked-buffer accounting; examples are not measured peak runtime usage. | Covered and retained: Existing memory accounting and examples retained. | Source/document review; see the separate validation record for actually executed tests. [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [memory-use.typ](../../publications/datasheets/sections/memory-use.typ), [README.md](../../crt/README.md) | Measure stack, heap-free working sets and application buffers on the actual workload. |
|
||||
| 93 / p. 712 | Appendix: Terminology, Notation and Document Map | Document conventions, navigation and provenance; not an additional hardware capability. | Covered and retained: Existing reference complete for its declared scope; retained. | Source/document review; see the separate validation record for actually executed tests. [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
| 94 / p. 712 | Terminology and Units | Document conventions, navigation and provenance; not an additional hardware capability. | Covered and retained: Existing reference complete for its declared scope; retained. | Source/document review; see the separate validation record for actually executed tests. [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
| 95 / p. 713 | Reading Numbers and Status | Document conventions, navigation and provenance; not an additional hardware capability. | Covered and retained: Existing reference complete for its declared scope; retained. | Source/document review; see the separate validation record for actually executed tests. [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
| 96 / p. 714 | Document and Evidence Navigation | Document conventions, navigation and provenance; not an additional hardware capability. | Covered and retained: Existing reference complete for its declared scope; retained. | Source/document review; see the separate validation record for actually executed tests. [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
| 97 / p. 715 | Appendix: Global Register and Address Index | Generated register/address inventory with stable per-register destinations. | Covered and retained: Existing generator reused; current NPU and APU definitions propagated. | Source/document review; see the separate validation record for actually executed tests. [register-index.typ](../../publications/datasheets/sections/register-index.typ), [register-annotations.json](../../publications/datasheets/register-annotations.json), [ip-catalog.json](../../publications/datasheets/ip-catalog.json) | Keep C/RTL parity and source-derived anchors; do not hand-maintain duplicate register lists. |
|
||||
| 98 / p. 715 | PRODUCT Register Instances | Generated register/address inventory with stable per-register destinations. | Covered and retained: Existing generator reused; current NPU and APU definitions propagated. | Source/document review; see the separate validation record for actually executed tests. [register-index.typ](../../publications/datasheets/sections/register-index.typ), [register-annotations.json](../../publications/datasheets/register-annotations.json), [ip-catalog.json](../../publications/datasheets/ip-catalog.json) | Keep C/RTL parity and source-derived anchors; do not hand-maintain duplicate register lists. |
|
||||
| 99 / p. 756 | MPW Conditional Register Instances | Generated register/address inventory with stable per-register destinations. | Covered and retained: Existing generator reused; current NPU and APU definitions propagated. | Source/document review; see the separate validation record for actually executed tests. [register-index.typ](../../publications/datasheets/sections/register-index.typ), [register-annotations.json](../../publications/datasheets/register-annotations.json), [ip-catalog.json](../../publications/datasheets/ip-catalog.json) | Keep C/RTL parity and source-derived anchors; do not hand-maintain duplicate register lists. |
|
||||
| 100 / p. 757 | Appendix: Fault and Status Code Reference | Source-defined diagnostic namespaces, application returns and sticky TEST_STATUS verdicts. | Covered and retained: Existing reference retained and generated current-source records reused. | Source/document review; see the separate validation record for actually executed tests. [fault-reference.typ](../../publications/datasheets/sections/fault-reference.typ), [application-diagnostics.typ](../../publications/datasheets/sections/application-diagnostics.typ), [engineering.md](../../docs/engineering.md) | Distinguish software returns from hardware completion and log presence from test pass. |
|
||||
| 101 / p. 757 | Diagnostic Code Namespaces | Source-defined diagnostic namespaces, application returns and sticky TEST_STATUS verdicts. | Covered and retained: Existing reference retained and generated current-source records reused. | Source/document review; see the separate validation record for actually executed tests. [fault-reference.typ](../../publications/datasheets/sections/fault-reference.typ), [application-diagnostics.typ](../../publications/datasheets/sections/application-diagnostics.typ), [engineering.md](../../docs/engineering.md) | Distinguish software returns from hardware completion and log presence from test pass. |
|
||||
| 102 / p. 763 | Status Registers and Capture Points | Source-defined diagnostic namespaces, application returns and sticky TEST_STATUS verdicts. | Covered and retained: Existing reference retained and generated current-source records reused. | Source/document review; see the separate validation record for actually executed tests. [fault-reference.typ](../../publications/datasheets/sections/fault-reference.typ), [application-diagnostics.typ](../../publications/datasheets/sections/application-diagnostics.typ), [engineering.md](../../docs/engineering.md) | Distinguish software returns from hardware completion and log presence from test pass. |
|
||||
| 103 / p. 769 | Firmware Application Results | Source-defined diagnostic namespaces, application returns and sticky TEST_STATUS verdicts. | Covered and retained: Existing reference retained and generated current-source records reused. | Source/document review; see the separate validation record for actually executed tests. [fault-reference.typ](../../publications/datasheets/sections/fault-reference.typ), [application-diagnostics.typ](../../publications/datasheets/sections/application-diagnostics.typ), [engineering.md](../../docs/engineering.md) | Distinguish software returns from hardware completion and log presence from test pass. |
|
||||
| 104 / p. 772 | Automated Completion and Simulator Verdicts | Source-defined diagnostic namespaces, application returns and sticky TEST_STATUS verdicts. | Covered and retained: Existing reference retained and generated current-source records reused. | Source/document review; see the separate validation record for actually executed tests. [fault-reference.typ](../../publications/datasheets/sections/fault-reference.typ), [application-diagnostics.typ](../../publications/datasheets/sections/application-diagnostics.typ), [engineering.md](../../docs/engineering.md) | Distinguish software returns from hardware completion and log presence from test pass. |
|
||||
| 105 / p. 773 | Document Control | Publication v0.5 DRAFT bound to reviewed dev commit; publication edits may postdate hardware snapshot. | Updated in v0.5: 2026-09-22 date, source closure, revision entry and 42-IP/109-entry evidence. | Source/document review; see the separate validation record for actually executed tests. [mini.json](../../publications/datasheets/mini.json), [appendices.typ](../../publications/datasheets/sections/appendices.typ), [README.md](../../publications/README.md) | Ship matching manifest, PDF digest, review and validation records together. |
|
||||
| 106 / p. 773 | Revision History | Publication v0.5 DRAFT bound to reviewed dev commit; publication edits may postdate hardware snapshot. | Updated in v0.5: 2026-09-22 date, source closure, revision entry and 42-IP/109-entry evidence. | Source/document review; see the separate validation record for actually executed tests. [mini.json](../../publications/datasheets/mini.json), [appendices.typ](../../publications/datasheets/sections/appendices.typ), [README.md](../../publications/README.md) | Ship matching manifest, PDF digest, review and validation records together. |
|
||||
| 107 / p. 774 | Sources and Reproducibility | Publication v0.5 DRAFT bound to reviewed dev commit; publication edits may postdate hardware snapshot. | Updated in v0.5: 2026-09-22 date, source closure, revision entry and 42-IP/109-entry evidence. | Source/document review; see the separate validation record for actually executed tests. [mini.json](../../publications/datasheets/mini.json), [appendices.typ](../../publications/datasheets/sections/appendices.typ), [README.md](../../publications/README.md) | Ship matching manifest, PDF digest, review and validation records together. |
|
||||
| 108 / p. 775 | License | Document conventions, navigation and provenance; not an additional hardware capability. | Covered and retained: Existing reference complete for its declared scope; retained. | Source/document review; see the separate validation record for actually executed tests. [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
| 109 / p. 776 | Document Status and Contact | Document conventions, navigation and provenance; not an additional hardware capability. | Covered and retained: Existing reference complete for its declared scope; retained. | Source/document review; see the separate validation record for actually executed tests. [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ) | Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
See [content review](content-review.md) for the bounded commercial comparison, [layout/content rules](style.md) for emphasis and badge geometry, and [publication guide](../README.md) for reproducible build instructions.
|
||||
|
||||
| # | Chapter / final pages | Technical disposition and evidence | Presentation review | Basis and recommendation |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | Product Brief / 1 | Covered and retained. Existing PRODUCT integration retained; APU image/default/P7 availability and the declared source identity are explicitly scoped. Source/document review; test availability is not an executed pass. | Cover contact and partial Functional mark updated; short feature phrases emphasized; no qualification promoted. | [mini.json](../../publications/datasheets/mini.json), [overview.typ](../../publications/datasheets/sections/overview.typ), [product-use.typ](../../publications/datasheets/sections/product-use.typ). Match capabilities to the exact profile and selected runtime; do not treat initial ready as delivery of the later Linux acceptance service. |
|
||||
| 2 | Features / 1 | Covered and retained. Existing PRODUCT integration retained; APU image/default/P7 availability and the declared source identity are explicitly scoped. Source/document review; test availability is not an executed pass. | Cover contact and partial Functional mark updated; short feature phrases emphasized; no qualification promoted. | [mini.json](../../publications/datasheets/mini.json), [overview.typ](../../publications/datasheets/sections/overview.typ), [product-use.typ](../../publications/datasheets/sections/product-use.typ). Match capabilities to the exact profile and selected runtime; do not treat initial ready as delivery of the later Linux acceptance service. |
|
||||
| 3 | Overview / 2 | Covered and retained. Existing PRODUCT integration retained; APU image/default/P7 availability and the declared source identity are explicitly scoped. Source/document review; test availability is not an executed pass. | Cover contact and partial Functional mark updated; short feature phrases emphasized; no qualification promoted. | [mini.json](../../publications/datasheets/mini.json), [overview.typ](../../publications/datasheets/sections/overview.typ), [product-use.typ](../../publications/datasheets/sections/product-use.typ). Match capabilities to the exact profile and selected runtime; do not treat initial ready as delivery of the later Linux acceptance service. |
|
||||
| 4 | Product Configuration and Feature Availability / 3 | Covered and retained. Existing PRODUCT integration retained; APU image/default/P7 availability and the declared source identity are explicitly scoped. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [mini.json](../../publications/datasheets/mini.json), [overview.typ](../../publications/datasheets/sections/overview.typ), [product-use.typ](../../publications/datasheets/sections/product-use.typ). Match capabilities to the exact profile and selected runtime; do not treat initial ready as delivery of the later Linux acceptance service. |
|
||||
| 5 | Typical Applications and System Configurations / 7 | Covered and retained. Existing PRODUCT integration retained; APU image/default/P7 availability and the declared source identity are explicitly scoped. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [mini.json](../../publications/datasheets/mini.json), [overview.typ](../../publications/datasheets/sections/overview.typ), [product-use.typ](../../publications/datasheets/sections/product-use.typ). Match capabilities to the exact profile and selected runtime; do not treat initial ready as delivery of the later Linux acceptance service. |
|
||||
| 6 | Reading this datasheet / 9 | Covered and retained. Existing task-based document and evidence map; no additional hardware capability. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Retain one navigator, the existing 109-entry structure and checked internal destinations. |
|
||||
| 7 | System Architecture / 56 | Covered and retained. Ten AXI data masters, seven-bit global IDs, GA2D master 8, NPU master 9 and JPEG 1R/1W admission. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [axi4_data_crossbar.sv](../../rtl/mini/top/axi4_data_crossbar.sv), [architecture.typ](../../publications/datasheets/sections/architecture.typ), [bus-programming.typ](../../publications/datasheets/sections/bus-programming.typ). Attach contention and recovery measurements before throughput claims. |
|
||||
| 8 | Introduction / 56 | Covered and retained. Ten AXI data masters, seven-bit global IDs, GA2D master 8, NPU master 9 and JPEG 1R/1W admission. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [axi4_data_crossbar.sv](../../rtl/mini/top/axi4_data_crossbar.sv), [architecture.typ](../../publications/datasheets/sections/architecture.typ), [bus-programming.typ](../../publications/datasheets/sections/bus-programming.typ). Attach contention and recovery measurements before throughput claims. |
|
||||
| 9 | Interconnect / 60 | Covered and retained. Ten AXI data masters, seven-bit global IDs, GA2D master 8, NPU master 9 and JPEG 1R/1W admission. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [axi4_data_crossbar.sv](../../rtl/mini/top/axi4_data_crossbar.sv), [architecture.typ](../../publications/datasheets/sections/architecture.typ), [bus-programming.typ](../../publications/datasheets/sections/bus-programming.typ). Attach contention and recovery measurements before throughput claims. |
|
||||
| 10 | Memory Attributes, Cache and DMA Coherency / 67 | Covered and retained. Non-coherent data paths; software buffer ownership and maintenance are required. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [memory-use.typ](../../publications/datasheets/sections/memory-use.typ), [system-reference.json](../../publications/datasheets/system-reference.json). Preserve clean/invalidate and ownership order in each platform integration. |
|
||||
| 11 | Clock and Reset / 70 | Covered and retained. The existing clock/reset framework remains applicable; HP polling is bounded while the earlier generic LP PSRAM-ready loop remains a separate startup boundary. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). A bounded loop does not bound a stalled MMIO transaction; retain stage-specific reset ownership. |
|
||||
| 12 | Interrupt System / 77 | Covered and retained. 64 LP vector positions: two local and 62 external; GA2D vector 32 / ordinal 30 / PLIC 11; NPU vector 33 / ordinal 31 / PLIC 12. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [routing-reference.typ](../../publications/datasheets/sections/routing-reference.typ), [software_reference.py](../../publications/software_reference.py), [system-reference.json](../../publications/datasheets/system-reference.json). Preserve vector/ordinal/PLIC distinctions; no-CSR runtime remains unsupported. |
|
||||
| 13 | DMA Request, Interrupt and Event Routing / 79 | Covered and retained. 64 LP vector positions: two local and 62 external; GA2D vector 32 / ordinal 30 / PLIC 11; NPU vector 33 / ordinal 31 / PLIC 12. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [routing-reference.typ](../../publications/datasheets/sections/routing-reference.typ), [software_reference.py](../../publications/software_reference.py), [system-reference.json](../../publications/datasheets/system-reference.json). Preserve vector/ordinal/PLIC distinctions; no-CSR runtime remains unsupported. |
|
||||
| 14 | Multicore Operation and Resource Ownership / 82 | Covered and retained. Ten shared resource slots with Resource ABI 1.2 and owner-routed faults/interrupts; access controls are not isolation certification. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [system-management.typ](../../publications/datasheets/sections/system-management.typ), [coexistence-reference.typ](../../publications/datasheets/sections/coexistence-reference.typ), [system-reference.json](../../publications/datasheets/system-reference.json). Validate handoff, stop/drain and concurrent workloads with exact firmware/profile reports. |
|
||||
| 15 | Peripheral Coexistence and Resource Conflicts / 84 | Covered and retained. Ten shared resource slots with Resource ABI 1.2 and owner-routed faults/interrupts; access controls are not isolation certification. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [system-management.typ](../../publications/datasheets/sections/system-management.typ), [coexistence-reference.typ](../../publications/datasheets/sections/coexistence-reference.typ), [system-reference.json](../../publications/datasheets/system-reference.json). Validate handoff, stop/drain and concurrent workloads with exact firmware/profile reports. |
|
||||
| 16 | Security and Access-Control Boundaries / 86 | Covered and retained. Ten shared resource slots with Resource ABI 1.2 and owner-routed faults/interrupts; access controls are not isolation certification. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [system-management.typ](../../publications/datasheets/sections/system-management.typ), [coexistence-reference.typ](../../publications/datasheets/sections/coexistence-reference.typ), [system-reference.json](../../publications/datasheets/system-reference.json). Validate handoff, stop/drain and concurrent workloads with exact firmware/profile reports. |
|
||||
| 17 | Debug, Diagnostics and Fault Recovery / 87 | Covered and retained. Ten shared resource slots with Resource ABI 1.2 and owner-routed faults/interrupts; access controls are not isolation certification. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [system-management.typ](../../publications/datasheets/sections/system-management.typ), [coexistence-reference.typ](../../publications/datasheets/sections/coexistence-reference.typ), [system-reference.json](../../publications/datasheets/system-reference.json). Validate handoff, stop/drain and concurrent workloads with exact firmware/profile reports. |
|
||||
| 18 | Register Access and Programming Conventions / 89 | Covered and retained. Source-defined MMIO and bounded protocol subsets; external compliance is not established. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [register-programming.typ](../../publications/datasheets/sections/register-programming.typ), [interface-subsets.typ](../../publications/datasheets/sections/interface-subsets.typ). Retain width/strobe/error semantics and controller-specific limits. |
|
||||
| 19 | Interface Standards and Supported Subsets / 91 | Covered and retained. Source-defined MMIO and bounded protocol subsets; external compliance is not established. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [register-programming.typ](../../publications/datasheets/sections/register-programming.typ), [interface-subsets.typ](../../publications/datasheets/sections/interface-subsets.typ). Retain width/strobe/error semantics and controller-specific limits. |
|
||||
| 20 | Peripherals / 94 | Covered and retained. 42 PRODUCT/MPW IP chapters; instances may share register banks. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [chapter-index.json](../../publications/datasheets/chapter-index.json), [structure-contract.json](../../publications/datasheets/structure-contract.json), [ip-catalog.json](../../publications/datasheets/ip-catalog.json). Keep stable register anchors and the reviewed 109-entry structure contract. |
|
||||
| 21 | XPI Universal Controller (XPI) / 94-113 | Covered and retained. Integrated: Four chip-select slots and 16 programmable LUT sequences. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [xpi.h](../../crt/include/retrosoc/hal/xpi.h), [xpi.md](../../docs/ip/xpi.md), [xpi.c](../../publications/examples/xpi.c). Retain the documented subset and prerequisites. External SDR SPI/QSPI flash; board-specific LUT and timing. Attach a matching scoped report before qualification. |
|
||||
| 22 | SPI SD Card Controller (SPISD) / 114-133 | Covered and retained. Integrated: SD card SPI-mode command/data host. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [spisd.h](../../crt/include/retrosoc/hal/spisd.h), [spisd.md](../../docs/ip/spisd.md), [spisd.c](../../publications/examples/spisd.c). Retain the documented subset and prerequisites. SPI-mode SD card; GPIO route and card supply. Attach a matching scoped report before qualification. |
|
||||
| 23 | SD Card Controller (SDIO0) / 134-155 | Covered and retained. Integrated: Native one-bit/four-bit SDR operation. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [sdio.h](../../crt/include/retrosoc/hal/sdio.h), [sdio.md](../../docs/ip/sdio.md), [sdio.c](../../publications/examples/sdio.c). Retain the documented subset and prerequisites. SD card and shared GPIO route. Attach a matching scoped report before qualification. |
|
||||
| 24 | On-Chip Memory (OCM / SRAM) / 156-162 | Covered and retained. Integrated: 32 KiB in the reference profile, using eight 4 KiB banks. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [onchip_sram.h](../../crt/include/retrosoc/hal/onchip_sram.h), [onchip-sram.md](../../docs/ip/onchip-sram.md), [sram.c](../../publications/examples/sram.c). Retain the documented subset and prerequisites. Selected technology SRAM macro; 32 KiB in the reference profile. Attach a matching scoped report before qualification. |
|
||||
| 25 | PSRAM Controller (PSRAM) / 163-181 | Covered and retained. Integrated: Four ESP-PSRAM64H devices addressable through a 32 MiB window. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [psram.h](../../crt/include/retrosoc/hal/psram.h), [psram.md](../../docs/ip/psram.md), [psram.c](../../publications/examples/psram.c). Retain the documented subset and prerequisites. External QPI PSRAM; mutually exclusive with OPI on shared memory pads. Attach a matching scoped report before qualification. |
|
||||
| 26 | OPI PSRAM / HyperBus-Style Controller / 182-199 | Covered and retained. Partial: One octal DDR memory interface and one selected protocol profile. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [opipsram.h](../../crt/include/retrosoc/hal/opipsram.h), [opipsram.md](../../docs/ip/opipsram.md), [opipsram.c](../../publications/examples/opipsram.c). Retain the documented subset and prerequisites. Compatible octal/HyperBus-style device; shared pads and board timing qualification. Attach a matching scoped report before qualification. |
|
||||
| 27 | SDRAM Controller (SDRAM) / 200-211 | Covered and retained. Integrated: Fixed 64 MiB, x16 SDR geometry with bank/row tracking. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [sdram.h](../../crt/include/retrosoc/hal/sdram.h), [sdram.md](../../docs/ip/sdram.md), [sdram.c](../../publications/examples/sdram.c). Retain the documented subset and prerequisites. External x16 SDR SDRAM; initialization and refresh timings. Attach a matching scoped report before qualification. |
|
||||
| 28 | General-Purpose Input Output (GPIO) / 212-228 | Covered and retained. Integrated: 32 bidirectional GPIOs with administration and restricted user windows. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [gpio.h](../../crt/include/retrosoc/hal/gpio.h), [gpio.md](../../docs/ip/gpio.md), [gpio.c](../../publications/examples/gpio.c). Retain the documented subset and prerequisites. Selected pad library and approved pin routing. Attach a matching scoped report before qualification. |
|
||||
| 29 | Direct Memory Access (DMA) / 229-244 | Covered and retained. Integrated: Eight channel contexts share a 32-bit AXI master. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [dma.h](../../crt/include/retrosoc/hal/dma.h), [dma.md](../../docs/ip/dma.md), [dma.c](../../publications/examples/dma.c). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 30 | General-Purpose Timer (TIM0, TIM1) / 245-251 | Covered and retained. Integrated: Two 32-bit general-purpose timers. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [timer.h](../../crt/include/retrosoc/hal/timer.h), [timer.md](../../docs/ip/timer.md), [timer.c](../../publications/examples/timer.c). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 31 | Real-Time Clock (RTC) / 252-265 | Covered and retained. Integrated: 64-bit seconds and 1/256-second subsecond time. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [rtc.h](../../crt/include/retrosoc/hal/rtc.h), [rtc.c](../../publications/examples/rtc.c), [datasheet.md](../../rtl/managed/clusterip/rtc/doc/datasheet.md). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 32 | Watchdog (WDG) / 266-275 | Covered and retained. Integrated: Independent-clock window watchdog. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [datasheet.md](../../rtl/managed/clusterip/wdg/doc/datasheet.md), [wdg_pkg.sv](../../rtl/managed/clusterip/wdg/rtl/wdg_pkg.sv), [wdg_reg.sv](../../rtl/managed/clusterip/wdg/rtl/wdg_reg.sv). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 33 | Pulse Width Modulation (PWM) / 276-300 | Covered and retained. Integrated: Two timers, four output channels and two operators. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [pwm.h](../../crt/include/retrosoc/hal/pwm.h), [pwm.c](../../publications/examples/pwm.c), [datasheet.md](../../rtl/managed/clusterip/pwm/doc/datasheet.md). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 34 | Management Console (UART0) / 301-313 | Covered and retained. Integrated: 64-byte TX and RX FIFOs; fractional baud-rate generator. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [uart.h](../../crt/include/retrosoc/hal/uart.h), [uart.md](../../docs/ip/uart.md), [uart.c](../../publications/examples/uart.c). Retain the documented subset and prerequisites. Management serial connection; optional DMA/flow-control routing. Attach a matching scoped report before qualification. |
|
||||
| 35 | Application Console (UART1) / 314-315 | Covered and retained. Integrated: 64-byte TX and RX FIFOs; fractional baud-rate generator. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [README.md](../../app/ports/linux/README.md), [retrosoc_hp.dts](../../app/ports/linux/linux/retrosoc_hp.dts), [uart.h](../../crt/include/retrosoc/hal/uart.h). Retain the documented subset and prerequisites. Dedicated console TX/RX; no connected DMA or RTS/CTS. Attach a matching scoped report before qualification. |
|
||||
| 36 | Inter-Integrated Circuit (I2C) / 316-329 | Covered and retained. Integrated: Two controller instances with 7-bit and 10-bit addressing. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [i2c.h](../../crt/include/retrosoc/hal/i2c.h), [i2c.md](../../docs/ip/i2c.md), [i2c.c](../../publications/examples/i2c.c). Retain the documented subset and prerequisites. External bus pull-ups and compatible target voltages. Attach a matching scoped report before qualification. |
|
||||
| 37 | WS2812 LED Interface / 330-338 | Covered and retained. Integrated: 24-bit GRB transmission on one GPIO alternate function. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [ws2812.h](../../crt/include/retrosoc/hal/ws2812.h), [ws2812.md](../../docs/ip/ws2812.md), [ws2812.c](../../publications/examples/ws2812.c). Retain the documented subset and prerequisites. Compatible LED chain and approved level/supply interface. Attach a matching scoped report before qualification. |
|
||||
| 38 | Personal System/2 (PS2) / 339-348 | Covered and retained. Integrated: Bidirectional open-drain host interface. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [ps2.h](../../crt/include/retrosoc/hal/ps2.h), [ps2.c](../../publications/examples/ps2.c), [datasheet.md](../../rtl/managed/clusterip/ps2/doc/datasheet.md). Retain the documented subset and prerequisites. Open-drain interface and board pull-ups. Attach a matching scoped report before qualification. |
|
||||
| 39 | SDIO Controller (SDIO1) / 349-352 | Covered and retained. Integrated: Native one-bit/four-bit SDR operation. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [sdio.h](../../crt/include/retrosoc/hal/sdio.h), [sdio.md](../../docs/ip/sdio.md), [sdio.c](../../publications/examples/sdio.c). Retain the documented subset and prerequisites. SD card and dedicated pads; generic FPGA mapping pending. Attach a matching scoped report before qualification. |
|
||||
| 40 | USB 2.0 Dual-Role Controller / 353-385 | Covered and retained. Integrated: Dual-role digital controller with external 8-bit ULPI PHY. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [usb2.h](../../crt/include/retrosoc/hal/usb2.h), [usb2.md](../../docs/ip/usb2.md), [usb2.c](../../publications/examples/usb2.c). Retain the documented subset and prerequisites. External ULPI PHY, 60 MHz interface clock, VBUS/role circuitry. Attach a matching scoped report before qualification. |
|
||||
| 41 | Architecture Information (ARCHINFO) / 386-394 | Covered and retained. Integrated: Read-only identity, configuration and topology discovery. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [archinfo.c](../../publications/examples/archinfo.c), [datasheet.md](../../rtl/managed/clusterip/archinfo/doc/datasheet.md), [archinfo_reg.sv](../../rtl/managed/clusterip/archinfo/rtl/archinfo_reg.sv). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 42 | System Controller (SYSCTRL) / 395-415 | Covered and retained. Integrated: Root-managed configuration, HP lifecycle and clock requests. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [sysctrl.h](../../crt/include/retrosoc/hal/sysctrl.h), [sysctrl.md](../../docs/ip/sysctrl.md), [sysctrl.c](../../publications/examples/sysctrl.c). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 43 | Reset Clock Unit (RCU) / 416-417 | Covered and retained. Integrated: AON-controlled requests and clock/reset policy. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [clock.h](../../crt/include/retrosoc/hal/clock.h), [pll-clock-control.md](../../docs/pll-clock-control.md), [rcu.c](../../publications/examples/rcu.c). Retain the documented subset and prerequisites. Reference PLL disabled; any physical PLL/backend needs separate qualification. Attach a matching scoped report before qualification. |
|
||||
| 44 | Management Local Interrupts (CLINT) / 418-422 | Covered and retained. Integrated: Per-hart software interrupts and 64-bit timer compare. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [clint.h](../../crt/include/retrosoc/hal/clint.h), [clint.md](../../docs/ip/clint.md), [clint.c](../../publications/examples/clint.c). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 45 | HP Local Interrupt Controller (ACLINT) / 423-426 | Covered and retained. Integrated: Two addressable hart slots; HP consumes slot 1. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [retrosoc_hp.dts](../../app/ports/linux/linux/retrosoc_hp.dts), [platform.c](../../app/ports/linux/opensbi/retrosoc_hp/platform.c), [clint.md](../../docs/ip/clint.md). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 46 | HP Platform-Level Interrupt Controller (PLIC) / 427-430 | Covered and retained. Integrated: 32 source IDs, with source 0 reserved. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [retrosoc_hp.dts](../../app/ports/linux/linux/retrosoc_hp.dts), [platform.c](../../app/ports/linux/opensbi/retrosoc_hp/platform.c), [hp-platform.md](../../docs/ip/hp-platform.md). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 47 | LP/HP Mailbox / 431-438 | Covered and retained. Integrated: Separate LP-to-HP and HP-to-LP payload banks. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 48 | Resource Controller / 439-445 | Covered and retained. Partial: Ten independently managed shared resources; resource 8 owns GA2D and resource 9 owns NPU execution, including lifecycle and LP/HP IRQ routing. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [resource.h](../../crt/include/retrosoc/hal/resource.h), [resource-controller.md](../../docs/ip/resource-controller.md), [resource.c](../../publications/examples/resource.c). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 49 | Fabric Monitor / 446-457 | Covered and retained. Integrated: Ten master and six target observation banks; master bank 8 observes GA2D traffic and master bank 9 observes NPU descriptor and data DMA traffic. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [fabric_monitor.h](../../crt/include/retrosoc/hal/fabric_monitor.h), [fabric-monitor.md](../../docs/ip/fabric-monitor.md), [monitor.c](../../publications/examples/monitor.c). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 50 | Inter-Integrated Circuit Sound (I2S) / 460-468 | Covered and retained. Integrated: Stereo master TX/RX with independent audio clock. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [i2s.h](../../crt/include/retrosoc/hal/i2s.h), [i2s.md](../../docs/ip/i2s.md), [i2s.c](../../publications/examples/i2s.c). Retain the documented subset and prerequisites. External audio clock and codec; stereo master operation. Attach a matching scoped report before qualification. |
|
||||
| 51 | Digital Video Port (DVP) / 469-479 | Covered and retained. Integrated: 8-bit parallel RGB565/YUV422 capture. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [dvp.h](../../crt/include/retrosoc/hal/dvp.h), [dvp.md](../../docs/ip/dvp.md), [dvp.c](../../publications/examples/dvp.c). Retain the documented subset and prerequisites. Parallel camera, sensor configuration and pixel clock. Attach a matching scoped report before qualification. |
|
||||
| 52 | JPEG Encoder / Decoder / 480-503 | Covered and retained. Partial: 8-bit Baseline Sequential JPEG encode or decode. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [jpeg.h](../../crt/include/retrosoc/hal/jpeg.h), [jpeg.md](../../docs/ip/jpeg.md), [jpeg.c](../../publications/examples/jpeg.c). Retain the documented subset and prerequisites. Native slot-6 payload admission has one normal read and one normal write credit at class 8; standalone codec behavior and end-to-end system qualification remain separate scopes. Attach a matching scoped report before qualification. |
|
||||
| 53 | 2D Graphics Accelerator (GA2D) / 504-523 | Covered and retained. Integrated: P5 direct single-job FILL, COPY, CONVERT, opaque alpha BLEND, A8 masks and exact background/destination in-place composition. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [ga2d.md](../../docs/ip/ga2d.md), [apb4_ga2d.sv](../../rtl/ip/multimedia/apb4_ga2d.sv), [ga2d_core.sv](../../rtl/ip/multimedia/ga2d_core.sv). P6 test sources and dated records already exist. Attach current-commit full-product contention, workload throughput and physical closure reports; preserve the documented subset. |
|
||||
| 54 | Audio Processing Unit (APU, partial) / 524-569 | Covered and retained. Partial: WAV/FLAC image and job/stream execution; fixed KWS is enabled only in the P7 acceptance configuration. MP3 remains unsupported. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [Makefile](../../Makefile), [main.c](../../app/apps/apu_release/main.c), [main.c](../../app/ports/hp-apu/main.c). Keep default/P7 capability and digest distinct, MP3 unsupported and KWS configuration-dependent. A shipped WAV/FLAC image or smoke wrapper is not full corpus or sustained-audio qualification. Keep inferred KWS storage distinct from the specified technology-macro target. |
|
||||
| 55 | Neural Processing Unit (NPU) / 570-594 | Covered and retained. Integrated: Eight INT8 operators with native HP descriptor/DMA execution and private local SRAM. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [npu.h](../../crt/include/retrosoc/hal/npu.h), [npu_regs.h](../../crt/include/retrosoc/hal/npu_regs.h), [npu.c](../../crt/src/hal/npu.c). Attach matching KWS/VWW raw reports including CPU preprocessing/Softmax and cache costs. Keep unknown-operator rejection, INT32 limits, abort/drain and private SRAM boundaries explicit; no arbitrary TFLite or certification claim. |
|
||||
| 56 | Crypto Controller / 595-616 | Covered and retained. Integrated: AES-128/192/256, SHA-224/256 and raw RSA-2048. Tests available; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [crypto.h](../../crt/include/retrosoc/hal/crypto.h), [crypto.md](../../docs/ip/crypto.md), [crypto.c](../../publications/examples/crypto.c). Retain the documented subset and prerequisites. LP-controlled buffers and key lifecycle; no secure key-store claim. Attach a matching scoped report before qualification. |
|
||||
| 57 | Cyclic Redundancy Check (CRC) / 617-623 | Covered and retained. Integrated: Programmable 7-, 8-, 16- or 32-bit CRC. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [crc.h](../../crt/include/retrosoc/hal/crc.h), [crc.c](../../publications/examples/crc.c), [datasheet.md](../../rtl/managed/clusterip/crc/doc/datasheet.md). Retain the documented subset and prerequisites. No additional off-chip component implied; use the selected clock/reset and access policy. Attach a matching scoped report before qualification. |
|
||||
| 58 | Random Number Generator (RNG) / 624-632 | Covered and retained. Partial: Entropy-source qualification, FIFO and continuous health checks. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [rng.h](../../crt/include/retrosoc/hal/rng.h), [rng.c](../../publications/examples/rng.c), [datasheet.md](../../rtl/managed/clusterip/rng/doc/datasheet.md). Retain the documented subset and prerequisites. Entropy-source qualification absent; deterministic integration source. Attach a matching scoped report before qualification. |
|
||||
| 59 | Low-Bandwidth Extension (EXT-L) / 633-634 | Covered and retained. Integrated: Fixed APB4 control and one interrupt. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [extension.h](../../crt/include/retrosoc/hal/extension.h), [extensions.md](../../docs/ip/extensions.md), [ext-l.c](../../publications/examples/ext-l.c). Retain the documented subset and prerequisites. Fixed external APB target and lifecycle contract. Attach a matching scoped report before qualification. |
|
||||
| 60 | High-Bandwidth Extension (EXT-H) / 635-643 | Covered and retained. Integrated: Fixed EXT-H control, ownership, bounds and lifecycle. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [extension.h](../../crt/include/retrosoc/hal/extension.h), [extensions.md](../../docs/ip/extensions.md), [extensions.c](../../publications/examples/extensions.c). Retain the documented subset and prerequisites. Bounded external AXI master and ACL configuration. Attach a matching scoped report before qualification. |
|
||||
| 61 | Packaging / 644 | Evidence needed. No matching characterized package, electrical, thermal or timing specification. Source/flow descriptions exist; no current matching scoped physical result is attached. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [pins.typ](../../publications/datasheets/sections/pins.typ), [electrical-reference.typ](../../publications/datasheets/sections/electrical-reference.typ). Supply package/board/corner/instrument evidence before publishing ratings. |
|
||||
| 62 | Electrical and Timing Specifications / 653 | Evidence needed. No matching characterized package, electrical, thermal or timing specification. Source/flow descriptions exist; no current matching scoped physical result is attached. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [pins.typ](../../publications/datasheets/sections/pins.typ), [electrical-reference.typ](../../publications/datasheets/sections/electrical-reference.typ). Supply package/board/corner/instrument evidence before publishing ratings. |
|
||||
| 63 | Software / 656 | Covered and retained. HP event polling uses 64,000,000 iterations, not milliseconds. Initial ready precedes GA2D result, cache-clean acknowledgement, HP-held state and return of ownership to LP; NPU handoff is selected by RS_NPU_P5_ACCEPTANCE, RS_NPU_P6_ACCEPTANCE. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 64 | Boot Configuration, Initialization and Recovery / 656 | Covered and retained. HP event polling uses 64,000,000 iterations, not milliseconds. Initial ready precedes GA2D result, cache-clean acknowledgement, HP-held state and return of ownership to LP; NPU handoff is selected by RS_NPU_P5_ACCEPTANCE, RS_NPU_P6_ACCEPTANCE. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 65 | Programming, Image Maintenance and Service Procedures / 663 | Covered and retained. Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py). Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 66 | Runtime, SDK and Shell / 665 | Covered and retained. Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py). Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 67 | Applications / 673 | Covered and retained. Runtime/HAL and conditional Linux bringup exist; no general GA2D Linux graphics, APU ASoC or generic NPU Linux driver is delivered. CSR and profile conditions apply. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [software.typ](../../publications/datasheets/sections/software.typ), [software-runtime.typ](../../publications/datasheets/sections/software-runtime.typ), [software_reference.py](../../publications/software_reference.py). Attach exact firmware/boot/device reports; do not infer integrated pass from syntax or host tests. |
|
||||
| 68 | Linux and Driver Status / 676 | Covered and retained. HP event polling uses 64,000,000 iterations, not milliseconds. Initial ready precedes GA2D result, cache-clean acknowledgement, HP-held state and return of ownership to LP; NPU handoff is selected by RS_NPU_P5_ACCEPTANCE, RS_NPU_P6_ACCEPTANCE. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 69 | Software Support and Validated Configurations / 679 | Covered and retained. HP event polling uses 64,000,000 iterations, not milliseconds. Initial ready precedes GA2D result, cache-clean acknowledgement, HP-held state and return of ownership to LP; NPU handoff is selected by RS_NPU_P5_ACCEPTANCE, RS_NPU_P6_ACCEPTANCE. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 70 | Implementation / 683 | Covered and retained. Current dev host-runtime/bootstrap increments reviewed; Linux x86_64, Python 3.10, Java 17 and SBT contract retained. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [dependencies.lock.json](../../dependencies/dependencies.lock.json), [Dockerfile](../../docker/Dockerfile), [flake.nix](../../flake.nix). Use the committed bootstrap and lock; a Docker build or Nix check is not a runtime regression pass. |
|
||||
| 71 | SoC Integration / 683 | Covered and retained. Current dev host-runtime/bootstrap increments reviewed; Linux x86_64, Python 3.10, Java 17 and SBT contract retained. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [dependencies.lock.json](../../dependencies/dependencies.lock.json), [Dockerfile](../../docker/Dockerfile), [flake.nix](../../flake.nix). Use the committed bootstrap and lock; a Docker build or Nix check is not a runtime regression pass. |
|
||||
| 72 | RTL Simulation / 684 | Covered and retained. Reproducible source and test flows exist; local execution and release qualification have separate scopes. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [software.typ](../../publications/datasheets/sections/software.typ), [regress.py](../../scripts/regress.py), [engineering.md](../../docs/engineering.md). Run the selected committed profile with required tools and archive machine-readable verdicts. |
|
||||
| 73 | FPGA Verification / 685 | Evidence needed. Board constraints/integration inputs exist; complete board acceptance evidence is not attached. Source/flow descriptions exist; no current matching scoped physical result is attached. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [README.md](../../fpga/README.md), [software.typ](../../publications/datasheets/sections/software.typ), [electrical-reference.typ](../../publications/datasheets/sections/electrical-reference.typ). Provide approved pin routes, board revision and external-device acceptance logs. |
|
||||
| 74 | Physical Design / 686 | Evidence needed. Physical flow inputs exist; no matching synthesis/netlist/STA/signoff report is attached. Source/flow descriptions exist; no current matching scoped physical result is attached. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [README.md](../../physical/README.md), [software.typ](../../publications/datasheets/sections/software.typ), [release-verification.typ](../../publications/datasheets/sections/release-verification.typ). Archive exact PDK/library/corner/constraints and complete physical reports. |
|
||||
| 75 | PCB Hardware / 687 | Evidence needed. Board constraints/integration inputs exist; complete board acceptance evidence is not attached. Source/flow descriptions exist; no current matching scoped physical result is attached. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [README.md](../../fpga/README.md), [software.typ](../../publications/datasheets/sections/software.typ), [electrical-reference.typ](../../publications/datasheets/sections/electrical-reference.typ). Provide approved pin routes, board revision and external-device acceptance logs. |
|
||||
| 76 | Appendix: MPW Compatibility / 688 | Covered and retained. Separate selectable MPW core/user-IP profile; not the fixed PRODUCT integration. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [mini-mpw.mk](../../configs/cluster/mini-mpw.mk), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Keep MPW selection, reset and GPIO ownership separate from PRODUCT claims. |
|
||||
| 77 | SoC Template / 688 | Covered and retained. Separate selectable MPW core/user-IP profile; not the fixed PRODUCT integration. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [mini-mpw.mk](../../configs/cluster/mini-mpw.mk), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Keep MPW selection, reset and GPIO ownership separate from PRODUCT claims. |
|
||||
| 78 | MPW User Timer / 690-692 | Covered and retained. MPW only: MPW-selectable timer and divider. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [user_ip.h](../../crt/include/retrosoc/hal/user_ip.h), [user-ip.md](../../docs/ip/user-ip.md), [mpw_timer.c](../../publications/examples/mpw_timer.c). Retain the documented subset and prerequisites. MPW profile, selected user-IP manifest and pad ownership. Attach a matching scoped report before qualification. |
|
||||
| 79 | MPW User GPIO / 693-695 | Covered and retained. MPW only: MPW-selectable user GPIO data and enables. Source reviewed; 0 attached per-IP report records. Workflow outcomes do not replace scoped reports. | Selected feature, programming and restriction phrases emphasized; shared register/ABI descriptions retained. | [user_ip.h](../../crt/include/retrosoc/hal/user_ip.h), [user-ip.md](../../docs/ip/user-ip.md), [mpw_gpio.c](../../publications/examples/mpw_gpio.c). Retain the documented subset and prerequisites. MPW profile, selected user-IP manifest and pad ownership. Attach a matching scoped report before qualification. |
|
||||
| 80 | Appendix: Product Direction / 696 | Covered and retained. Future family positioning and release milestones are not implemented product commitments. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [appendices.typ](../../publications/datasheets/sections/appendices.typ). Publish commitments only after a reviewed implementation and release decision. |
|
||||
| 81 | Product Series / 696 | Covered and retained. Future family positioning and release milestones are not implemented product commitments. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [appendices.typ](../../publications/datasheets/sections/appendices.typ). Publish commitments only after a reviewed implementation and release decision. |
|
||||
| 82 | Roadmap / 697 | Covered and retained. Future family positioning and release milestones are not implemented product commitments. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [appendices.typ](../../publications/datasheets/sections/appendices.typ). Publish commitments only after a reviewed implementation and release decision. |
|
||||
| 83 | Technical Report / 698 | Covered and retained. Exact-commit CI observation for c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b at 2026-09-23T08:26:42Z; individual workflow/stage conclusions remain scoped. Source/document review; test availability is not an executed pass. | Current source/CI identity recorded and evidence phrases emphasized; unfinished runs are not passes. | [system-reference.json](../../publications/datasheets/system-reference.json), [release-verification.typ](../../publications/datasheets/sections/release-verification.typ), [dev_reference.py](../../publications/dev_reference.py). Keep unfinished/failed/skipped states and original reports. Previous local test totals remain historical; CI does not populate absent per-IP qualification reports. |
|
||||
| 84 | Release Verification Summary / 698 | Covered and retained. Exact-commit CI observation for c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b at 2026-09-23T08:26:42Z; individual workflow/stage conclusions remain scoped. Source/document review; test availability is not an executed pass. | Current source/CI identity recorded and evidence phrases emphasized; unfinished runs are not passes. | [system-reference.json](../../publications/datasheets/system-reference.json), [release-verification.typ](../../publications/datasheets/sections/release-verification.typ), [dev_reference.py](../../publications/dev_reference.py). Keep unfinished/failed/skipped states and original reports. Previous local test totals remain historical; CI does not populate absent per-IP qualification reports. |
|
||||
| 85 | Shuttle and Qualification Evidence / 702 | Evidence needed. No matching silicon/shuttle/package characterization report supplied. Source/flow descriptions exist; no current matching scoped physical result is attached. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [appendices.typ](../../publications/datasheets/sections/appendices.typ), [release-verification.typ](../../publications/datasheets/sections/release-verification.typ). Supply lot, die revision, package, setup and test conditions with each measurement. |
|
||||
| 86 | Performance and Power Characterization / 703 | Covered and retained. Counters and workload definitions exist; no matching product performance/power measurement is supplied. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Measure the selected runtime, clock, workload and memory/cache costs. Iteration budgets are not milliseconds; historical IP reports do not establish current full-product closure. |
|
||||
| 87 | Known Limitations and Revision Compatibility / 705 | Covered and retained. Current feature gates and source/runtime limitations are explicit; the Linux rootfs ready publisher does not supply the full acceptance service. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 88 | Implementation and Qualification Limitations / 705 | Covered and retained. Current feature gates and source/runtime limitations are explicit; the Linux rootfs ready publisher does not supply the full acceptance service. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 89 | Revision Identification and Compatibility / 710 | Covered and retained. Current feature gates and source/runtime limitations are explicit; the Linux rootfs ready publisher does not supply the full acceptance service. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 90 | Appendix: Software Memory and Buffer Requirements / 711 | Covered and retained. Static linker and worked-buffer accounting; examples are not measured peak runtime usage. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [memory-use.typ](../../publications/datasheets/sections/memory-use.typ), [README.md](../../crt/README.md). Measure stack, heap-free working sets and application buffers on the actual workload. |
|
||||
| 91 | Linker Layout and Runtime Accounting / 711 | Covered and retained. Static linker and worked-buffer accounting; examples are not measured peak runtime usage. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [memory-use.typ](../../publications/datasheets/sections/memory-use.typ), [README.md](../../crt/README.md). Measure stack, heap-free working sets and application buffers on the actual workload. |
|
||||
| 92 | Worked Buffer Budgets / 712 | Covered and retained. Static linker and worked-buffer accounting; examples are not measured peak runtime usage. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [memory-use.typ](../../publications/datasheets/sections/memory-use.typ), [README.md](../../crt/README.md). Measure stack, heap-free working sets and application buffers on the actual workload. |
|
||||
| 93 | Appendix: Terminology, Notation and Document Map / 714 | Covered and retained. Existing task-based document and evidence map; no additional hardware capability. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Retain one navigator, the existing 109-entry structure and checked internal destinations. |
|
||||
| 94 | Terminology and Units / 714 | Covered and retained. Document conventions, navigation and provenance; not an additional hardware capability. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
| 95 | Reading Numbers and Status / 715 | Covered and retained. Document conventions, navigation and provenance; not an additional hardware capability. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
| 96 | Document and Evidence Navigation / 716 | Covered and retained. Existing task-based document and evidence map; no additional hardware capability. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Retain one navigator, the existing 109-entry structure and checked internal destinations. |
|
||||
| 97 | Appendix: Global Register and Address Index / 717 | Covered and retained. Generated register/address inventory with stable per-register destinations. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [register-index.typ](../../publications/datasheets/sections/register-index.typ), [register-annotations.json](../../publications/datasheets/register-annotations.json), [ip-catalog.json](../../publications/datasheets/ip-catalog.json). Keep C/RTL parity and source-derived anchors; do not hand-maintain duplicate register lists. |
|
||||
| 98 | PRODUCT Register Instances / 717 | Covered and retained. Generated register/address inventory with stable per-register destinations. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [register-index.typ](../../publications/datasheets/sections/register-index.typ), [register-annotations.json](../../publications/datasheets/register-annotations.json), [ip-catalog.json](../../publications/datasheets/ip-catalog.json). Keep C/RTL parity and source-derived anchors; do not hand-maintain duplicate register lists. |
|
||||
| 99 | MPW Conditional Register Instances / 758 | Covered and retained. Generated register/address inventory with stable per-register destinations. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [register-index.typ](../../publications/datasheets/sections/register-index.typ), [register-annotations.json](../../publications/datasheets/register-annotations.json), [ip-catalog.json](../../publications/datasheets/ip-catalog.json). Keep C/RTL parity and source-derived anchors; do not hand-maintain duplicate register lists. |
|
||||
| 100 | Appendix: Fault and Status Code Reference / 759 | Covered and retained. HP event polling uses 64,000,000 iterations, not milliseconds. Initial ready precedes GA2D result, cache-clean acknowledgement, HP-held state and return of ownership to LP; NPU handoff is selected by RS_NPU_P5_ACCEPTANCE, RS_NPU_P6_ACCEPTANCE. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 101 | Diagnostic Code Namespaces / 759 | Covered and retained. Source-defined diagnostic namespaces, application returns and sticky TEST_STATUS verdicts. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [fault-reference.typ](../../publications/datasheets/sections/fault-reference.typ), [application-diagnostics.typ](../../publications/datasheets/sections/application-diagnostics.typ), [engineering.md](../../docs/engineering.md). Distinguish software returns from hardware completion and log presence from test pass. |
|
||||
| 102 | Status Registers and Capture Points / 765 | Covered and retained. Source-defined diagnostic namespaces, application returns and sticky TEST_STATUS verdicts. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [fault-reference.typ](../../publications/datasheets/sections/fault-reference.typ), [application-diagnostics.typ](../../publications/datasheets/sections/application-diagnostics.typ), [engineering.md](../../docs/engineering.md). Distinguish software returns from hardware completion and log presence from test pass. |
|
||||
| 103 | Firmware Application Results / 771 | Covered and retained. HP event polling uses 64,000,000 iterations, not milliseconds. Initial ready precedes GA2D result, cache-clean acknowledgement, HP-held state and return of ownership to LP; NPU handoff is selected by RS_NPU_P5_ACCEPTANCE, RS_NPU_P6_ACCEPTANCE. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [main.c](../../app/apps/hp_boot/main.c), [hp_mailbox.c](../../crt/src/hal/hp_mailbox.c), [S99retrosoc-hp](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp). Keep the selected runtime and every terminal checkpoint explicit. The supplied Linux rootfs only sends initial ready and lacks the later GA2D/cache-clean service; HP_LINUX_READY also appears for freestanding acceptance. Reset is requested by the failure helper only before GA2D ownership has passed to HP. |
|
||||
| 104 | Automated Completion and Simulator Verdicts / 774 | Covered and retained. Source-defined diagnostic namespaces, application returns and sticky TEST_STATUS verdicts. Source/document review; test availability is not an executed pass. | Key phrases reviewed; preserve technical meaning and ordinary code/diagram typography. | [fault-reference.typ](../../publications/datasheets/sections/fault-reference.typ), [application-diagnostics.typ](../../publications/datasheets/sections/application-diagnostics.typ), [engineering.md](../../docs/engineering.md). Distinguish software returns from hardware completion and log presence from test pass. |
|
||||
| 105 | Document Control / 775 | Covered and retained. Publication identity and source provenance for c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b; no additional hardware capability. Source/document review; test availability is not an executed pass. | Presentation history, exact source identity, contact and final pagination reviewed. | [mini.json](../../publications/datasheets/mini.json), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Ship the matching PDF, manifest, change-page report, chapter review and actual validation record together. |
|
||||
| 106 | Revision History / 775 | Covered and retained. Publication identity and source provenance for c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b; no additional hardware capability. Source/document review; test availability is not an executed pass. | Presentation history, exact source identity, contact and final pagination reviewed. | [mini.json](../../publications/datasheets/mini.json), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Ship the matching PDF, manifest, change-page report, chapter review and actual validation record together. |
|
||||
| 107 | Sources and Reproducibility / 776 | Covered and retained. Publication identity and source provenance for c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b; no additional hardware capability. Source/document review; test availability is not an executed pass. | Presentation history, exact source identity, contact and final pagination reviewed. | [mini.json](../../publications/datasheets/mini.json), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Ship the matching PDF, manifest, change-page report, chapter review and actual validation record together. |
|
||||
| 108 | License / 777 | Covered and retained. Publication identity and source provenance for c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b; no additional hardware capability. Source/document review; test availability is not an executed pass. | Presentation history, exact source identity, contact and final pagination reviewed. | [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
| 109 | Document Status and Contact / 778 | Covered and retained. Publication identity and source provenance for c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b; no additional hardware capability. Source/document review; test availability is not an executed pass. | Presentation history, exact source identity, contact and final pagination reviewed. | [reading.typ](../../publications/datasheets/sections/reading.typ), [usage-appendices.typ](../../publications/datasheets/sections/usage-appendices.typ), [appendices.typ](../../publications/datasheets/sections/appendices.typ). Preserve clear DRAFT/status language, source links and third-party license ownership. |
|
||||
|
||||
The unnumbered closing page remains outside the frozen chapter contract. Subsequent page movement is navigation, not a newly implemented feature. No RTL, SDK interface, hardware profile or CI rule was changed by this publication task.
|
||||
@@ -1,47 +1,108 @@
|
||||
# Mini datasheet content review - 2026-09-22
|
||||
# Mini datasheet content review - v0.5 presentation revision
|
||||
|
||||
The v0.5 DRAFT targets dev commit
|
||||
`ca4b06d30456599a2d3fd676d832f8d4dd2f78af`. The main reference remains
|
||||
IHP130 PRODUCT / 32 KiB SRAM; the APU P7 acceptance profile is described separately.
|
||||
## Current presentation revision
|
||||
|
||||
This round retains v0.5 DRAFT / 2026-09-22 and reviewed source
|
||||
`c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b`. Its comparison baseline is the
|
||||
779-page PDF with SHA-256
|
||||
`25257e5243e945401c8a214d4043819cf802a7fa2d22b04d83b513ce9075647b`.
|
||||
The cover contact becomes `Yuchi Miao(miaoyuchi@ict.ac.cn)` with a mail link;
|
||||
PDF author metadata remains the name. Functional uses an explicitly partial,
|
||||
vertical left-half pale-gold mark. This is not a new full-verification claim.
|
||||
|
||||
All frozen chapters are reviewed for selective emphasis: short capability and
|
||||
parameter phrases, programming prerequisites/order, limits, failure conditions
|
||||
and evidence boundaries. The IP renderer preserves explicit strong spans rather
|
||||
than deleting their markers. Code, addresses, register identifiers and diagram
|
||||
labels keep their separate typography rules. Hardware text and values are retained.
|
||||
The current dev increment changes only
|
||||
Docker/Nix runtime libraries, tool-archive access modes, environment stamp
|
||||
permissions, their guide and host tests; RTL, SDK and committed hardware profiles
|
||||
are unchanged. The new revision-history row records this presentation work.
|
||||
|
||||
This round uses only `v05-emphasis-` content markers plus shared navigation
|
||||
markers. Earlier source-refresh corrections below remain historical context.
|
||||
Regenerated chapter-review and change-page records identify final page movement
|
||||
without describing NPU or other existing IP as newly added.
|
||||
Build directly in the current dev checkout and retain the exact reviewed SHA
|
||||
and fresh CI observation. The temporary independent snapshot directory was
|
||||
removed at the user's request; existing shared caches and earlier PDF artifacts
|
||||
remain. Strict source checks remain enabled.
|
||||
|
||||
## Prior technical refresh and retained commercial comparison
|
||||
|
||||
The preceding technical refresh retained **v0.5 DRAFT / 2026-09-22** and reviewed commit
|
||||
`b209ccedfe6f9c33078ef082a4d31580d4d1a845`. The main reference remains
|
||||
IHP130 PRODUCT / 32 KiB SRAM; the APU P7 acceptance profile is separate.
|
||||
This is a publication refresh, not a hardware change or a new qualification campaign.
|
||||
|
||||
The [STM32N6 datasheet](https://www.st.com/resource/en/datasheet/dm01125716.pdf),
|
||||
[ESP32-P4 datasheet](https://documentation.espressif.com/esp32-p4_datasheet_en.html)
|
||||
and [RP2350 datasheet](https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf)
|
||||
inform the organization of accelerator functions, configuration boundaries,
|
||||
programming references and revision/errata material. Their features, numerical
|
||||
ratings and certifications are not transferred to retroSoC.
|
||||
That technical refresh compared against the 777-page baseline bound to
|
||||
`ca4b06d30456599a2d3fd676d832f8d4dd2f78af`, with SHA-256
|
||||
`c8e18ba1a973ed409bf2fb3c2197cea427097c1b57760b04fb1e1c97a7ea26a6`.
|
||||
That round used the `v05-refresh-` prefix for its active change markers. NPU's
|
||||
existing chapter and earlier diagram work were retained, not newly added.
|
||||
Actual final page ranges belong to the delivered change report; pagination alone
|
||||
does not turn retained material into a content change.
|
||||
|
||||
| Area | Implementation and document assessment | v0.5 disposition | Recommendation |
|
||||
## Commercial references and bounded use
|
||||
|
||||
The official sources below were checked on **2026-09-22**. The adopted ideas concern
|
||||
organization and clarity; their features, numerical ratings, certifications and
|
||||
release-status policies are not retroSoC specifications.
|
||||
|
||||
| Official reference | Document identity and release | Relevant organization | Disposition for Mini |
|
||||
| --- | --- | --- | --- |
|
||||
| NPU | Software-launchable eight-operator computation, private DMA/SRAM, compiler and HAL exist. Publication data mixed shell-only and enabled descriptions and lacked a chapter. | Added the independent NPU chapter, source-derived geometry, operator/job/error limits, register/HAL reference, circuit, storage, descriptor/parameter layouts and normal/abort waveforms. | Use the static supported graph subset and exact numeric profile. Attach matching full-corpus and physical reports before claiming speedup, accuracy or timing closure. |
|
||||
| APU formats and base programming | APUMC V1/V2, 4096-word current store, seven classes/62 opcodes, APUM model and 128-byte job format remain correct. | Covered; retained. Default and P7 capability/digest identities are now explicit. | Preserve format compatibility and distinguish the fixed APUM engine from NPU deployment. MP3 remains unsupported. |
|
||||
| APU configuration and acceptance | Default KWS is off; the P7 acceptance profile enables it and publishes digest 0xF5005D7C. LP/HP acceptance and quiesced-loader progress are implemented. | Updated loader/ACL/ownership/cache and bare-metal HP workflow. No Linux ASoC support is claimed. | A passing smoke wrapper or missing-data early return is not the full accuracy or 60-second-per-scenario release campaign. Supply workload/clock/result artifacts. |
|
||||
| GA2D | Existing FILL/COPY/CONVERT/opaque BLEND/A8 programming coverage is adequate. P6 extends tests, workload matrices and dated evidence. | Retained functional ABI; updated performance-method and evidence boundaries, including schema 3. | The historical composition target and 48 MHz slow-corner timing were not met. Full-product closure and current-source measurements still need matching artifacts. |
|
||||
| Fabric, memory conversion and resources | Ten masters/resources, NPU master/resource9 and Resource ABI1.2 are implemented. The 64-to-32 converter supports fragmented long bursts. | Updated prose, matrices and source-bound circuits, NPU IRQ/fault/cache/lifecycle references, and corrected the overview NPU HP background. | Preserve master/target credit, permission, source-ID and boundary rules. An admitted burst is not a throughput guarantee. |
|
||||
| Address/register/IRQ/pad inventories | Existing generation and register-field mechanisms are adequate for their declared scope. | Covered; retained and extended to the independently rendered NPU chapter. No new NPU pins are implied. | Keep chapter, catalog, feature, register, diagram and API coverage synchronized when advancing the source snapshot. |
|
||||
| Startup, cache handoff and recovery | Existing LP/HP startup, boot image, timeout/partial-transfer, ownership and recovery references are substantial and remain applicable. | Covered; retained with NPU/APU and current diagnostic-stage additions. Repeated result codes remain stage-qualified. | A HAL, DT node or freestanding HP payload is not a native Linux driver. Complete cache and terminal/drain handoff before buffer reuse. |
|
||||
| Interface, format and memory budgeting | Existing mode exclusions, byte packing, pitches, buffer accounting and interoperability guidance are adequate. | Covered; retained with NPU INT8 preprocessing and CPU-finalizer boundaries. | Check actual byte order, zero points, allocation/stride and producer/consumer lifetimes; shared memory does not convert formats. |
|
||||
| Electrical, package, thermal, reliability and ordering | Chapter structure and evidence requirements are complete; measured product values are not. | Covered structure; evidence missing. Existing placeholders are retained instead of duplicated. | Supply process/package/corner/board/instrument/workload evidence. Do not substitute target clocks, analytic peaks or commercial-device limits. |
|
||||
| Release evidence | Current CI status, historical narratives and exact-profile IP reports are different evidence classes. | Updated commit-bound CI with status and nullable conclusion; dated GA2D/NPU narratives remain historical. | Refresh CI before delivery and retain pending/failed/skipped states. Missing original reports cannot be recreated from prose as current passes. |
|
||||
| [STM32N6 datasheet](https://www.st.com/resource/en/datasheet/dm01125716.pdf) | DS14791 Rev 10, 2026-08-04 | Introduction, device configuration tables, functional overview, electrical conditions and revision history; separate reference-manual and errata destinations. | Retain Mini's configuration/functional/electrical separation and source links. Do not copy device limits, part numbers or qualification claims. |
|
||||
| [ESP32-P4 datasheet](https://documentation.espressif.com/esp32-p4_datasheet_en.html) | ESP32-P4 Series Datasheet v0.7, 2026-07-14 | Series/chip revision, peripheral pin assignment, document status definitions and related-document navigation. | Retain profile-specific availability and pad constraints. Improve links in the existing document map; Mini's DRAFT status remains independently defined. |
|
||||
| [RP2350 datasheet](https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf) | RP2350 Datasheet, build-date 2025-07-29, build-version `d126e9e-clean` | Integrated programming reference; separate hardware and documentation revision histories; errata identify affected revisions, workaround and fix status. | Retain the full Mini reference and distinguish publication corrections, implementation limitations and missing evidence. Do not describe a documented workaround or wording correction as a hardware fix. |
|
||||
|
||||
## Source/specification discrepancies
|
||||
## Current implementation and document assessment
|
||||
|
||||
- `docs/ip/apu.md` describes sixteen KWS technology-macro banks, while
|
||||
`apu_kws_sram_client.sv` still uses inferred storage with combinational reads.
|
||||
The datasheet retains the implementation's logical-versus-physical distinction.
|
||||
Reconcile the hardware specification or implement/verify the macro change in a
|
||||
separate hardware task.
|
||||
- Older NPU phase comments and some source-linked descriptions predate the enabled
|
||||
scheduler and capability returns. Publication facts follow the instantiated
|
||||
parameters, register logic and actual compute/DMA path. Comment cleanup is
|
||||
recommended separately; no RTL edits are included here.
|
||||
- The dated GA2D and NPU verification narratives refer to reports not supplied
|
||||
for this publication's exact source revision. They are indexed as historical
|
||||
records, without promoting current per-IP verification or RTL maturity.
|
||||
| Area | Implementation and document assessment | This refresh | Specific recommendation |
|
||||
| --- | --- | --- | --- |
|
||||
| NPU | The existing chapter adequately covers the software-launchable eight-operator engine, private DMA/SRAM, compiler/HAL, descriptor/parameter layouts and normal/abort behavior. | Already covered; retain the chapter, geometry, static graph subset and numeric profile. No new NPU capability is introduced by this refresh. | Attach matching full-corpus and physical reports before claiming speedup, accuracy or timing closure. Distinguish the deployed burst limit from the reusable DMA default. |
|
||||
| APU formats and base programming | APUMC V1/V2, 4096-word current store, seven classes/62 opcodes, APUM model and 128-byte job format are already covered. | Already covered; retain the formats, register/HAL reference and default/P7 identity distinction. | Preserve format compatibility and separate the fixed APUM engine from NPU deployment. MP3 remains unsupported. |
|
||||
| APU summary, configuration and acceptance | Default KWS is off; P7 enables it with digest `0xF5005D7C`. The checked-in WAV/FLAC image is distinct from full production-job qualification. | Correct summary/body/table consistency while retaining the detailed formats and bare-metal acceptance reference. No native Linux ASoC support is claimed. | A smoke wrapper or missing-data early return is not the full accuracy or 60-second-per-scenario campaign. Keep actual workload, clock, source and result artifacts with any pass. |
|
||||
| GA2D | Existing FILL/COPY/CONVERT/opaque BLEND/A8 programming coverage and P6 workload/evidence boundaries are adequate. | Already covered; retain functional ABI and schema-3 performance-method descriptions. | The dated composition target and 48 MHz slow-corner timing were not met. Full-product closure and current-source measurements still require matching artifacts. |
|
||||
| Fabric, memory conversion and resources | Ten masters/resources, NPU master/resource 9, Resource ABI 1.2 and fragmented 64-to-32 long-burst conversion are already described. | Already covered; retain source-bound topology, matrices, circuits, credits and lifecycle references. | Preserve permission, source-ID and boundary rules. Burst admission is not a throughput guarantee. |
|
||||
| Address/register/IRQ/pad inventories | Existing generation and field-reference mechanisms cover their declared scope, including the independent NPU chapter. | Already covered; retain inventories, instance distinctions and stable anchors. Correct mailbox-purpose summaries from the actual register offsets and HAL/RTL producer paths. | Keep chapter, feature, register, diagram and API coverage synchronized. NPU has no implied new external pins. |
|
||||
| HP boot, mailbox and Linux runtime | The actual `hp_boot` terminal sequence extends beyond initial ready through GA2D ownership/result, cache-clean acknowledgement, HP-held state and return to LP. NPU handoffs are conditional on the P5/P6 acceptance definitions. | Correct shortened boot/recovery summaries, polling units, mailbox-purpose tables and stage-qualified diagrams. Distinguish generic `HP_LINUX_READY` text from the selected runtime. | The supplied Linux rootfs sends initial ready but lacks the later GA2D/cache-clean service. Record that delivery gap; freestanding acceptance behavior does not establish complete Linux integration. |
|
||||
| Cache handoff, ownership and recovery | Existing non-coherent buffer ownership, clean/invalidate and stop/drain references are adequate. | Already covered; retain these rules and align the boot-specific terminal/failure sequence with them. | Do not reuse buffers before terminal/drain handoff. The failure helper requests reset only before GA2D has been handed to HP; do not generalize an unconditional reset policy. |
|
||||
| Interface, format and memory budgeting | Mode exclusions, byte packing, pitches, NPU INT8 preprocessing, CPU-finalizer boundaries and buffer accounting are already covered. | Already covered; retain the existing tables and examples. | Check byte order, zero points, allocation/stride and producer/consumer lifetimes. Shared memory does not convert formats; missing ELF/MAP or high-water evidence remains unprovided. |
|
||||
| Electrical, package, thermal, reliability and ordering | Chapter structure and evidence requirements are complete; measured product values are not. | Structure adequate; retain existing placeholders without adding duplicate chapters. Evidence remains missing. | Supply process/package/corner/board/instrument/workload evidence. Do not substitute target clocks, analytic peaks or commercial-device limits. |
|
||||
| Development environment and maintenance | Current repository sources define the shared Linux environment, Python 3.10 Docker/Nix choices, the locked SBT tool, Java 17 requirement and activation-script handling. | Update development instructions and source references; link contribution/Git rules in the publication guide. | Follow the committed bootstrap and dependency lock. Environment availability does not establish a firmware, simulator or physical pass. |
|
||||
| Release evidence | Current CI, prior local tests, historical narratives and exact-profile IP reports have different scopes. | Refresh complete-SHA/UTC CI observations and preserve job/step/runtime-stage status, including pending, failed and skipped work. Previous local test totals remain historical. | Refresh before delivery. A workflow verdict cannot replace the original scoped report, and missing artifacts cannot be reconstructed from prose as current passes. |
|
||||
| Document navigation and norms | The existing nine-question document map and frozen 109-entry structure are sufficient. | Link Reading this datasheet to the existing map and its nine rows to existing internal anchors. Separate lasting rules from this round's source/baseline/marker record. | Retain one navigator and stable chapter destinations. Verify links after layout; do not add a second guide or restructure adequate chapters. |
|
||||
|
||||
## Source/specification discrepancies and follow-up
|
||||
|
||||
- [APU specification](../../docs/ip/apu.md) describes sixteen KWS technology-macro
|
||||
banks, while [the SRAM client](../../rtl/ip/multimedia/apu_kws_sram_client.sv)
|
||||
uses inferred storage with combinational reads. Preserve the logical/physical
|
||||
distinction in the datasheet. Reconcile the engineering contract or implement
|
||||
and verify the macro change as a separate hardware task.
|
||||
- Older NPU phase comments and some descriptions predate the enabled scheduler
|
||||
and capability returns. Keep publication claims tied to instantiated parameters,
|
||||
register logic and the compute/DMA path. Clean up stale engineering comments
|
||||
separately; this publication refresh does not edit RTL.
|
||||
- [HP boot orchestration](../../app/apps/hp_boot/main.c),
|
||||
[mailbox HAL](../../crt/src/hal/hp_mailbox.c) and
|
||||
[Linux ready publisher](../../app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp)
|
||||
define distinct parts of the handoff. Document the absent later Linux service
|
||||
explicitly. A future Linux integration task must supply and verify the GA2D,
|
||||
cache-clean and ownership protocol rather than infer it from the initial marker.
|
||||
- Dated GA2D/NPU verification narratives lack attached reports for this exact
|
||||
publication revision. Keep them historical, with the report/profile/stage
|
||||
requirements visible. Obtain original artifacts or execute an appropriately
|
||||
scoped campaign before updating current per-IP verification or RTL maturity.
|
||||
- [Development environment](../../docs/development-environment.md) and its
|
||||
[bootstrap](../../scripts/development_environment.py) are the source of truth
|
||||
for host requirements. Documentation of Python 3.10 and activation-file mode
|
||||
`0644` does not establish a successful Docker, Nix or EDA run.
|
||||
|
||||
The [chapter review](chapter-review.md) covers all **109 frozen entries / 42 IP
|
||||
chapters**, classifies each disposition and recommendation, and binds final page
|
||||
numbers to the delivered PDF. Document completeness is not protocol compliance,
|
||||
physical closure or silicon qualification. The independent unnumbered closing
|
||||
page remains outside that chapter contract.
|
||||
page remains outside that chapter contract. The final validation report records
|
||||
only checks actually executed for this refresh and identifies all unrun gates.
|
||||
@@ -1,201 +1,202 @@
|
||||
{
|
||||
"uart": [
|
||||
"64-byte TX and RX FIFOs; fractional baud-rate generator.",
|
||||
"**64-byte TX and RX FIFOs**; fractional baud-rate generator.",
|
||||
"5-8 data bits, parity, break, loopback and receive diagnostics.",
|
||||
"UART0 connects DMA and RTS/CTS; UART1 has its own integration limits."
|
||||
],
|
||||
"i2c": [
|
||||
"Two controller instances with 7-bit and 10-bit addressing.",
|
||||
"Two controller instances with **7-bit and 10-bit addressing**.",
|
||||
"Sixteen-entry command/RX queues, repeated START and clock stretching.",
|
||||
"Arbitration detection, bounded recovery and DMA pacing."
|
||||
],
|
||||
"i2s": [
|
||||
"Stereo master TX/RX with independent audio clock.",
|
||||
"**Stereo master TX/RX** with independent audio clock.",
|
||||
"16/24-bit and 48/96 kHz presets; programmable clock division.",
|
||||
"32-bit streams and CDC FIFOs; no slave, TDM or PDM mode."
|
||||
],
|
||||
"ws2812": [
|
||||
"24-bit GRB transmission on one GPIO alternate function.",
|
||||
"**24-bit GRB** transmission on one GPIO alternate function.",
|
||||
"Sixteen-word FIFO, frame length and programmable pulse/reset timings.",
|
||||
"Explicit underflow, abort and completion reporting."
|
||||
],
|
||||
"timer": [
|
||||
"Two 32-bit general-purpose timers.",
|
||||
"**Two 32-bit** general-purpose timers.",
|
||||
"16-bit prescalers and two compare channels per instance.",
|
||||
"Periodic/one-shot modes, count direction and debug freeze."
|
||||
],
|
||||
"gpio": [
|
||||
"32 bidirectional GPIOs with administration and restricted user windows.",
|
||||
"**32 bidirectional GPIOs** with administration and restricted user windows.",
|
||||
"Atomic output commands, open drain, filtering and per-pin interrupts.",
|
||||
"Alternate-function ownership, guard cycles and irreversible locks."
|
||||
],
|
||||
"clint": [
|
||||
"Per-hart software interrupts and 64-bit timer compare.",
|
||||
"Per-hart software interrupts and **64-bit timer compare**.",
|
||||
"Shared 64-bit timebase with RV32 word access.",
|
||||
"One management hart slot in the reference integration."
|
||||
],
|
||||
"aclint": [
|
||||
"Two addressable hart slots; HP consumes slot 1.",
|
||||
"Two addressable hart slots; **HP consumes slot 1**.",
|
||||
"Machine software and timer interrupts for the HP subsystem.",
|
||||
"Separate address window from management CLINT."
|
||||
],
|
||||
"dma": [
|
||||
"Eight channel contexts share a 32-bit AXI master.",
|
||||
"**Eight channel contexts** share a 32-bit AXI master.",
|
||||
"Direct and linked-list 64-byte TCD operation.",
|
||||
"Up to 16-beat bursts and selected AXI4-Stream endpoints."
|
||||
],
|
||||
"sysctrl": [
|
||||
"Root-managed configuration, HP lifecycle and clock requests.",
|
||||
"**Root-managed** configuration, HP lifecycle and clock requests.",
|
||||
"Sticky first-fault capture and performance snapshots.",
|
||||
"Sticky firmware test result and RTC wake observation."
|
||||
],
|
||||
"psram": [
|
||||
"Four ESP-PSRAM64H devices addressable through a 32 MiB window.",
|
||||
"Four ESP-PSRAM64H devices addressable through a **32 MiB window**.",
|
||||
"Device-specific 4-bit SDR SPI/QPI protocol.",
|
||||
"Separate APB management, recovery and timing configuration."
|
||||
],
|
||||
"sdram": [
|
||||
"Fixed 64 MiB, x16 SDR geometry with bank/row tracking.",
|
||||
"Fixed **64 MiB, x16 SDR** geometry with bank/row tracking.",
|
||||
"Burst-capable AXI frontend and periodic refresh.",
|
||||
"Programmable device timing in SDRAM-clock cycles."
|
||||
],
|
||||
"opipsram": [
|
||||
"One octal DDR memory interface and one selected protocol profile.",
|
||||
"One octal DDR memory interface and **one selected protocol profile**.",
|
||||
"OPI or single-clock HyperBus-style digital transaction model.",
|
||||
"Training/recovery controls; external-device qualification remains required."
|
||||
],
|
||||
"xpi": [
|
||||
"Four chip-select slots and 16 programmable LUT sequences.",
|
||||
"Four chip-select slots and **16 programmable LUT sequences**.",
|
||||
"SDR transfers over one, two or four data pads.",
|
||||
"Mapped reads, indirect PIO/DMA and automatic status polling."
|
||||
],
|
||||
"spisd": [
|
||||
"SD card SPI-mode command/data host.",
|
||||
"SD card **SPI-mode** command/data host.",
|
||||
"Private AXI DMA and scatter-gather descriptors.",
|
||||
"CRC, timeout, PIO and explicit card-command completion."
|
||||
],
|
||||
"sdio": [
|
||||
"Native one-bit/four-bit SDR operation.",
|
||||
"Native **one-bit/four-bit SDR** operation.",
|
||||
"SD Memory/SDIO command support with per-lane CRC.",
|
||||
"Private descriptor DMA and separate instance integration."
|
||||
],
|
||||
"jpeg": [
|
||||
"8-bit Baseline Sequential JPEG encode or decode.",
|
||||
"8-bit **Baseline Sequential JPEG** encode or decode.",
|
||||
"Images up to 2048 × 2048; modes are mutually exclusive.",
|
||||
"Private AXI64 DMA, direct jobs and a scatter-gather ring."
|
||||
],
|
||||
"apu": [
|
||||
"Coreless microcode sequencer with private DMA and local storage.",
|
||||
"WAV/FLAC job and stream infrastructure in the current capability word.",
|
||||
"MP3 is unsupported. Default PRODUCT disables KWS; the P7 acceptance profile advertises the fixed KWS model and ABI digest."
|
||||
"**Coreless microcode sequencer** with private DMA and local storage.",
|
||||
"WAV/FLAC jobs and streams are enabled in the deployed P5 path; their format, image and buffer requirements still apply.",
|
||||
"Fixed KWS is disabled in default PRODUCT and enabled by the P7 acceptance profile with its own ABI digest.",
|
||||
"MP3 is unsupported. Advertised capabilities do not establish full-corpus, sustained-audio or production qualification."
|
||||
],
|
||||
"npu": [
|
||||
"64 dense MACs, eight depthwise lanes and 64 KiB of private banked SRAM.",
|
||||
"**64 dense MACs**, eight depthwise lanes and 64 KiB of private banked SRAM.",
|
||||
"Eight INT8 operator classes, checked INT32 accumulation and profile-1 requantization.",
|
||||
"HP-native AXI64 DMA, 128-byte descriptors, APB4 control and owner-routed interrupts."
|
||||
],
|
||||
"dvp": [
|
||||
"8-bit parallel RGB565/YUV422 capture.",
|
||||
"**8-bit parallel RGB565/YUV422** capture.",
|
||||
"Programmable sync polarity, sample edge, crop and snapshot mode.",
|
||||
"Word packing with start-of-frame/end-of-line stream markers."
|
||||
],
|
||||
"usb2": [
|
||||
"Dual-role digital controller with external 8-bit ULPI PHY.",
|
||||
"Dual-role digital controller with **external 8-bit ULPI PHY**.",
|
||||
"Eight device endpoints, sixteen host channels and 16 KiB packet RAM.",
|
||||
"Descriptor DMA, IRQ/error retention and role-specific control."
|
||||
],
|
||||
"crypto": [
|
||||
"AES-128/192/256, SHA-224/256 and raw RSA-2048.",
|
||||
"AES-128/192/256, SHA-224/256 and **raw RSA-2048**.",
|
||||
"PIO and central-DMA streaming paths.",
|
||||
"Protected key/exponent readback; no claim of a secure key vault or certification."
|
||||
],
|
||||
"mailbox": [
|
||||
"Separate LP-to-HP and HP-to-LP payload banks.",
|
||||
"**Separate LP-to-HP and HP-to-LP** payload banks.",
|
||||
"Doorbells and independently masked interrupt state.",
|
||||
"Boot/lifecycle message exchange with explicit publication ordering."
|
||||
],
|
||||
"sram": [
|
||||
"32 KiB in the reference profile, using eight 4 KiB banks.",
|
||||
"**32 KiB in the reference profile**, using eight 4 KiB banks.",
|
||||
"Native AXI64 data frontend and byte-write support.",
|
||||
"APB discovery and performance counters."
|
||||
],
|
||||
"rtc": [
|
||||
"64-bit seconds and 1/256-second subsecond time.",
|
||||
"64-bit seconds and **1/256-second** subsecond time.",
|
||||
"Two alarms, periodic wake timer and signed calibration.",
|
||||
"Asynchronous command handoff and coherent snapshots."
|
||||
],
|
||||
"wdg": [
|
||||
"Independent-clock window watchdog.",
|
||||
"**Independent-clock** window watchdog.",
|
||||
"Two-key servicing, early warning and retained reset cause.",
|
||||
"Configuration locks and explicit debug policy."
|
||||
],
|
||||
"pwm": [
|
||||
"Two timers, four output channels and two operators.",
|
||||
"Two timers, **four output channels** and two operators.",
|
||||
"Shadow updates, fade/gamma, complementary/dead-time control.",
|
||||
"Fault handling and two capture inputs."
|
||||
],
|
||||
"crc": [
|
||||
"Programmable 7-, 8-, 16- or 32-bit CRC.",
|
||||
"Programmable **7-, 8-, 16- or 32-bit** CRC.",
|
||||
"Polynomial, initialization, reflection, byte order and final XOR controls.",
|
||||
"Byte-strobed input, running state and latched result."
|
||||
],
|
||||
"rng": [
|
||||
"Entropy-source qualification, FIFO and continuous health checks.",
|
||||
"**Entropy-source qualification**, FIFO and continuous health checks.",
|
||||
"Sticky errors, counters and bounded reads.",
|
||||
"The integrated deterministic source is unqualified for production entropy."
|
||||
],
|
||||
"ps2": [
|
||||
"Bidirectional open-drain host interface.",
|
||||
"Bidirectional **open-drain** host interface.",
|
||||
"Sixteen-entry RX/TX FIFOs and input filtering.",
|
||||
"Start/parity/stop checks, inhibit, timeouts and abort."
|
||||
],
|
||||
"archinfo": [
|
||||
"Read-only identity, configuration and topology discovery.",
|
||||
"**Read-only identity**, configuration and topology discovery.",
|
||||
"Generated build provenance and memory/technology capabilities.",
|
||||
"Lifecycle-gated device identity reads."
|
||||
],
|
||||
"resource": [
|
||||
"Ten independently managed shared resources; resource 8 owns the active P5 GA2D direct 2D engine and IRQ route.",
|
||||
"**Ten independently managed shared resources**; resource 8 owns the active P5 GA2D direct 2D engine and IRQ route.",
|
||||
"Owner locks, quiesce/reset and LP/HP IRQ routing.",
|
||||
"Explicit cache-maintenance handoff and sticky faults."
|
||||
],
|
||||
"monitor": [
|
||||
"Ten master and six target observation banks; bank 8 observes active P5 GA2D direct 2D traffic.",
|
||||
"**Ten master and six target observation banks**; bank 8 observes active P5 GA2D direct 2D traffic.",
|
||||
"Saturating counters, snapshots and outstanding high-water marks.",
|
||||
"Sticky first-fault attribution and live isolation status."
|
||||
],
|
||||
"extensions": [
|
||||
"Fixed EXT-H control, ownership, bounds and lifecycle.",
|
||||
"**Fixed EXT-H** control, ownership, bounds and lifecycle.",
|
||||
"AXI64 data-master interface with address-range checking.",
|
||||
"DMA service registers and timeout/fault reporting."
|
||||
],
|
||||
"ext-l": [
|
||||
"Fixed APB4 control and one interrupt.",
|
||||
"**Fixed APB4** control and one interrupt.",
|
||||
"Ownership, lock, quiesce and reset control.",
|
||||
"No data master, stream interface or local SRAM."
|
||||
],
|
||||
"rcu": [
|
||||
"AON-controlled requests and clock/reset policy.",
|
||||
"**AON-controlled** requests and clock/reset policy.",
|
||||
"Safe-source fallback, traffic drain and PLL qualification.",
|
||||
"Clock division and memory-pad mode through SYSCTRL."
|
||||
],
|
||||
"plic": [
|
||||
"32 source IDs, with source 0 reserved.",
|
||||
"32 source IDs, with **source 0 reserved**.",
|
||||
"Two delivery contexts: machine and supervisor.",
|
||||
"Priorities, masks, threshold and claim/complete semantics."
|
||||
],
|
||||
"mpw-timer": [
|
||||
"MPW-selectable timer and divider.",
|
||||
"**MPW-selectable** timer and divider.",
|
||||
"Small register window and user-GPIO output.",
|
||||
"No PRODUCT instantiation or dedicated IRQ claim."
|
||||
],
|
||||
"mpw-gpio": [
|
||||
"MPW-selectable user GPIO data and enables.",
|
||||
"**MPW-selectable** user GPIO data and enables.",
|
||||
"Readback of the shared user-GPIO input bus.",
|
||||
"Selection and pad ownership remain root-controlled."
|
||||
],
|
||||
"ga2d": [
|
||||
"P5 direct single-job FILL, COPY, CONVERT and opaque alpha BLEND.",
|
||||
"P5 **direct single-job** FILL, COPY, CONVERT and opaque alpha BLEND.",
|
||||
"RGB565/RGB888/XRGB8888/ARGB8888 color surfaces; A8 foreground mask.",
|
||||
"Private AXI64 master with pitch and byte-edge handling, owner-routed IRQ and retained error/counter snapshots.",
|
||||
"No descriptor queue, scaling, rotation, transparent-background blend or Linux graphics driver."
|
||||
|
||||
@@ -398,7 +398,7 @@
|
||||
"rtl/ip/multimedia/apu_reg.sv",
|
||||
"rtl/ip/multimedia/apb4_apu.sv"
|
||||
],
|
||||
"summary": "Partially implemented coreless audio subsystem; production codec jobs remain disabled."
|
||||
"summary": "Coreless audio subsystem with enabled WAV/FLAC jobs; fixed KWS is P7-configured, MP3 is unsupported, and production qualification remains incomplete."
|
||||
},
|
||||
{
|
||||
"id": "crypto",
|
||||
|
||||
@@ -21,9 +21,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/xpi.c",
|
||||
"api": [
|
||||
@@ -88,9 +88,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/spisd.c",
|
||||
"api": [
|
||||
@@ -154,9 +154,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/sdio.c",
|
||||
"api": [
|
||||
@@ -218,9 +218,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/sram.c",
|
||||
"api": [
|
||||
@@ -260,9 +260,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/psram.c",
|
||||
"api": [
|
||||
@@ -326,9 +326,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/opipsram.c",
|
||||
"api": [
|
||||
@@ -391,9 +391,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/sdram.c",
|
||||
"api": [
|
||||
@@ -456,9 +456,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/gpio.c",
|
||||
"api": [
|
||||
@@ -524,9 +524,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/dma.c",
|
||||
"api": [
|
||||
@@ -586,9 +586,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/timer.c",
|
||||
"api": [
|
||||
@@ -650,9 +650,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/rtc.c",
|
||||
"api": [
|
||||
@@ -716,9 +716,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Configure prescale, reload, window and warning policy while inactive; lock only after validation.",
|
||||
"Start once, then use the required two-key service inside the allowed window with bounded completion checks.",
|
||||
"An APB reset does not stop the independent core. Inspect the retained cause after recovery."
|
||||
"Configure prescale, reload, window and warning policy **while inactive**; lock only after validation.",
|
||||
"Start once, then use the required **two-key service** inside the allowed window with bounded completion checks.",
|
||||
"An **APB reset does not stop** the independent core. Inspect the retained cause after recovery."
|
||||
],
|
||||
"flow": [
|
||||
"Service key writes",
|
||||
@@ -748,9 +748,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/pwm.c",
|
||||
"api": [
|
||||
@@ -812,9 +812,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/uart.c",
|
||||
"api": [
|
||||
@@ -877,9 +877,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/i2c.c",
|
||||
"api": [
|
||||
@@ -941,9 +941,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/ws2812.c",
|
||||
"api": [
|
||||
@@ -1007,9 +1007,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/ps2.c",
|
||||
"api": [
|
||||
@@ -1075,9 +1075,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/usb2.c",
|
||||
"api": [
|
||||
@@ -1138,9 +1138,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Read a snapshot through core/archinfo.h and validate build identity before using configuration-dependent drivers.",
|
||||
"Use discovered memory/topology/technology capabilities.",
|
||||
"Read device identity only when its lifecycle gate permits it; the current top-level wiring does not provision a valid unique device ID."
|
||||
"Read a snapshot through core/archinfo.h and **validate build identity** before using configuration-dependent drivers.",
|
||||
"Use **discovered memory/topology/technology capabilities**.",
|
||||
"Read device identity only when its lifecycle gate permits it; the current top-level wiring **does not provision a valid unique device ID**."
|
||||
],
|
||||
"example_file": "publications/examples/archinfo.c",
|
||||
"api": [
|
||||
@@ -1178,9 +1178,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/sysctrl.c",
|
||||
"api": [
|
||||
@@ -1242,9 +1242,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/clint.c",
|
||||
"api": [
|
||||
@@ -1296,9 +1296,9 @@
|
||||
"Each 64-bit timer value is accessed as two 32-bit words. Use the retry and safe compare-update sequences below. The HP boot configuration uses a 1 MHz reference timebase; changing a CPU PLL setting does not redefine this reference."
|
||||
],
|
||||
"software_steps": [
|
||||
"HP consumes hart slot 1 of the two-slot window. Do not use a management-CLINT base-address helper.",
|
||||
"Read high/low/high and retry if the high words differ when a coherent RV32 time value is required.",
|
||||
"Update compare using the safe high/low sequence. OpenSBI may provide this service for HP software."
|
||||
"HP consumes **hart slot 1** of the two-slot window. Do not use a management-CLINT base-address helper.",
|
||||
"Read **high/low/high and retry** if the high words differ when a coherent RV32 time value is required.",
|
||||
"Update compare using the **safe high/low sequence**. OpenSBI may provide this service for HP software."
|
||||
],
|
||||
"flow": [
|
||||
"Reference ticks / MSIP",
|
||||
@@ -1322,9 +1322,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Program source priority, the machine/supervisor context enable and threshold.",
|
||||
"Read CLAIM_COMPLETE once per claim. Zero means no eligible source; a nonzero ID claims that source.",
|
||||
"Service the device cause, then write the claimed ID to the same context to complete it. A still-active level can pend again."
|
||||
"Program source priority, the machine/supervisor **context enable and threshold**.",
|
||||
"Read CLAIM_COMPLETE **once per claim**. Zero means no eligible source; a nonzero ID claims that source.",
|
||||
"Service the device cause, then write the claimed ID to the **same context** to complete it. A still-active level can pend again."
|
||||
],
|
||||
"flow": [
|
||||
"External IRQ levels",
|
||||
@@ -1347,9 +1347,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/mailbox.c",
|
||||
"api": [
|
||||
@@ -1404,9 +1404,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/resource.c",
|
||||
"api": [
|
||||
@@ -1462,9 +1462,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/monitor.c",
|
||||
"api": [
|
||||
@@ -1526,9 +1526,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/i2s.c",
|
||||
"api": [
|
||||
@@ -1590,9 +1590,9 @@
|
||||
],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/dvp.c",
|
||||
"api": [
|
||||
@@ -1654,9 +1654,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/jpeg.c",
|
||||
"api": [
|
||||
@@ -1713,7 +1713,8 @@
|
||||
"function_sections": [],
|
||||
"software_sections": [],
|
||||
"notes": [
|
||||
"The default product capability word remains 0x000001BD until every P7/P8 release gate passes. The dedicated P7 evidence profile uses 0x000001FD for WAV, FLAC, private DMA, ring, stream, KWS, sequencer and resampler; MP3 remains clear with deferred P6.",
|
||||
"The deployed P5 register, loader and sequencer paths enable WAV/FLAC jobs. Default PRODUCT advertises 0x000001BD with KWS disabled; the dedicated P7 acceptance profile advertises 0x000001FD with fixed-model KWS and ABI digest 0xF5005D7C. MP3 remains unsupported in both configurations.",
|
||||
"Capability and ABI identities describe the selected implementation. Full-corpus codec/KWS accuracy, sustained-audio acceptance and production qualification require their own matching reports; none is implied by enabling the P7 configuration.",
|
||||
"LP loads a bounded APUMC image before submitting work. Expanded P5 RTL has 4096 64-bit control-store words (32 KiB), CAPABILITY1=0x01827020 and APB version 1.1 while retaining APUMC V1 image compatibility.",
|
||||
"The loader checks header, ABI, bounds, entry descriptors and CRC before publishing valid/lock state. Rejected or aborted loads must leave stale instructions unexecutable.",
|
||||
"Direct jobs use JOB_* staging registers; ring jobs use descriptor ownership and producer/consumer rules. Buffer limits, codec entry bounds, ownership, quiesce and transport completion participate in admission and termination.",
|
||||
@@ -1721,11 +1722,11 @@
|
||||
"On a fault, inspect retained stage/address/detail and consumed/produced counts, acknowledge the correct IRQ causes, and stop or reset the appropriate lifecycle level before reusing buffers."
|
||||
],
|
||||
"software_steps": [
|
||||
"Probe information and capability through rs_apu_probe; reject codecs and formats not advertised by this snapshot.",
|
||||
"Obtain ownership and configure allowed buffer ranges. Publish an aligned image and call rs_apu_microcode_load with a bounded timeout.",
|
||||
"Check successful image validation before configuring a direct job or publishing ring descriptors. Set rate/channel/format expectations and valid input/output ranges.",
|
||||
"Use the job/ring APIs declared in apu.h with the required fences and cache maintenance.",
|
||||
"Wait for a terminal result and inspect counts, errors and IRQs. Successful transport alone does not establish full codec qualification."
|
||||
"Probe information and capability through rs_apu_probe; **reject codecs and formats not advertised** by this snapshot.",
|
||||
"**Obtain ownership** and configure allowed buffer ranges. Publish an aligned image and call rs_apu_microcode_load with a bounded timeout.",
|
||||
"Check **successful image validation** before configuring a direct job or publishing ring descriptors. Set rate/channel/format expectations and valid input/output ranges.",
|
||||
"Use the job/ring APIs declared in apu.h with the required **fences and cache maintenance**.",
|
||||
"Wait for a **terminal result** and inspect counts, errors and IRQs. Successful transport alone does not establish full codec qualification."
|
||||
],
|
||||
"example_file": "publications/examples/apu.c",
|
||||
"api": [
|
||||
@@ -1787,11 +1788,11 @@
|
||||
"All APB writes require full word strobes. Unknown offsets, reserved-bit violations, busy configuration changes and disallowed START commands complete with PSLVERR without the prohibited side effect."
|
||||
],
|
||||
"software_steps": [
|
||||
"Read identity, numeric profile, EXECUTION_READY and required operator bits before preparing a model. Use only the compiler-supported static integer graph subset.",
|
||||
"Establish Resource Controller ownership, allowed noncacheable DMA ranges and buffer lifetime. Clean CPU-produced descriptors/parameters/inputs and fence before START; the low-level HAL does not do this automatically.",
|
||||
"Clear the previous terminal IRQ, then submit the aligned descriptor list with a job token and nonzero hardware watchdog. Wait for the matching token with a bounded software polling budget.",
|
||||
"After DONE, snapshot counters and invalidate destination cache blocks before CPU consumption. CPU preprocessing and terminal Softmax are outside NPU execution time.",
|
||||
"On software timeout keep buffers owned by the device. Abort and wait for terminal/drained state; rs_npu_abort_wait reports ABORTED through RS_EIO. Capture fault and recovery generation before reset or reuse."
|
||||
"Read identity, numeric profile, EXECUTION_READY and required operator bits before preparing a model. Use only the compiler-supported **static integer graph subset**.",
|
||||
"Establish Resource Controller ownership, allowed noncacheable DMA ranges and buffer lifetime. Clean CPU-produced descriptors/parameters/inputs and **fence before START**; the low-level HAL does not do this automatically.",
|
||||
"Clear the previous terminal IRQ, then submit the aligned descriptor list with a job token and nonzero hardware watchdog. Wait for the **matching token** with a bounded software polling budget.",
|
||||
"After DONE, snapshot counters and **invalidate destination cache blocks** before CPU consumption. CPU preprocessing and terminal Softmax are outside NPU execution time.",
|
||||
"On software timeout **keep buffers owned by the device**. Abort and wait for terminal/drained state; rs_npu_abort_wait reports ABORTED through RS_EIO. Capture fault and recovery generation before reset or reuse."
|
||||
],
|
||||
"api": [
|
||||
{
|
||||
@@ -1859,9 +1860,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/crypto.c",
|
||||
"api": [
|
||||
@@ -1920,9 +1921,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/crc.c",
|
||||
"api": [
|
||||
@@ -1982,9 +1983,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/rng.c",
|
||||
"api": [
|
||||
@@ -2044,9 +2045,9 @@
|
||||
"software_sections": [],
|
||||
"notes": [],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"example_file": "publications/examples/extensions.c",
|
||||
"api": [
|
||||
@@ -2106,9 +2107,9 @@
|
||||
"Both demo IPs complete APB access with PREADY=1 and PSLVERR=0. Only address bits 7:0 are decoded, so the local register pattern aliases every 256 bytes. Undefined reads return zero and undefined writes have no effect. These legacy blocks ignore PSTRB; software must use aligned full-word accesses. Neither block has a FIFO, DMA engine or dedicated interrupt."
|
||||
],
|
||||
"software_steps": [
|
||||
"Run only with the committed MPW configuration and a board-safe user-GPIO ownership mask. The PRODUCT user-IP aperture does not instantiate this selectable demo.",
|
||||
"Probe the expected slot and check its identifier before accessing local registers; the probe selects that slot through SYSCTRL. Check every returned status.",
|
||||
"Use the sequence below. This legacy block has no completion interrupt or local abort command; GPIO recovery clears OE, and timer recovery uses root reset/selection under the board ownership policy."
|
||||
"Run only with the **committed MPW configuration** and a board-safe user-GPIO ownership mask. The PRODUCT user-IP aperture does not instantiate this selectable demo.",
|
||||
"Probe the expected slot and check its identifier before accessing local registers; the probe selects that slot through SYSCTRL. **Check every returned status**.",
|
||||
"Use the sequence below. This legacy block has **no completion interrupt or local abort command**; GPIO recovery clears OE, and timer recovery uses root reset/selection under the board ownership policy."
|
||||
],
|
||||
"flow": [
|
||||
"User clock",
|
||||
@@ -2148,9 +2149,9 @@
|
||||
"Both demo IPs complete APB access with PREADY=1 and PSLVERR=0. Only address bits 7:0 are decoded, so the local register pattern aliases every 256 bytes. Undefined reads return zero and undefined writes have no effect. These legacy blocks ignore PSTRB; software must use aligned full-word accesses. Neither block has a FIFO, DMA engine or dedicated interrupt."
|
||||
],
|
||||
"software_steps": [
|
||||
"Run only with the committed MPW configuration and a board-safe user-GPIO ownership mask. The PRODUCT user-IP aperture does not instantiate this selectable demo.",
|
||||
"Probe the expected slot and check its identifier before accessing local registers; the probe selects that slot through SYSCTRL. Check every returned status.",
|
||||
"Use the sequence below. This legacy block has no completion interrupt or local abort command; GPIO recovery clears OE, and timer recovery uses root reset/selection under the board ownership policy."
|
||||
"Run only with the **committed MPW configuration** and a board-safe user-GPIO ownership mask. The PRODUCT user-IP aperture does not instantiate this selectable demo.",
|
||||
"Probe the expected slot and check its identifier before accessing local registers; the probe selects that slot through SYSCTRL. **Check every returned status**.",
|
||||
"Use the sequence below. This legacy block has **no completion interrupt or local abort command**; GPIO recovery clears OE, and timer recovery uses root reset/selection under the board ownership policy."
|
||||
],
|
||||
"flow": [
|
||||
"User data/output enable",
|
||||
@@ -2190,9 +2191,9 @@
|
||||
"The RCU is controlled through SYSCTRL registers; it does not own another APB address aperture. Clock roots, divisions, safe fallback and memory-pad mode remain root-management operations."
|
||||
],
|
||||
"software_steps": [
|
||||
"Inspect clock status and capability; the reference profile has no enabled PLL macro.",
|
||||
"Use rs_clock_set_frequency with a bounded timeout; traffic drain and safe-source sequencing remain controller responsibilities.",
|
||||
"Check completion and sticky faults. Retain the safe source after a failed change."
|
||||
"Inspect clock status and capability; the reference profile has **no enabled PLL macro**.",
|
||||
"Use rs_clock_set_frequency with a **bounded timeout**; traffic drain and safe-source sequencing remain controller responsibilities.",
|
||||
"Check completion and sticky faults. **Retain the safe source** after a failed change."
|
||||
],
|
||||
"reference": "docs/pll-clock-control.md",
|
||||
"register_family": "sysctrl",
|
||||
@@ -2236,9 +2237,9 @@
|
||||
"EXT-L exposes control and interrupt capability without a data master, stream interface or local SRAM. EXT-H-only data and DMA controls are not supported in this slot."
|
||||
],
|
||||
"software_steps": [
|
||||
"Confirm the instance base address, active clock/reset domain and resource owner before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. Do not write configuration fields while an operation forbids it.",
|
||||
"Use bounded completion checks; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
"Confirm the instance base address, **active clock/reset domain and resource owner** before accessing registers.",
|
||||
"Read the identification/capability registers where present, then follow the configuration and transfer sequence above. **Do not write configuration fields while an operation forbids it**.",
|
||||
"Use **bounded completion checks**; inspect and clear the documented event/error fields. Transfer shared-buffer ownership with the required fences and cache maintenance."
|
||||
],
|
||||
"reference": "docs/ip/extensions.md",
|
||||
"register_family": "extensions",
|
||||
@@ -2291,12 +2292,12 @@
|
||||
"There is no descriptor, ring or queue submission, scaling, rotation, negative pitch, YUV/CLUT renderer, hardware cache coherence or native Linux graphics driver. The presence of P5 tests and firmware scenarios does not establish Phase 6 system-performance or physical qualification."
|
||||
],
|
||||
"software_steps": [
|
||||
"Read capability/format words, select an implemented operation, and obtain resource ownership. Confirm DATA_READY and that no recovery is pending.",
|
||||
"Allocate disjoint bounded surfaces, except the explicitly supported equal background/destination BLEND case. Validate pitch, format, dimensions, alignment and addresses with rs_ga2d_job_validate.",
|
||||
"Clean CPU-produced inputs as required, prepare destination ownership, and issue the required memory fence before configuring the job. Keep surfaces and configuration stable while active.",
|
||||
"Call rs_ga2d_configure, then rs_ga2d_start. Use rs_ga2d_wait or the owner-routed IRQ; LP vector 32, external ordinal 30 and HP PLIC source 11 name different routing layers.",
|
||||
"Capture terminal status, first-error details and counter snapshots before acknowledging W1C IRQ causes. Invalidate a DMA-written destination before CPU consumption where its mapping is cached.",
|
||||
"A polling timeout does not prove hardware idle. Use rs_ga2d_abort_wait to stop/drain accepted traffic, inspect recovery_required, and perform the documented resource/bridge rearm when required. A soft reset must not be used to discard in-flight bus obligations."
|
||||
"Read capability/format words, select an implemented operation, and obtain resource ownership. Confirm DATA_READY and that **no recovery is pending**.",
|
||||
"Allocate **disjoint bounded surfaces**, except the explicitly supported equal background/destination BLEND case. Validate pitch, format, dimensions, alignment and addresses with rs_ga2d_job_validate.",
|
||||
"Clean CPU-produced inputs as required, prepare destination ownership, and issue the required memory fence before configuring the job. Keep surfaces and configuration **stable while active**.",
|
||||
"Call rs_ga2d_configure, then rs_ga2d_start. Use rs_ga2d_wait or the **owner-routed IRQ**; LP vector 32, external ordinal 30 and HP PLIC source 11 name different routing layers.",
|
||||
"Capture terminal status, first-error details and counter snapshots **before acknowledging** W1C IRQ causes. Invalidate a DMA-written destination before CPU consumption where its mapping is cached.",
|
||||
"A polling timeout **does not prove hardware idle**. Use rs_ga2d_abort_wait to stop/drain accepted traffic, inspect recovery_required, and perform the documented resource/bridge rearm when required. A soft reset must not be used to discard in-flight bus obligations."
|
||||
],
|
||||
"example_file": "publications/examples/ga2d.c",
|
||||
"api": [
|
||||
|
||||
@@ -3,9 +3,16 @@
|
||||
#import "diagram-packages.typ": circuit-diagram, binary-figures, storage-figures
|
||||
|
||||
#let inline(value) = {
|
||||
let parts=value.split("`")
|
||||
for (i,part) in parts.enumerate() {
|
||||
if calc.rem(i,2)==1 { code(part) } else { part.replace("**","") }
|
||||
// A deliberately limited inline grammar: explicit strong spans and raw code.
|
||||
// Code is opaque, including any literal asterisks it contains.
|
||||
let bold = false
|
||||
for (i,part) in value.split("`").enumerate() {
|
||||
if calc.rem(i,2)==1 { code(part) } else {
|
||||
for (j,piece) in part.split("**").enumerate() {
|
||||
if j>0 { bold = not bold }
|
||||
if bold { strong(piece) } else { piece }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -113,6 +120,7 @@
|
||||
}
|
||||
|
||||
#let ip-reference(id, family, depth, shared:none, legacy:none, register-family:none, software-note:none, functional-note:none, protocol-note:none) = {
|
||||
change-start("v05-emphasis-ip-"+id,"Selected feature, programming and limitation emphasis: "+upper(id))
|
||||
let chapter=data.chapters.at(family)
|
||||
let revised=id in ("sysctrl","resource","monitor","apu","i2s")
|
||||
if revised {change-start("dev-ip-"+id,chapter.title+" current implementation and register reference")}
|
||||
@@ -179,4 +187,5 @@
|
||||
source-note(chapter.reference,title:"Detailed interface contract and source provenance")
|
||||
}
|
||||
if revised {change-end("dev-ip-"+id)}
|
||||
change-end("v05-emphasis-ip-"+id)
|
||||
}
|
||||
@@ -10,6 +10,7 @@
|
||||
|
||||
==== Audio Processing Unit (APU, partial) <apu>
|
||||
|
||||
#change-start("v05-refresh-apu-chapter","Current codec availability and ordered APU acceptance")
|
||||
#ip("apu")
|
||||
|
||||
#ip-reference("apu","apu",4,functional-note:[
|
||||
@@ -20,8 +21,8 @@
|
||||
(([Control-store instructions],[#implementation.instruction_words / #implementation.maximum_instruction_words words],[#implementation.free_instruction_words words remain in the implemented V2 store.]),
|
||||
([Serialized image],[#implementation.bundle_bytes bytes],[Includes the header, entries, instructions and coefficient tables.]),
|
||||
([Coefficient/table payload],[#implementation.table_bytes bytes],[Separate from instruction-word capacity.]),
|
||||
([Entry roles],[WAV; reserved MP3 trap; FLAC],[MP3 is not a decoder implementation.]),
|
||||
([Qualification],[Static assembly only],[A valid image and capability bits do not establish corpus accuracy, sustained playback or physical signoff.])),
|
||||
([Entry roles],[WAV; reserved MP3 trap; FLAC],[*MP3 is not a decoder implementation*.]),
|
||||
([Qualification],[*Static assembly only*],[A valid image and capability bits do not establish corpus accuracy, sustained playback or physical signoff.])),
|
||||
widths:(1.1fr,0.85fr,2.05fr))
|
||||
APUMC V1 retains 2048-word limits and 11-bit control-flow PCs; V2 uses 4096-word limits and
|
||||
12-bit PCs. Both retain the common 64-bit instruction fields, seven classes and 62 defined
|
||||
@@ -63,4 +64,5 @@ image availability. KWS implementation exists but EnableP7 defaults to false in
|
||||
|
||||
])
|
||||
|
||||
#change-end("v05-refresh-apu-chapter")
|
||||
#context metadata((kind:"ip-end",id:"apu",page:here().page()))
|
||||
@@ -11,9 +11,9 @@
|
||||
#ip("archinfo")
|
||||
|
||||
#ip-reference("archinfo","archinfo",4,legacy:[
|
||||
Discovery registers report the generated build/configuration identity, topology, SRAM bytes
|
||||
Discovery registers report the *generated build/configuration identity*, topology, SRAM bytes
|
||||
and technology capabilities. Device-ID inputs are tied invalid and read-disabled in the
|
||||
current SoC integration; the document does not claim a provisioned unique silicon identity.
|
||||
current SoC integration; the document *does not claim a provisioned unique silicon identity*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"archinfo",page:here().page()))
|
||||
@@ -12,7 +12,7 @@
|
||||
|
||||
#ip-reference("clint","clint",4,legacy:[
|
||||
CLINT supplies machine software and timer interrupts for the management hart. The committed
|
||||
timebase is 1 MHz. It is separate from the HP local-interrupt window and from the PLIC external
|
||||
*timebase is 1 MHz*. It is *separate from the HP local-interrupt window* and from the PLIC external
|
||||
interrupt controller.
|
||||
])
|
||||
|
||||
|
||||
@@ -11,10 +11,10 @@
|
||||
#ip("crc")
|
||||
|
||||
#ip-reference("crc","crc",4,legacy:[
|
||||
CRC V2 supports 7-, 8-, 16- and 32-bit widths, programmable polynomial, initial/final XOR,
|
||||
CRC V2 supports *7-, 8-, 16- and 32-bit widths*, programmable polynomial, initial/final XOR,
|
||||
input/output reflection and byte order. Software or system DMA supplies data; the block has
|
||||
no private memory master or interrupt. CRC is a data-integrity primitive, not encryption or
|
||||
authentication. Firmware must use the parameters required by its file, packet or boot format.
|
||||
no private memory master or interrupt. CRC is a data-integrity primitive, *not encryption or
|
||||
authentication*. Firmware must use the parameters required by its file, packet or boot format.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"crc",page:here().page()))
|
||||
@@ -14,8 +14,8 @@
|
||||
|
||||
#ip-reference("crypto","crypto",4,legacy:[
|
||||
The engine provides PIO and central-DMA streaming for AES and SHA-2, plus raw RSA-2048 modular
|
||||
exponentiation. Software must supply protocol-level padding, key policy and validated operation
|
||||
parameters. This is not a claim of secure key storage, certified cryptography or side-channel
|
||||
exponentiation. Software must supply *protocol-level padding, key policy and validated operation
|
||||
parameters*. This is *not a claim of secure key storage*, certified cryptography or side-channel
|
||||
resistance. HP access is restricted by the management-only control contract.
|
||||
])
|
||||
|
||||
|
||||
@@ -11,10 +11,10 @@
|
||||
#ip("dvp")
|
||||
|
||||
#ip-reference("dvp","dvp",4,legacy:[
|
||||
The 8-bit parallel input supports RGB565 and YUV422, programmable sync polarity and sampling
|
||||
The *8-bit parallel input* supports RGB565 and YUV422, programmable sync polarity and sampling
|
||||
edge, snapshot/continuous capture and rectangular cropping. AXI4-Stream marks start-of-frame
|
||||
and end-of-line; central DMA moves capture data to memory. A maximum sensor resolution or frame
|
||||
rate requires a validated sensor, clock, buffer and memory-bandwidth configuration.
|
||||
rate requires a *validated sensor, clock, buffer and memory-bandwidth configuration*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"dvp",page:here().page()))
|
||||
@@ -11,9 +11,9 @@
|
||||
#ip("ext-h")
|
||||
|
||||
#ip-reference("ext-h","extensions",4,legacy:[
|
||||
EXT-H adds a native AXI64 data master with read/write address bounds, ownership and timeout
|
||||
EXT-H adds a *native AXI64 data master* with read/write address bounds, ownership and timeout
|
||||
handling. Its current capability declaration has no stream interface or local SRAM. It is a
|
||||
fixed product slot, not the legacy runtime IPSEL multiplexer.
|
||||
*fixed product slot*, not the legacy runtime IPSEL multiplexer.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"ext-h",page:here().page()))
|
||||
@@ -13,8 +13,8 @@
|
||||
#ip("ext-l")
|
||||
|
||||
#ip-reference("ext-l","ext-l",4,shared:"ext-h",register-family:"extensions",legacy:[
|
||||
EXT-L is a fixed APB4 control slot with one interrupt. Its current capability declaration has
|
||||
no data master, stream interface or local SRAM.
|
||||
EXT-L is a *fixed APB4 control slot* with one interrupt. Its current capability declaration has
|
||||
*no data master, stream interface or local SRAM*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"ext-l",page:here().page()))
|
||||
@@ -12,12 +12,12 @@
|
||||
|
||||
#ip-reference("gpio","gpio",3,legacy:[
|
||||
Software controls per-pin mode, output data, output enable, open-drain behavior, input filtering
|
||||
and interrupt configuration. Alternate-function and user-IP paths share the same 32 physical
|
||||
GPIOs. Atomic set/clear/toggle operations avoid software read-modify-write races.
|
||||
and interrupt configuration. Alternate-function and user-IP paths share the *same 32 physical
|
||||
GPIOs*. *Atomic set/clear/toggle operations* avoid software read-modify-write races.
|
||||
|
||||
==== System IO / Management Window
|
||||
The administration window owns pad mode, electrical controls, filters, user access masks and
|
||||
configuration locks. The user access mask resets to zero. Configuration ownership and lock
|
||||
configuration locks. The *user access mask resets to zero*. Configuration ownership and lock
|
||||
semantics apply to the single controller; this window is not a separate GPIO bank.
|
||||
|
||||
==== User Custom IO / User Window
|
||||
|
||||
@@ -11,14 +11,14 @@
|
||||
===== HP Local Interrupt Controller (ACLINT) <hp-aclint>
|
||||
|
||||
#let r=data.regions.find(r=>r.symbol=="HP_ACLINT")
|
||||
Base address: #code(r.base_hex). Window size: #r.size_label. HP software and timer interrupts; hart slot 1 is connected.
|
||||
Base address: #code(r.base_hex). Window size: #r.size_label. HP software and timer interrupts; *hart slot 1 is connected*.
|
||||
|
||||
|
||||
#ip-reference("hp-aclint","aclint",5,legacy:[
|
||||
|
||||
The HP ACLINT supplies local software and timer interrupts to VexiiRiscv. The PLIC
|
||||
handles external interrupt sources, including the separate mailbox doorbell. These
|
||||
controllers have distinct address windows and interrupt semantics.
|
||||
controllers have *distinct address windows and interrupt semantics*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"hp-aclint",page:here().page()))
|
||||
@@ -13,8 +13,8 @@
|
||||
#ip-reference("i2c","i2c",4,legacy:[
|
||||
Each instance has sixteen-entry command and receive FIFOs, 7/10-bit addresses, repeated START,
|
||||
clock stretching, arbitration-loss detection, filtering, bounded waits and bus recovery.
|
||||
GPIO7/8 ALT0 route I2C0; GPIO3/4 ALT1 route I2C1. External pull-ups and a validated board timing
|
||||
budget are required. The current IP is controller-mode, not an I2C target/slave peripheral.
|
||||
GPIO7/8 ALT0 route I2C0; GPIO3/4 ALT1 route I2C1. *External pull-ups* and a validated board timing
|
||||
budget are required. The current IP is *controller-mode, not an I2C target/slave peripheral*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"i2c",page:here().page()))
|
||||
@@ -17,9 +17,9 @@
|
||||
#ip("i2s")
|
||||
|
||||
#ip-reference("i2s","i2s",4,legacy:[
|
||||
The stereo master supports 16/24-bit and 48/96 kHz presets plus programmable clock dividers.
|
||||
The *stereo master* supports 16/24-bit and 48/96 kHz presets plus programmable clock dividers.
|
||||
TX/RX streams use 32-bit words and 128-word FIFOs. Configuration and sample CDC handle the
|
||||
independent audio clock. Slave, TDM and PDM modes are not advertised. A codec/DAC/ADC and
|
||||
independent audio clock. *Slave, TDM and PDM modes are not advertised*. A codec/DAC/ADC and
|
||||
board-level audio-clock qualification are external requirements.
|
||||
The wrapper exports the synchronized RX warm-flush state as #code("rx_flush_busy_o") to
|
||||
the APU integration. The internal KWS receive route and its flush/lifecycle coordination are
|
||||
|
||||
@@ -11,8 +11,8 @@
|
||||
#ip("jpeg")
|
||||
|
||||
#ip-reference("jpeg","jpeg",4,legacy:[
|
||||
The block implements 8-bit Baseline Sequential JPEG for images up to 2048 × 2048. Encoding and
|
||||
decoding are mutually exclusive in one instance. Direct jobs and a scatter-gather ring use a
|
||||
The block implements *8-bit Baseline Sequential JPEG* for images up to 2048 × 2048. Encoding and
|
||||
decoding are *mutually exclusive* in one instance. Direct jobs and a scatter-gather ring use a
|
||||
private 64-bit DMA master. Resource ownership, interrupts and bounded error completion are
|
||||
part of the integration. Progressive JPEG and a sustained video-rate claim are not specified.
|
||||
])
|
||||
|
||||
@@ -12,8 +12,8 @@
|
||||
|
||||
#ip-reference("monitor","monitor",4,legacy:[
|
||||
The monitor observes accepted requests, beats, waits, outstanding high-water marks, aging,
|
||||
timeouts, isolation and warm flushes. Saturating counters are read through explicit snapshots.
|
||||
Sticky first-fault attribution keeps source identity and decoded target information. Monitoring
|
||||
timeouts, isolation and warm flushes. Saturating counters are read through *explicit snapshots*.
|
||||
*Sticky first-fault attribution* keeps source identity and decoded target information. Monitoring
|
||||
does not alter arbitration or admission policy.
|
||||
])
|
||||
|
||||
|
||||
@@ -3,6 +3,6 @@
|
||||
#pagebreak(weak:true)
|
||||
#context metadata((kind:"ip-start",id:"mpw-gpio",page:here().page()))
|
||||
==== MPW User GPIO <mpw-gpio>
|
||||
This selected user IP uses the shared MPW user-IP window. The active selector determines which design responds; PRODUCT does not instantiate this selectable IP.
|
||||
This selected user IP uses the shared MPW user-IP window. The active selector determines which design responds; *PRODUCT does not instantiate this selectable IP*.
|
||||
#ip-reference("mpw-gpio","mpw-gpio",4)
|
||||
#context metadata((kind:"ip-end",id:"mpw-gpio",page:here().page()))
|
||||
@@ -3,6 +3,6 @@
|
||||
#pagebreak(weak:true)
|
||||
#context metadata((kind:"ip-start",id:"mpw-timer",page:here().page()))
|
||||
==== MPW User Timer <mpw-timer>
|
||||
This selected user IP uses the shared MPW user-IP window. The active selector determines which design responds; PRODUCT does not instantiate this selectable IP.
|
||||
This selected user IP uses the shared MPW user-IP window. The active selector determines which design responds; *PRODUCT does not instantiate this selectable IP*.
|
||||
#ip-reference("mpw-timer","mpw-timer",4)
|
||||
#context metadata((kind:"ip-end",id:"mpw-timer",page:here().page()))
|
||||
@@ -12,10 +12,10 @@
|
||||
|
||||
#ip-reference("opipsram","opipsram",5,legacy:[
|
||||
One controller supports a boot-selected octal DDR transaction profile or a single-clock
|
||||
HyperBus-style profile. Initialization locks the selected protocol until soft reset. The
|
||||
HyperBus-style profile. Initialization *locks the selected protocol until soft reset*. The
|
||||
128 MiB aperture is addressability, not a device-density commitment. QPI and OPI share memory
|
||||
pads and must not drive them concurrently.
|
||||
#note[This is a prototype interface. A specific 3.3 V OPI or single-clock HyperBus-style device
|
||||
pads and *must not drive them concurrently*.
|
||||
#note[This is a *prototype interface*. A specific 3.3 V OPI or single-clock HyperBus-style device
|
||||
still requires electrical, timing, board and silicon qualification. It is not a blanket claim
|
||||
of compatibility with every HyperBus device.]
|
||||
])
|
||||
|
||||
@@ -12,8 +12,8 @@
|
||||
|
||||
#ip-reference("ps2","ps2",4,legacy:[
|
||||
GPIO0/1 ALT1 route PS/2 clock/data. The integration binds input sensing and active-low drive
|
||||
behavior for an open-drain bus. External pull-ups are required. Before changing GPIO ownership,
|
||||
firmware disables the controller and confirms that both output enables are released.
|
||||
behavior for an open-drain bus. *External pull-ups are required*. Before changing GPIO ownership,
|
||||
firmware disables the controller and confirms that *both output enables are released*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"ps2",page:here().page()))
|
||||
@@ -11,8 +11,8 @@
|
||||
#ip("psram")
|
||||
|
||||
#ip-reference("psram","psram",5,legacy:[
|
||||
The QPI controller addresses four ESP-PSRAM64H devices, each 8 MiB. It uses four SDR data pins
|
||||
and device-specific initialization, recovery and restricted commands. It does not implement
|
||||
The QPI controller addresses *four ESP-PSRAM64H devices, each 8 MiB*. It uses four SDR data pins
|
||||
and *device-specific initialization*, recovery and restricted commands. It does not implement
|
||||
octal PSRAM, DDR/DTR, DQS or generic CPOL/CPHA selection. The QPI data port uses local
|
||||
AXI64-to-32 adaptation and an HP-to-memory clock crossing.
|
||||
])
|
||||
|
||||
@@ -14,8 +14,8 @@
|
||||
Four PWM outputs, two capture inputs, a fault input and a synchronization input are routed
|
||||
through the GPIO alternate-function matrix. The managed V2 implementation includes interrupt
|
||||
reporting and management-debug halt integration.
|
||||
Program divider and waveform parameters against the active peripheral clock; a register field
|
||||
width alone does not establish a qualified output frequency.
|
||||
Program divider and waveform parameters against the *active peripheral clock*; a register field
|
||||
width alone *does not establish a qualified output frequency*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"pwm",page:here().page()))
|
||||
@@ -11,8 +11,8 @@
|
||||
|
||||
|
||||
#ip-reference("rcu","rcu",4,shared:"sysctrl",register-family:"sysctrl",legacy:[
|
||||
RCU functionality is accessed through system control and the clock/reset subsystem rather
|
||||
than an additional standalone APB window. Clock switching, safe fallback and qualification
|
||||
RCU functionality is accessed through system control and the clock/reset subsystem *rather
|
||||
than an additional standalone APB window*. Clock switching, safe fallback and qualification
|
||||
limits are described in the Clock and Reset section.
|
||||
#source-note("docs/pll-clock-control.md")
|
||||
])
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
#ip("resource")
|
||||
|
||||
#ip-reference("resource","resource",4,legacy:[
|
||||
Ten resources are managed: central DMA, USB2, SDIO0, SDIO1, SPI-SD, EXT-H, JPEG,
|
||||
*Ten resources* are managed: central DMA, USB2, SDIO0, SDIO1, SPI-SD, EXT-H, JPEG,
|
||||
APU, GA2D and NPU. Resource ABI 1.2 reports ten slots. Resource 9 owns the native-HP
|
||||
NPU, including LP vector 33 / HP PLIC 12 steering. Resource 8 routes the GA2D
|
||||
its IRQ according to its current owner and controls its private AXI64 lifecycle.
|
||||
@@ -21,8 +21,8 @@ RGB565, RGB888, XRGB8888, and ARGB8888 are color surfaces; A8 is BLEND
|
||||
foreground-only. Snapshots, pitch, and byte edges remain available. It does not
|
||||
provide transparent-background/premultiplied-alpha modes, scaling, rendering,
|
||||
descriptor/ring/queue submission, hardware cache coherency, or a Linux graphics driver.
|
||||
Ownership changes require quiesce, completion of accepted traffic and cache-maintenance
|
||||
handoff. HP can inspect allowed status but cannot take over root writes. An ownership grant
|
||||
Ownership changes require *quiesce, completion of accepted traffic and cache-maintenance
|
||||
handoff*. HP can inspect allowed status but *cannot take over root writes*. An ownership grant
|
||||
does not bypass the target access policy or EXT-H address bounds.
|
||||
])
|
||||
|
||||
|
||||
@@ -11,9 +11,9 @@
|
||||
#ip("rng")
|
||||
|
||||
#ip-reference("rng","rng",4,legacy:[
|
||||
The integration supplies a deterministic diagnostic source with qualification deasserted.
|
||||
The controller must retain its fail-closed behavior for unqualified entropy. It cannot be
|
||||
used as a production cryptographic random source until a qualified PDK entropy source and
|
||||
The integration supplies a *deterministic diagnostic source* with qualification deasserted.
|
||||
The controller must retain its *fail-closed behavior* for unqualified entropy. It *cannot be
|
||||
used as a production cryptographic random source* until a qualified PDK entropy source and
|
||||
the associated validation are integrated.
|
||||
])
|
||||
|
||||
|
||||
@@ -12,11 +12,11 @@
|
||||
|
||||
#ip-reference("rtc","rtc",4,legacy:[
|
||||
RTC V2 provides a 64-bit Unix-epoch counter, 1/256-second resolution, two alarms, a periodic
|
||||
wake timer and smooth digital calibration. Time reads use an atomic snapshot. The engine uses
|
||||
wake timer and smooth digital calibration. Time reads use an *atomic snapshot*. The engine uses
|
||||
the independent audio input frequency selected by the profile rather than assuming a
|
||||
32.768 kHz crystal. RTC interrupt and wake outputs are distinct integration signals.
|
||||
#tbd[Battery-backed operation, oscillator accuracy and retention across loss of board power
|
||||
are not specified by the current digital integration.]
|
||||
are *not specified by the current digital integration*.]
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"rtc",page:here().page()))
|
||||
@@ -17,9 +17,9 @@
|
||||
#source-note("rtl/ip/storage/sdio_command.sv",title:"Command assembly and most-significant-bit-first transmission")
|
||||
]
|
||||
],legacy:[
|
||||
SDIO0 provides native SD command/data transfers and descriptor-driven DMA through I/O gateway A.
|
||||
SDIO0 provides *native SD command/data transfers* and descriptor-driven DMA through I/O gateway A.
|
||||
Its signals share the GPIO alternate-function matrix. The card, pull-ups, bus voltage and board
|
||||
timing are external integration requirements. Do not equate protocol support with a qualified
|
||||
timing are *external integration requirements*. Do not equate protocol support with a qualified
|
||||
card-speed grade. SDIO1 uses the same controller family with a separate instance and pad group.
|
||||
])
|
||||
|
||||
|
||||
@@ -11,9 +11,9 @@
|
||||
#ip("sdio1")
|
||||
|
||||
#ip-reference("sdio1","sdio",4,shared:"sdio0",legacy:[
|
||||
The second native SD instance uses dedicated clock, command and four data pads and is routed
|
||||
The second native SD instance uses *dedicated clock, command and four data pads* and is routed
|
||||
through I/O gateway B. Resource ownership controls DMA submission and LP/HP interrupt delivery.
|
||||
The dedicated pad group is intentionally unbound in the generic FPGA profile until board pin,
|
||||
The dedicated pad group is *intentionally unbound* in the generic FPGA profile until board pin,
|
||||
I/O-bank voltage and timing constraints are approved.
|
||||
])
|
||||
|
||||
|
||||
@@ -11,10 +11,10 @@
|
||||
#ip("sdram")
|
||||
|
||||
#ip-reference("sdram","sdram",5,legacy:[
|
||||
The fixed x16 SDR geometry has two bank bits, thirteen row bits and ten column bits. The
|
||||
The *fixed x16 SDR geometry* has two bank bits, thirteen row bits and ten column bits. The
|
||||
controller tracks open rows, accepts native bursts and exposes programmable timing values in
|
||||
SDRAM-clock cycles. AXI64 crosses into the stable memory domain before local 64-to-32 adaptation.
|
||||
Firmware must initialize the device and program timings for the fitted part before use.
|
||||
Firmware must initialize the device and *program timings for the fitted part before use*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"sdram",page:here().page()))
|
||||
@@ -11,9 +11,9 @@
|
||||
#ip("spisd")
|
||||
|
||||
#ip-reference("spisd","spisd",5,legacy:[
|
||||
The host controls SD cards in SPI mode and moves payloads through a private AXI4 master, routed
|
||||
The host controls SD cards in *SPI mode* and moves payloads through a private AXI4 master, routed
|
||||
through I/O gateway B. Resource ownership determines which hart receives its interrupt.
|
||||
The former 1 GiB memory-mapped card aperture is reserved; software must use command/data
|
||||
The *former 1 GiB memory-mapped card aperture is reserved*; software must use command/data
|
||||
operations. Card initialization, capacity discovery and supported transfer details belong to
|
||||
the SPI-SD contract, rather than fixed card-size claims in the feature list.
|
||||
])
|
||||
|
||||
@@ -13,11 +13,11 @@
|
||||
#ip("sram")
|
||||
|
||||
#ip-reference("sram","sram",5,legacy:[
|
||||
The reference profile selects eight 4 KiB banks for 32 KiB total. The configuration accepts
|
||||
The reference profile selects *eight 4 KiB banks for 32 KiB total*. The configuration accepts
|
||||
4, 16, 32, 64 or 128 KiB; only 32 KiB is selected by the committed product profiles.
|
||||
SRAM has a native AXI64/ID7 data interface in the HP domain and an APB4 configuration window.
|
||||
Technology macros and behavioral models are selected by the configuration. A larger configurable
|
||||
capacity is not a statement of qualified area, timing or yield.
|
||||
capacity is *not a statement of qualified area, timing or yield*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"sram",page:here().page()))
|
||||
@@ -13,8 +13,8 @@
|
||||
#ip-reference("sysctrl","sysctrl",4,legacy:[
|
||||
Root-controlled registers manage lifecycle and faults. Automated firmware reports completion
|
||||
through TEST_STATUS: bit 31 is valid, bit 0 is pass and bits 15:8 hold the result code.
|
||||
The first valid full-word write is sticky until reset. UART startup output is diagnostic,
|
||||
not the acceptance verdict.
|
||||
The *first valid full-word write is sticky until reset*. UART startup output is diagnostic,
|
||||
*not the acceptance verdict*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"sysctrl",page:here().page()))
|
||||
@@ -19,9 +19,9 @@
|
||||
]
|
||||
|
||||
],legacy:[
|
||||
Both timers support free-running, periodic and one-shot operation, up/down counting and sticky
|
||||
Both timers support *free-running, periodic and one-shot operation*, up/down counting and sticky
|
||||
interrupt status. An optional debug-freeze input stops counting while management Hazard3 is
|
||||
halted, without preventing register access. No separate TIM2 advanced timer is integrated.
|
||||
halted, without preventing register access. *No separate TIM2 advanced timer* is integrated.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"timer",page:here().page()))
|
||||
@@ -11,10 +11,10 @@
|
||||
#ip("uart1")
|
||||
|
||||
#ip-reference("uart1","uart",5,shared:"uart0",legacy:[
|
||||
UART1 uses the same 64-byte FIFO UART v3 ABI, not a separate non-FIFO implementation. Its
|
||||
UART1 uses the *same 64-byte FIFO UART v3 ABI*, not a separate non-FIFO implementation. Its
|
||||
dedicated TX/RX pads serve the HP console. HP PLIC source 1 is distinct from the LP vector
|
||||
number above. The initial Linux console uses OpenSBI/hvc0; a native Linux UART driver remains
|
||||
a separate delivery item.
|
||||
number above. The initial Linux console uses OpenSBI/hvc0; a *native Linux UART driver remains
|
||||
a separate delivery item*.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"uart1",page:here().page()))
|
||||
@@ -11,12 +11,12 @@
|
||||
#ip("usb2")
|
||||
|
||||
#ip-reference("usb2","usb2",4,legacy:[
|
||||
The digital controller uses an external 8-bit ULPI PHY, descriptor-driven AXI DMA and APB4
|
||||
The digital controller uses an *external 8-bit ULPI PHY*, descriptor-driven AXI DMA and APB4
|
||||
control. Its dedicated thirteen-pad interface includes ULPI clock, DATA[7:0], DIR, NXT, STP
|
||||
and PHY reset. These pads do not enter the GPIO mux. The primary external PHY target is USB3320.
|
||||
#note[The custom controller is not an EHCI register-compatible block. Host/device software,
|
||||
#note[The custom controller is *not an EHCI register-compatible block*. Host/device software,
|
||||
protocol coverage, USB compliance and board/PHY timing have their own release gates.
|
||||
An integrated digital controller does not establish USB-IF certification.]
|
||||
An integrated digital controller *does not establish USB-IF certification*.]
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"usb2",page:here().page()))
|
||||
@@ -13,8 +13,8 @@
|
||||
#ip-reference("wdg","wdg",4,legacy:[
|
||||
The watchdog remains clocked independently of the APB register domain. Early-warning IRQ14
|
||||
allows software intervention before the reset request. Software starts the watchdog once and
|
||||
services it with a two-key sequence. Timeout, early-window service and malformed service
|
||||
sequences request reset. An APB reset does not stop the running watchdog core. The integrated
|
||||
services it with a *two-key sequence*. Timeout, early-window service and malformed service
|
||||
sequences request reset. An *APB reset does not stop the running watchdog core*. The integrated
|
||||
reset-request pulse parameter is eight watchdog cycles.
|
||||
])
|
||||
|
||||
|
||||
@@ -11,9 +11,9 @@
|
||||
#ip("ws2812")
|
||||
|
||||
#ip-reference("ws2812","ws2812",4,legacy:[
|
||||
GPIO2 ALT1 carries the single transmit output. Words are sent GRB, most-significant bit first.
|
||||
Symbol high/low durations and reset-low time are programmable. This is not a Dallas/Maxim
|
||||
1-Wire controller and must not be used as a substitute for that protocol.
|
||||
GPIO2 ALT1 carries the single transmit output. Words are sent *GRB, most-significant bit first*.
|
||||
Symbol high/low durations and reset-low time are programmable. This is *not a Dallas/Maxim
|
||||
1-Wire controller* and must not be used as a substitute for that protocol.
|
||||
])
|
||||
|
||||
#context metadata((kind:"ip-end",id:"ws2812",page:here().page()))
|
||||
@@ -18,10 +18,10 @@ Each IP chapter begins on a new page. Shared register layouts are documented onc
|
||||
#ip("xpi")
|
||||
|
||||
#ip-reference("xpi","xpi",5,legacy:[
|
||||
XPI V2 supports programmable command sequences, SDR serial phases and independent chip-select
|
||||
XPI V2 supports programmable command sequences, *SDR serial phases* and independent chip-select
|
||||
configuration. The command LUT supports serial flash reads and indirect transfers without
|
||||
embedding one device's opcode sequence into software-visible hardware policy. Memory reads,
|
||||
command programming, DMA and status polling share a controlled transaction engine.
|
||||
command programming, DMA and status polling share a *controlled transaction engine*.
|
||||
|
||||
The boot alias begins at address zero. The main XPI data aperture is 256 MiB, while the boot
|
||||
alias is 16 MiB; these are decoder windows, not fitted flash capacities. Data-plane writes are
|
||||
|
||||
@@ -3,10 +3,12 @@
|
||||
"document_id": "RS-MINI-DS",
|
||||
"version": "0.5",
|
||||
"status": "DRAFT",
|
||||
"change_prefix": "v05-emphasis-",
|
||||
"date": "2026-09-22",
|
||||
"author": "Yuchi Miao",
|
||||
"author_email": "miaoyuchi@ict.ac.cn",
|
||||
"maintainer": "ECOS Team, ICT, CAS",
|
||||
"source_revision": "ca4b06d30456599a2d3fd676d832f8d4dd2f78af",
|
||||
"source_revision": "c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b",
|
||||
"profile": "configs/ci/ihp130.mk",
|
||||
"hp_profile": "configs/ci/ihp130-hp.mk",
|
||||
"mpw_profile": "configs/cluster/mini-mpw.mk",
|
||||
|
||||
@@ -1,17 +1,18 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-api-semantics","Selected body emphasis: api semantics")
|
||||
#let api = data.system_reference.software.api_reference
|
||||
|
||||
=== Software Timeouts and Polling Budgets <software-timeouts>
|
||||
|
||||
The SDK defines rs_timeout_t as an unsigned #(api.timeout_bits)-bit value and currently sets
|
||||
RS_TIMEOUT_DEFAULT to #api.default_budget. These values are software budgets, not a universal
|
||||
unit of microseconds, milliseconds or CPU cycles. Their consumption depends on the function:
|
||||
RS_TIMEOUT_DEFAULT to #api.default_budget. These values are *software budgets, not a universal
|
||||
unit* of microseconds, milliseconds or CPU cycles. Their consumption depends on the function:
|
||||
the common wait helpers decrement on every polling iteration, while UART read/write decrement
|
||||
only while the FIFO blocks progress. The UART budget is shared across the whole call.
|
||||
only while the FIFO blocks progress. The UART *budget is shared across the whole call*.
|
||||
|
||||
An iteration includes code execution and any register/bus access. CPU frequency, compiler
|
||||
output, bus waits and intervening work affect elapsed time. The budget does not independently
|
||||
bound an MMIO read that has not returned. A register named TIMEOUT can count hardware clocks
|
||||
output, bus waits and intervening work affect elapsed time. The budget *does not independently
|
||||
bound an MMIO read* that has not returned. A register named TIMEOUT can count hardware clocks
|
||||
or protocol units and is separate from an rs_timeout_t argument.
|
||||
|
||||
#ds-table("api-timeout-budgets",[Representative timeout budgets and zero-budget behavior],
|
||||
@@ -39,7 +40,7 @@ Do not obtain a supposedly portable deadline by treating RS_TIMEOUT_DEFAULT as o
|
||||
|
||||
RS_OK describes the operation implemented by the called function. It can mean a command was
|
||||
written, FIFO entries were accepted or a completion predicate was observed. Identify that
|
||||
boundary before releasing resources, consuming output or announcing completion to another hart.
|
||||
boundary *before releasing resources*, consuming output or announcing completion to another hart.
|
||||
The selected cases below do not impose a uniform completion or rollback contract on every HAL.
|
||||
|
||||
#for row in api.rows {
|
||||
@@ -65,3 +66,5 @@ General side-effect and retry rules remain in @register-programming.
|
||||
#source("crt/src/hal/dma.c",title:"DMA implementation") ·
|
||||
#source("crt/src/hal/timer.c",title:"Timer implementation")
|
||||
]
|
||||
|
||||
#change-end("v05-emphasis-api-semantics")
|
||||
@@ -1,11 +1,12 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-appendices","Selected body emphasis: appendices")
|
||||
#import "../figures.typ": *
|
||||
|
||||
= Appendix: MPW Compatibility <mpw>
|
||||
== SoC Template
|
||||
=== Architecture
|
||||
The separate MPW configuration retains selectable user-core and user-IP mechanisms. It is
|
||||
not the fixed PRODUCT topology and does not define a Gen2/Gen2+ derivative mapping. Hazard3
|
||||
*not the fixed PRODUCT topology* and does not define a Gen2/Gen2+ derivative mapping. Hazard3
|
||||
remains the management core. The selected C0-C3 interface uses RIBP and an AXI4 adapter.
|
||||
|
||||
#change-start("system-mpw", "MPW hardware organization")
|
||||
@@ -49,13 +50,13 @@ selectable user cores or user IPs.
|
||||
The product ladder expresses intended positioning. It does not advertise implemented Tiny,
|
||||
Std or Pro profiles or measured performance for a future device. The current Mini integrates
|
||||
the independently documented GA2D and NPU subsets; neither establishes a future-family feature
|
||||
set or commercial qualification. Only the reviewed Mini snapshot is specified here.
|
||||
set or commercial qualification. *Only the reviewed Mini snapshot is specified here*.
|
||||
#source-note("docs/soc-family-positioning.md", title:"Family roadmap and scope")
|
||||
|
||||
== Roadmap
|
||||
#placeholder[Reviewed release and silicon roadmap]
|
||||
#tbd[Release dates, derivative differences, process/package selections and future accelerator
|
||||
milestones have not been established as product commitments in this datasheet.]
|
||||
milestones have *not been established as product commitments* in this datasheet.]
|
||||
|
||||
= Technical Report
|
||||
#include "release-verification.typ"
|
||||
@@ -83,21 +84,24 @@ number is used to imply completion.
|
||||
|
||||
= Document Control
|
||||
== Revision History
|
||||
#change-start("revision-history", "Document revision history")
|
||||
#change-start("v05-refresh-revision", "Same-version dev revision history")
|
||||
#ds-table("revisions", [Document revision history],
|
||||
([Date], [Version], [Change], [Author]),
|
||||
(([2025-09-28],[0.1],[Create document],[Yuchi Miao]),
|
||||
([2025-12-02],[0.2],[Initial draft],[Yuchi Miao]),
|
||||
([2026-02-15],[0.3],[Initial release (historical document entry)],[Yuchi Miao]),
|
||||
([2026-09-17],[0.4 DRAFT],[Refresh the reviewed dev snapshot; add the independent GA2D P5 reference and 41-IP/108-entry structure. Synchronize APU V1/V2 and gated KWS, nine-master fabric, JPEG admission, LP external IRQ and scoped CI evidence. Retain the approved layout and unadorned repository footer.],[Yuchi Miao / ECOS Team]),
|
||||
([2026-09-22],[0.5 DRAFT],[Bind the current dev snapshot; add the NPU chapter and 42-IP/109-entry structure. Synchronize ten-master/resource integration, configured APU KWS/digest and bare-metal acceptance, GA2D P6 and long-burst conversion. Separate current CI state, historical reports and missing qualification.],[Yuchi Miao / ECOS Team])),
|
||||
([2026-09-22],[0.5 DRAFT],[Initial v0.5, reviewed ca4b06d30456: add the NPU chapter and 42-IP/109-entry structure. Synchronize ten-master/resource integration, configured APU KWS/digest and bare-metal acceptance, GA2D P6 and long-burst conversion. Separate current CI state, historical reports and missing qualification.],[Yuchi Miao / ECOS Team]),
|
||||
([2026-09-22],[0.5 DRAFT],[Same-version dev refresh: correct bounded HP acceptance and mailbox purposes; align APU availability and loading order; add development-environment evidence boundaries and linked task navigation. Preserve the existing IP structure and hardware interfaces.],[Yuchi Miao / ECOS Team]),
|
||||
([2026-09-22],[0.5 DRAFT],[Presentation revision: add the cover email contact and partial Functional mark; emphasize selected capability, programming, limitation and evidence phrases. Bind the reviewed current dev source and CI observation; hardware statements and interfaces are retained.],[Yuchi Miao / ECOS Team])),
|
||||
widths:(0.8fr,0.65fr,1.8fr,1fr),
|
||||
)
|
||||
The retained historical release entry does not establish silicon availability or qualify
|
||||
the electrical placeholders in this revision.
|
||||
#change-end("revision-history")
|
||||
#change-end("v05-refresh-revision")
|
||||
|
||||
== Sources and Reproducibility <publication-provenance>
|
||||
#change-start("v05-refresh-provenance","Exact snapshot and same-version publication identity")
|
||||
Hardware snapshot: #code(doc.source_revision).
|
||||
The source revision, configuration files, media commit, font/package hashes and PDF digest
|
||||
are recorded in the build manifest. The datasheet is built manually with Typst 0.15.1 and
|
||||
@@ -114,6 +118,15 @@ The generated address, IRQ, GPIO, pad and bus-permission data are derived from c
|
||||
inputs. Explanatory prose is reviewed against RTL and software contracts; stale descriptive
|
||||
documents do not override executable integration.
|
||||
|
||||
This file is a same-version v0.5 DRAFT revision. Distinguish it from the previous
|
||||
v0.5 delivery by the complete reviewed source revision and the matching PDF/manifest
|
||||
digests; the version number alone does not identify these two source sets. The
|
||||
UTC time in @release-verification identifies the CI observation, not a hardware test date.
|
||||
The engineering guide owns the supported tool environment and full setup commands.
|
||||
#source-note("docs/development-environment.md",title:"Supported environment and checkout-specific prerequisites")
|
||||
#source-note("docs/engineering.md",title:"Reproducible inputs, artifacts and executed-stage evidence")
|
||||
#change-end("v05-refresh-provenance")
|
||||
|
||||
== License
|
||||
retroSoC project material is distributed under Mulan Permissive Software License, Version 2.
|
||||
Third-party IP, fonts and Typst packages retain their own licenses. The media repository
|
||||
@@ -128,3 +141,5 @@ is available. Specifications can change with later source revisions.
|
||||
Author: #link("mailto:miaoyuchi@ict.ac.cn")[Yuchi Miao] \
|
||||
Maintainer: #doc.maintainer \
|
||||
Project: #link("https://github.com/retroSoC/retroSoC")[retroSoC source repository]
|
||||
|
||||
#change-end("v05-emphasis-appendices")
|
||||
@@ -1,11 +1,12 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-application-diagnostics","Selected body emphasis: application diagnostics")
|
||||
|
||||
=== Diagnostic application sequences <application-diagnostics>
|
||||
The following inventories describe the checks that the reviewed application sources execute.
|
||||
They are not newly observed pass results. Run selection and reported coverage must name the
|
||||
They are *not newly observed pass results*. Run selection and reported coverage must name the
|
||||
application, profile and stage; an application summary line cannot enlarge the tested scope.
|
||||
These routines change hardware state and scratch memory and belong in a controlled diagnostic
|
||||
environment with competing users stopped.
|
||||
environment with *competing users stopped*.
|
||||
|
||||
#for app in data.system_reference.software.applications {
|
||||
block(breakable:false,sticky:true)[
|
||||
@@ -23,7 +24,7 @@ environment with competing users stopped.
|
||||
Bringup prints application and ARCHINFO diagnostics between UART setup and the SDIO check.
|
||||
The ARCHINFO diagnostic routine returns void; its error text is not separately propagated into
|
||||
bringup's terminal result. The CI smoke application has its own explicit identity check and
|
||||
is selected by the regression runner's APP override. Do not equate the two sequences.
|
||||
is selected by the regression runner's APP override. *Do not equate the two sequences*.
|
||||
|
||||
The SDIO self-test observes controller presence/capabilities and uses the CMD_DONE test-IRQ path;
|
||||
it does not send a card-initialization or data-transfer command. USB2 self-test requires an idle
|
||||
@@ -43,3 +44,5 @@ Record test invocation and logs under @release-verification before publishing a
|
||||
#source-note("crt/src/hal/usb2.c",title:"USB2 controller self-test implementation")
|
||||
#source-note("crt/src/hal/crypto.c",title:"Crypto known-answer checks and zeroization")
|
||||
#source-note("scripts/regress.py",title:"Regression selection of CI smoke firmware")
|
||||
|
||||
#change-end("v05-emphasis-application-diagnostics")
|
||||
@@ -1,6 +1,7 @@
|
||||
#import "../style.typ": *
|
||||
|
||||
#let apu-release-reference() = [
|
||||
#change-start("v05-refresh-apu","Source-bound APU availability and acceptance order")
|
||||
#minor-title("Default and P7 acceptance configurations")
|
||||
#ds-table("apu-profile-capabilities",[APU capability and digest by committed configuration],
|
||||
([Configuration],[CAPABILITY0],[ABI_DIGEST],[Software boundary]),
|
||||
@@ -8,32 +9,32 @@
|
||||
code("0x"+upper(str(r.capability,base:16))),code("0x"+upper(str(r.digest,base:16))),
|
||||
if r.enabled {[Fixed APUM KWS is enabled; APP=apu_release and CSR-enabled IRQ acceptance.]} else {[WAV/FLAC enabled; KWS discovery returns RS_ENOTSUP.]})),
|
||||
widths:(1.45fr,0.65fr,0.65fr,1.25fr))
|
||||
The P7 digest is an ABI identity derived from the frozen register, model and microcode
|
||||
The P7 digest is an *ABI identity derived from the frozen register, model and microcode*
|
||||
interfaces. It is not a runtime accuracy result, firmware authentication or a physical
|
||||
qualification certificate. MP3 capability remains clear in both configurations.
|
||||
qualification certificate. *MP3 capability remains clear* in both configurations.
|
||||
#source-note("rtl/ip/multimedia/apu_reg.sv",title:"Actual configured capability and digest values")
|
||||
#source-note("scripts/apu_abi_digest.py",title:"Frozen ABI identity checks")
|
||||
|
||||
#minor-title("Implemented LP-to-HP acceptance sequence")
|
||||
The dedicated APU release configuration adds an LP orchestration image and a freestanding
|
||||
HP payload. It is a reproducible acceptance path, not a Linux ASoC driver or a general audio
|
||||
application distribution. The ordinary PRODUCT profile continues to use its existing gate.
|
||||
+ LP initializes memories and stages the APUMC image, APUM model and workload data.
|
||||
+ LP quiesces the resource, configures permitted address ranges, then loads and locks the
|
||||
microcode and model through the loader interfaces. Existing model-load DMA may continue
|
||||
while resource quiesce blocks new jobs; quiesce must not deadlock the accepted load.
|
||||
+ LP completes the required cache/fence and resource handoff before releasing HP work.
|
||||
+ HP performs the acceptance WAV and memory-window KWS jobs using cache-maintained
|
||||
buffers, checks the restricted LP-only range behavior, and publishes its result to LP.
|
||||
+ On timeout or fault, preserve ownership and buffers until the engine and accepted DMA
|
||||
obligations have drained; capture the terminal result before recovery or reuse.
|
||||
HP payload. It is a reproducible acceptance path, *not a Linux ASoC driver* or a general audio
|
||||
application distribution. The ordinary PRODUCT profile keeps KWS disabled by default.
|
||||
#enum(..data.system_reference.apu_implementation.acceptance_steps.map(r=>r.description))
|
||||
Accepted model-load DMA may continue while resource quiesce blocks new jobs; quiesce
|
||||
*must not deadlock an accepted load*. The ordered LP steps above are extracted from the
|
||||
application calls and their failure checkpoints; they do not imply a new executed test.
|
||||
|
||||
HP performs the acceptance WAV and memory-window KWS jobs using cache-maintained
|
||||
buffers, checks the restricted LP-only range behavior, and publishes its result to LP.
|
||||
On timeout or fault, *preserve ownership and buffers* until the engine and accepted DMA
|
||||
obligations have drained; capture the terminal result before recovery or reuse.
|
||||
#source-note("app/apps/apu_release/main.c",title:"LP asset loading, ACL setup and HP orchestration")
|
||||
#source-note("app/ports/hp-apu/main.c",title:"Bare-metal HP cache, job and result sequence")
|
||||
#source-note("tests/rtl/apu_p8_quiesce_load_tb.sv",title:"Accepted loader progress under quiesce")
|
||||
|
||||
#minor-title("Smoke, corpus and sustained-audio evidence")
|
||||
The accuracy runner selects 1000 locked PCM windows for its full gate, with at least 900
|
||||
correct classifications required. Its small smoke subset explicitly does not apply that gate.
|
||||
correct classifications required. Its small smoke subset explicitly *does not apply that gate*.
|
||||
The concurrency runner's release matrix covers WAV and FLAC with continuous RX KWS for
|
||||
60 simulated seconds per configuration at the specified 48 MHz test clock; shorter defaults
|
||||
and smoke invocations are not that campaign. Model/input identities, layer comparisons,
|
||||
@@ -43,4 +44,5 @@
|
||||
here from a capability bit, runner source or aggregate Pytest count.
|
||||
#source-note("scripts/run_apu_p7_kws_rtl.py",title:"Full accuracy gate and subset distinction")
|
||||
#source-note("scripts/run_apu_p7_concurrent_rtl.py",title:"Complete sustained-audio matrix and defaults")
|
||||
#change-end("v05-refresh-apu")
|
||||
]
|
||||
@@ -1,4 +1,5 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-architecture","Selected body emphasis: architecture")
|
||||
#import "../figures.typ": *
|
||||
#import "../waveforms.typ": timing
|
||||
#import "../diagram-packages.typ": memory-window-diagram
|
||||
@@ -8,15 +9,15 @@
|
||||
#change-start("dev-architecture","Ten-master fabric, address map, LP IRQ and lifecycle reference")
|
||||
== Introduction
|
||||
=== SoC Architecture
|
||||
Mini PRODUCT contains two fixed harts, an LP-owned control plane, a native HP data fabric and
|
||||
two APB4 register islands. There is no hardware cache coherency. Software transfers shared
|
||||
Mini PRODUCT contains *two fixed harts*, an LP-owned control plane, a native HP data fabric and
|
||||
two APB4 register islands. There is *no hardware cache coherency*. Software transfers shared
|
||||
buffer ownership explicitly and performs the required fences and cache maintenance.
|
||||
|
||||
#figure(soc-functional-diagram(), caption:[Mini PRODUCT functional architecture and clock domains.])<soc-functional-overview>
|
||||
|
||||
=== Management Processor
|
||||
==== Hazard3
|
||||
Hazard3 is hart 0 and the root-management processor. The reference profile selects RV32IM
|
||||
Hazard3 is hart 0 and the *root-management processor*. The reference profile selects RV32IM
|
||||
firmware. Its AHB-Lite interface is adapted to AXI32 for control access; memory transactions
|
||||
are directed through the LP gateway to the shared data plane. The management JTAG path provides
|
||||
halt, resume, register and system-bus access. LP retains control while HP is held in reset.
|
||||
@@ -25,7 +26,7 @@ halt, resume, register and system-bus access. LP retains control while HP is hel
|
||||
=== Application Processor
|
||||
==== VexiiRiscv
|
||||
The generated HP hart is a dual-issue RV32IMAFDC + Zicbom configuration, with supervisor/user
|
||||
modes, Sv32 virtual memory and 64-byte cache-maintenance blocks. Hart 1 uses native AXI64
|
||||
modes, Sv32 virtual memory and *64-byte cache-maintenance blocks*. Hart 1 uses native AXI64
|
||||
instruction and data paths. Its uncached MMIO path is downsized and crosses into the LP
|
||||
control plane. OpenSBI/Linux inputs and generated-core configuration are dependency-locked.
|
||||
#source-note("docs/lp-hp-architecture.md", title:"LP/HP architecture and boot contract")
|
||||
@@ -170,3 +171,5 @@ Claim/complete and priority rules are defined in the HP platform contract.
|
||||
#include "register-programming.typ"
|
||||
#include "interface-subsets.typ"
|
||||
#change-end("dev-architecture")
|
||||
|
||||
#change-end("v05-emphasis-architecture")
|
||||
@@ -1,11 +1,12 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-boot-bundle-format","Selected body emphasis: boot bundle format")
|
||||
#import "../diagram-packages.typ": binary-figures, storage-figures
|
||||
#let bundle = data.system_reference.software.bundle_reference
|
||||
#let hex(value) = code("0x"+upper(str(value,base:16)))
|
||||
|
||||
=== HP Boot Bundle Binary Format <boot-bundle-format>
|
||||
|
||||
The supplied format is a fixed four-artifact bundle, serialized as little-endian 32-bit words.
|
||||
The supplied format is a fixed four-artifact bundle, serialized as *little-endian 32-bit words*.
|
||||
The format version is #bundle.version; it is independent of the datasheet's v0.5 revision.
|
||||
The bundle starts at Flash offset #hex(bundle.bundle_offset), after the LP firmware area.
|
||||
Its fixed header is #bundle.fixed_header_bytes bytes, each descriptor is #bundle.entry_bytes
|
||||
@@ -14,8 +15,8 @@ bytes and the complete header including #bundle.entry_count descriptors is #bund
|
||||
The following offsets are relative to the beginning of the named structure. The descriptor
|
||||
array starts immediately after the fixed header, so descriptor n begins at
|
||||
#code(str(bundle.fixed_header_bytes)+" + n * "+str(bundle.entry_bytes)), for n = 0…#(bundle.entry_count - 1).
|
||||
All listed fields occupy four bytes. Use the explicit serialization, not an arbitrary host
|
||||
structure layout. The existing load addresses and maximum allocations remain in the preceding
|
||||
All listed fields occupy four bytes. Use the *explicit serialization, not an arbitrary host
|
||||
structure layout*. The existing load addresses and maximum allocations remain in the preceding
|
||||
image-layout table.
|
||||
|
||||
#binary-figures("software-boot","software")
|
||||
@@ -89,3 +90,5 @@ The example values are recalculated from the actual packager rather than maintai
|
||||
#source-note("tests/test_hp_boot_bundle.py",title:"Existing package layout/CRC test boundary")
|
||||
|
||||
#storage-figures("software-boot",section:"software")
|
||||
|
||||
#change-end("v05-emphasis-boot-bundle-format")
|
||||
@@ -1,9 +1,10 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-bus-programming","Selected body emphasis: bus programming")
|
||||
#let programming = data.system_reference.programming
|
||||
|
||||
=== Bus Transaction Rules and Arbitration <bus-programming>
|
||||
The usable transaction set is the intersection of the issuing master, fabric, adapters and
|
||||
destination. A 64-bit fabric does not make every target a 64-bit register interface. Keep
|
||||
The usable transaction set is the *intersection of the issuing master, fabric, adapters and
|
||||
destination*. A 64-bit fabric does not make every target a 64-bit register interface. Keep
|
||||
device/MMIO accesses within the target's register contract even when a bus path accepts a wider request.
|
||||
|
||||
#ds-table("bus-path-rules",[Transaction rules by path in the reviewed implementation],
|
||||
@@ -30,9 +31,9 @@ transfers and the narrower documented target limits. See @register-programming f
|
||||
{[No normal address admission through this slot.]} else {[Subject to target credits, ID and lifecycle gates.]})),
|
||||
widths:(1.5fr,0.55fr,0.6fr,1.65fr))
|
||||
SRAM and SDRAM have separate four-read/two-write target limits; serial and error targets use
|
||||
one read/one write. Target credits and master credits both constrain admission. The source
|
||||
one read/one write. *Target credits and master credits both constrain admission*. The source
|
||||
identity receives a fixed master prefix, and the same source ID is blocked while its earlier
|
||||
transaction remains active. Multiple IDs do not remove ordering requirements imposed by software.
|
||||
transaction remains active. *Multiple IDs do not remove ordering requirements* imposed by software.
|
||||
|
||||
The JPEG private path is connected to slot 6 in #code("soc_data_plane") and receives one normal
|
||||
read credit plus one normal write credit. Normal JPEG payload addresses remain subject to target
|
||||
@@ -71,3 +72,5 @@ original request. This conversion does not remove source/target alignment, 4 KiB
|
||||
permission or length restrictions. It also does not raise the NPU's independently configured
|
||||
eight-beat maximum. Verify the source master, converter and final memory contract together.
|
||||
#source-note("rtl/mini/top/axi4_downsizer_64to32.sv",title:"Implemented fragmentation, read reassembly and write response aggregation")
|
||||
|
||||
#change-end("v05-emphasis-bus-programming")
|
||||
@@ -1,9 +1,10 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-clock-programming","Selected body emphasis: clock programming")
|
||||
#let examples = data.system_reference.programming.timing
|
||||
|
||||
=== Clock, Divider and Timebase Programming <clock-programming>
|
||||
Select a functional clock before calculating a divider. A profile's CPU clock, PCLK, stable
|
||||
memory clock and audio clock are not interchangeable. The existing clock/reset inventory names
|
||||
*Select a functional clock before calculating a divider*. A profile's CPU clock, PCLK, stable
|
||||
memory clock and audio clock are *not interchangeable*. The existing clock/reset inventory names
|
||||
the domains; the table below records which clock must be supplied to the relevant calculation.
|
||||
|
||||
#ds-table("functional-clock-use",[Functional-clock inputs and configuration consequences],
|
||||
@@ -21,7 +22,7 @@ The published calculator rounds the period to units of 1/256 input-clock cycle:
|
||||
#code("P = floor((Fclk * 256 + floor(Btarget / 2)) / Btarget)").
|
||||
#code("BAUD_INT = P >> 8") and #code("BAUD_FRAC = P & 255"); the nominal resulting rate is
|
||||
#code("Bactual = Fclk * 256 / P"). The accepted range is #code("4096 <= P <= 0xffffffff").
|
||||
Both zero inputs and a period below the supported minimum must be rejected.
|
||||
Both *zero inputs and a period below the supported minimum* must be rejected.
|
||||
|
||||
#ds-table("uart-divider-examples",[UART integer/fraction examples checked against the SDK],
|
||||
([Input Hz],[Target baud],[INT / FRAC],[Nominal baud],[Error ppm]),
|
||||
@@ -87,3 +88,5 @@ The resulting buffer budget is worked through in @software-memory-budget.
|
||||
#source-note("crt/src/hal/timer_math.c",title:"Timer period calculation and overflow checks")
|
||||
#source-note("crt/src/hal/i2s_math.c",title:"Exact I2S divider and sample-packing helpers")
|
||||
#source-note("rtl/ip/serial/i2s_clkgen.sv",title:"I2S divider edge behavior")
|
||||
|
||||
#change-end("v05-emphasis-clock-programming")
|
||||
@@ -1,9 +1,10 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-coexistence-reference","Selected body emphasis: coexistence reference")
|
||||
|
||||
== Peripheral Coexistence and Resource Conflicts <resource-conflicts>
|
||||
This matrix describes shared resources and integration constraints. Hardware exclusions,
|
||||
software conventions and bandwidth competition require different decisions. Allowed combinations
|
||||
still require workload-specific validation.
|
||||
still require *workload-specific validation*.
|
||||
|
||||
#ds-table("coexistence-matrix",[Shared-resource constraints across IP boundaries],
|
||||
([Shared resource],[Constraint class],[Condition / integration action]),
|
||||
@@ -13,8 +14,8 @@ still require workload-specific validation.
|
||||
=== Choosing a coexistence configuration
|
||||
+ Start from the generated GPIO alternate-function table and memory-pad mode. A single pad
|
||||
cannot be driven by two independent peripheral outputs; identify the complete pin group.
|
||||
+ Allocate software DMA contexts and check endpoint exclusivity. Reserve the entire buffer
|
||||
lifetime, not just the interval needed to program the channel.
|
||||
+ Allocate software DMA contexts and check endpoint exclusivity. Reserve the *entire buffer
|
||||
lifetime*, not just the interval needed to program the channel.
|
||||
+ Check the central Resource Controller's owner. Its DMA resource represents the shared engine,
|
||||
not an independent LP/HP owner bit for each software channel convention.
|
||||
+ Account for gateway sharing, memory target credits and conservative drain/block behavior.
|
||||
@@ -28,7 +29,7 @@ but it does not change a shared endpoint, stream-switch mode or target bandwidth
|
||||
pad exclusion cannot be solved by choosing another DMA channel.
|
||||
|
||||
=== Failure handling and evidence
|
||||
Reject a conflicting request without overwriting active state. Capture the context, owner,
|
||||
Reject a conflicting request *without overwriting active state*. Capture the context, owner,
|
||||
pad mode and fault. Complete recovery before reassignment. An admission error is not permission
|
||||
to widen an ACL; simultaneous-workload qualification remains separate.
|
||||
#block(above:rhythm.metadata-before,below:rhythm.metadata-after,breakable:false)[
|
||||
@@ -37,3 +38,5 @@ to widen an ACL; simultaneous-workload qualification remains separate.
|
||||
#source("rtl/mini/top/soc_data_plane.sv",title:"Gateway/lifecycle wiring") ·
|
||||
#source("docs/ip/resource-controller.md",title:"Ownership and drain contract")
|
||||
]
|
||||
|
||||
#change-end("v05-emphasis-coexistence-reference")
|
||||
@@ -1,9 +1,10 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-connection-constraints","Selected body emphasis: connection constraints")
|
||||
|
||||
=== External Interfaces and Connection Constraints <connection-constraints>
|
||||
Select external components using both the IP protocol contract and the board's electrical
|
||||
requirements. A logical controller instance does not establish an on-chip PHY, fitted memory
|
||||
or connector pinout. The pin/alternate-function tables above identify routes, not a complete PCB.
|
||||
or connector pinout. The pin/alternate-function tables above identify routes, *not a complete PCB*.
|
||||
|
||||
#ds-table("external-dependencies",[External interface dependencies and integration restrictions],
|
||||
([Interface],[Connection requirement]),
|
||||
@@ -12,7 +13,7 @@ or connector pinout. The pin/alternate-function tables above identify routes, no
|
||||
|
||||
==== Memory and shared-pin selection
|
||||
QPI and OPI share a memory-pad route. Reset selects the documented QPI mode, and AON retains
|
||||
the selected mode and lock across LP/HP changes. Select the mode before accessing the attached
|
||||
the selected mode and lock across LP/HP changes. *Select the mode before accessing* the attached
|
||||
device. The inactive controller receives safe inputs and cannot drive its clock/chip-select/output
|
||||
enable; mapped accesses to that inactive target return an error. Live QPI-to-OPI switching is
|
||||
not a supported application operation in this snapshot.
|
||||
@@ -21,7 +22,7 @@ The controller aperture bounds addressability. Confirm actual device count, dens
|
||||
command sequence, latency and refresh requirements from the supported controller contract
|
||||
and selected component. Do not assume arbitrary QSPI or HyperBus devices are interchangeable.
|
||||
XPI writes use indirect commands; a CPU store into the read-only data-plane flash mapping is
|
||||
not a programming operation. Verify erase/program completion before making code executable.
|
||||
*not a programming operation*. Verify erase/program completion before making code executable.
|
||||
|
||||
#include "device-compatibility.typ"
|
||||
|
||||
@@ -62,3 +63,5 @@ VBUS sensing, role/power switching and ESD protection belong to the approved boa
|
||||
#source-note("docs/ip/gpio.md",title:"Pad ownership, guards and alternate-function behavior")
|
||||
#source-note("docs/ip/usb2.md",title:"ULPI digital/physical interface boundary")
|
||||
#source-note("fpga/README.md",title:"Board-specific wrapper and constraint ownership")
|
||||
|
||||
#change-end("v05-emphasis-connection-constraints")
|
||||
@@ -0,0 +1,35 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-development-environment","Selected body emphasis: development environment")
|
||||
|
||||
=== Development environment and reproducible inputs
|
||||
#change-start("v05-refresh-development","Supported development environment and evidence stages")
|
||||
#let environment=data.system_reference.development_environment
|
||||
The supported open-source tool environment targets #environment.platform. The Docker image,
|
||||
Nix application and manual Ubuntu #environment.ubuntu bootstrap share the repository's locked
|
||||
installer. Docker and Nix use Python #environment.python to match the pinned requirement sets;
|
||||
both provide Java #environment.java for the locked SBT #environment.sbt toolchain. These are
|
||||
development prerequisites, *not additional SoC functions* or a statement of target performance.
|
||||
|
||||
#ds-table("development-entrypoints",[Development entrypoints and their boundaries],
|
||||
([Entrypoint],[Reproducible input],[Use and evidence boundary]),
|
||||
(([Docker],[Digest-pinned Ubuntu base and the shared dependency lock.],[The image supplies tools. A mounted checkout supplies managed RTL, PDKs, application inputs and generated outputs.]),
|
||||
([Nix],[Locked nixpkgs and a *Linux x86_64* FHS environment.],[The launcher uses the same bootstrap in the current checkout. A successful flake check does not establish runtime regression success.]),
|
||||
([Manual Ubuntu],[Shared bootstrap, archive checksums and pinned Python requirements.],[Activate and check the installed environment, then prepare the selected profile's dependencies before building.])),
|
||||
widths:(0.65fr,1.45fr,2.15fr))
|
||||
|
||||
The environment does not package PDK repositories, managed RTL, application archives,
|
||||
build products or compiler caches. Follow the engineering guide's setup and doctor flows
|
||||
for the selected checkout and profile. Preserve the installed environment manifest and
|
||||
input hashes with each result; the full setup commands belong in that guide.
|
||||
|
||||
Record installation, environment checking and runtime regression as separate stages.
|
||||
The hosted development-environment workflow currently runs the IHP130 behavioral-only
|
||||
regression; it does not add synthesis, netlist, STA or silicon evidence. A failed runtime
|
||||
stage remains a failure even when Docker build or Nix installation/checking succeeds.
|
||||
See @release-verification for the commit-bound observation and its UTC sampling time.
|
||||
#source-note("docs/development-environment.md",title:"Supported environment, setup commands and activation")
|
||||
#source-note("dependencies/dependencies.lock.json",title:"Locked sources, tools, containers and Nix inputs")
|
||||
#source-note(".github/workflows/development-environment.yml",title:"Actual installation and behavioral runtime stages")
|
||||
#change-end("v05-refresh-development")
|
||||
|
||||
#change-end("v05-emphasis-development-environment")
|
||||
@@ -1,8 +1,9 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-device-compatibility","Selected body emphasis: device compatibility")
|
||||
|
||||
==== External Memory and Device Compatibility <device-compatibility>
|
||||
The table distinguishes a controller protocol profile, a simulation model and a qualified
|
||||
physical component. Geometry or a similar command set is insufficient to establish drop-in
|
||||
The table distinguishes a controller protocol profile, a simulation model and a *qualified
|
||||
physical component*. Geometry or a similar command set is insufficient to establish drop-in
|
||||
compatibility. Device order codes, supply, speed grade and board timing must be reviewed together.
|
||||
|
||||
#ds-table("external-device-profiles",[External-memory profiles and their evidence boundary],
|
||||
@@ -14,13 +15,13 @@ compatibility. Device order codes, supply, speed grade and board timing must be
|
||||
([Device / profile],[Model evidence indexed],[Board],[Silicon]),
|
||||
data.system_reference.programming.devices.map(r=>(r.name,r.model,r.board,r.silicon)),
|
||||
widths:(1.1fr,1.85fr,0.6fr,0.6fr))
|
||||
Model source and test availability are not a reviewed passing run. The fast XPI backend is
|
||||
Model source and test availability are *not a reviewed passing run*. The fast XPI backend is
|
||||
specifically narrower than a pin-level flash model: it is useful for selected boot/regression
|
||||
work and must not qualify erase/program behavior, all LUT modes or board sampling margins.
|
||||
|
||||
Before substituting a component, compare its reset state, command/address encoding, mode/dummy
|
||||
phases, latency configuration, page and chip boundaries, supported sampling clocks and status
|
||||
bits. Validate the complete initialization and recovery sequence, not only a successful ID read.
|
||||
bits. Validate the *complete initialization and recovery sequence*, not only a successful ID read.
|
||||
For SDRAM, match bank/row/column geometry and convert device timings to the actual memory clock.
|
||||
|
||||
The QPI controller is device-specific. The OPI and modified single-clock HyperBus-style paths
|
||||
@@ -37,3 +38,5 @@ because QPI and OPI use mutually exclusive shared pads.
|
||||
#source-note("docs/ip/opipsram.md",title:"Prototype OPI and single-clock HyperBus-style profiles")
|
||||
#source-note("docs/ip/sdram.md",title:"SDRAM geometry, clocking and timing configuration")
|
||||
|
||||
|
||||
#change-end("v05-emphasis-device-compatibility")
|
||||
@@ -1,9 +1,10 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-electrical-reference","Selected body emphasis: electrical reference")
|
||||
|
||||
== Electrical and Timing Specifications <electrical-specifications>
|
||||
The RTL snapshot and reference configuration establish digital behavior, not production
|
||||
electrical ratings. The following groups define the information needed for a physical release.
|
||||
TBD means no reviewed specification is attached; it never means zero or an unrestricted limit.
|
||||
The RTL snapshot and reference configuration establish digital behavior, *not production
|
||||
electrical ratings*. The following groups define the information needed for a physical release.
|
||||
TBD means no reviewed specification is attached; it *never means zero or an unrestricted limit*.
|
||||
|
||||
Each completed parameter row must identify its supply/pad domain, PVT and load conditions,
|
||||
unit, Min/Typ/Max interpretation and report revision. Attach setup/hold and output-delay
|
||||
@@ -13,8 +14,8 @@ production-test guarantees distinct when the release record in @release-verifica
|
||||
=== Parameter conditions and evidence
|
||||
Every numerical electrical entry must identify process/PDK and revision, macro/pad implementation,
|
||||
package, supply, temperature, clock configuration and loading. Label the basis as approved
|
||||
vendor specification, model/analysis, characterization or production test. Minimum/maximum
|
||||
guarantees and typical observations must not be interchanged.
|
||||
vendor specification, model/analysis, characterization or production test. *Minimum/maximum
|
||||
guarantees and typical observations must not be interchanged*.
|
||||
|
||||
#ds-table("electrical-conditions",[Conditions required for a numerical electrical specification],
|
||||
([Condition],[Required record],[Current publication state]),
|
||||
@@ -37,7 +38,7 @@ Power connections and sequencing must come from the selected technology and pack
|
||||
([Partial power],[Back-power/injection limits and permitted levels when another rail is absent.],[TBD]),
|
||||
([Decoupling],[Approved capacitor network, placement, return path and package-specific requirements.],[TBD])),
|
||||
widths:(0.8fr,2.8fr,0.4fr))
|
||||
Digital initialization begins only after the board has met its approved rail, clock and reset
|
||||
Digital initialization begins *only after the board has met* its approved rail, clock and reset
|
||||
requirements. Use the clock/reset sequence in @operating-states after that point. No universal
|
||||
rail ordering, brownout threshold or reset pulse width is specified for the generic SoC here.
|
||||
|
||||
@@ -100,3 +101,5 @@ isolation and retention current are not established by the current digital clock
|
||||
widths:(1fr,2.4fr,0.6fr))
|
||||
#source-note("physical/README.md",title:"Technology, macro and physical-validation boundary")
|
||||
#source-note("docs/pll-clock-control.md",title:"Digital clock choices and physical qualification")
|
||||
|
||||
#change-end("v05-emphasis-electrical-reference")
|
||||
@@ -1,15 +1,16 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-fault-reference","Selected body emphasis: fault reference")
|
||||
#import "../ip-reference.typ": inline
|
||||
|
||||
= Appendix: Fault and Status Code Reference <fault-code-reference>
|
||||
This appendix is a lookup aid for the reviewed implementation. Begin with the producing
|
||||
module and the validity/ownership state, then decode its value. An equal number in two tables
|
||||
does not imply an equal fault. Numeric enums select one value; bitmasks can contain several
|
||||
This appendix is a lookup aid for the reviewed implementation. Begin with the *producing
|
||||
module and the validity/ownership state*, then decode its value. An equal number in two tables
|
||||
*does not imply an equal fault*. Numeric enums select one value; bitmasks can contain several
|
||||
independent causes. Source-declared codes are not proof that every associated optional
|
||||
function or end-to-end path is implemented.
|
||||
|
||||
Capture first-fault address, master, direction, engine progress and descriptor state before
|
||||
acknowledging or resetting anything. The detailed register and recovery contracts in
|
||||
Capture first-fault address, master, direction, engine progress and descriptor state *before
|
||||
acknowledging or resetting anything*. The detailed register and recovery contracts in
|
||||
@system-diagnostics remain authoritative. The global address lookup is @global-register-index.
|
||||
|
||||
== Diagnostic Code Namespaces
|
||||
@@ -59,10 +60,12 @@ intermediate console messages. The same integer can denote different stages, inc
|
||||
one application. Preserve application identity, execution order and preceding log markers.
|
||||
|
||||
=== HP Boot Application Results
|
||||
#change-start("v05-refresh-boot-results","Bounded boot failures and stage-qualified terminal result")
|
||||
These result codes belong to the supplied HP boot application. TEST_STATUS's result byte is
|
||||
application-defined; other firmware can assign different meanings. Code 1 can be written
|
||||
before a reliable console exists. A missing ready event does not generate a new firmware
|
||||
code: the current final mailbox wait has no firmware-local deadline.
|
||||
before a reliable console exists. The ready, result and cache-clean waits have bounded polling
|
||||
budgets and distinct failure stages. The initial ready marker precedes the remaining GA2D
|
||||
acceptance/cache handoff; it does not itself write a successful TEST_STATUS value.
|
||||
|
||||
#ds-table("boot-result-codes",[HP boot application terminal result codes],
|
||||
([Code],[Meaning / producing stage]),
|
||||
@@ -71,9 +74,13 @@ code: the current final mailbox wait has no firmware-local deadline.
|
||||
The #code("HP_BOOT_FAILED:<code>") diagnostic is emitted by the failure helper before its
|
||||
terminal status write; UART initialization failure uses the direct terminal path. Entry-copy
|
||||
failure is reported only after both the DMA attempt and software copy/CRC fallback fail.
|
||||
After copying, HP release and Linux readiness are distinct checkpoints. See @boot-configuration
|
||||
for prerequisites and @image-maintenance for separate programming-tool result semantics.
|
||||
After copying, HP release, initial readiness, job result and cache-clean handoff are distinct
|
||||
checkpoints. NPU resource handoff is conditional on its acceptance build options. The failure
|
||||
helper preserves HP state after GA2D ownership moves to HP; a failed verdict does not guarantee
|
||||
a completed reset or DMA drain. See @boot-configuration for prerequisites/recovery and
|
||||
@image-maintenance for separate programming-tool result semantics.
|
||||
#source-note("app/apps/hp_boot/main.c",title:"Actual boot failure branches and ready-event handling")
|
||||
#change-end("v05-refresh-boot-results")
|
||||
|
||||
#for app in data.system_reference.software.applications {
|
||||
heading(level:3,app.title)
|
||||
@@ -120,3 +127,5 @@ different measurements. This appendix supplies no new successful hardware run.
|
||||
#source-note("rtl/mini/dv/tb/retrosoc_tb.sv",title:"Icarus testbench completion")
|
||||
#source-note("rtl/mini/dv/verilator/csrc/Emulator.cpp",title:"Verilator completion")
|
||||
#source-note("docs/engineering.md",title:"Regression verdict and evidence rules")
|
||||
|
||||
#change-end("v05-emphasis-fault-reference")
|
||||
@@ -5,9 +5,9 @@
|
||||
#ds-table("ga2d-operations",[GA2D P5 operations and admitted surfaces],
|
||||
([Operation],[Inputs],[Destination and boundary]),
|
||||
(([FILL],[COLOR; foreground/background surfaces unused.],[Any supported color format; fill alpha follows COLOR for ARGB8888.]),
|
||||
([COPY],[One color foreground.],[Same format as foreground; byte-preserving, no overlapping source/destination.]),
|
||||
([COPY],[One color foreground.],[Same format as foreground; byte-preserving, *no overlapping source/destination*.]),
|
||||
([CONVERT],[One color foreground.],[Any supported color format; bit replication on RGB565 expansion and high-bit truncation on packing.]),
|
||||
([BLEND],[Color foreground or A8 mask; opaque color background.],[Color destination. Background may equal destination only with identical address, pitch and format.])),
|
||||
([BLEND],[Color foreground or A8 mask; opaque color background.],[Color destination. Background may equal destination only with *identical address, pitch and format*.])),
|
||||
widths:(0.6fr,1.3fr,2.3fr))
|
||||
RGB565 stores red in bits 15:11, green in 10:5 and blue in 4:0. RGB888 stores bytes R, G, B
|
||||
in increasing memory addresses. XRGB8888 and ARGB8888 store bytes B, G, R, X/A. Conversion
|
||||
@@ -18,7 +18,7 @@
|
||||
Let #code("Af") be foreground alpha (255 for RGB/XRGB or the mask byte for A8),
|
||||
#code("Ag") the global alpha, and #code("F")/#code("B") one foreground/background color channel:
|
||||
#code-block(raw("A = floor((Af * Ag + 127) / 255)\nC = floor((F * A + B * (255 - A) + 127) / 255)",block:true))
|
||||
The two rounding steps are separate. A8 supplies alpha only and takes foreground RGB from
|
||||
The two rounding steps are separate. *A8 supplies alpha only* and takes foreground RGB from
|
||||
COLOR. Background alpha is not accumulated; BLEND writes opaque destination alpha.
|
||||
#source-note("rtl/ip/multimedia/ga2d_pixel.sv",title:"Implemented byte packing and two-stage alpha rounding")
|
||||
|
||||
@@ -45,12 +45,12 @@
|
||||
#let ga2d-protocol() = [
|
||||
#minor-title("Admission, completion and recovery")
|
||||
Configuration is staged through APB4 and latched for one accepted job. START requires a
|
||||
ready data path, idle engine and valid geometry; BUSY is not a queue-space indicator.
|
||||
ready data path, idle engine and valid geometry; BUSY is *not a queue-space indicator*.
|
||||
Completion is reported after the engine's accepted read/write obligations have completed.
|
||||
#ds-table("ga2d-recovery",[GA2D completion and recovery decisions],
|
||||
([Observation],[Required software action]),
|
||||
(([DONE with no error],[Capture counters, acknowledge the owner IRQ, and transfer destination ownership before CPU reads.]),
|
||||
([Software polling timeout],[Do not reuse the buffers. Request abort and wait for accepted bus traffic to drain.]),
|
||||
([Software polling timeout],[*Do not reuse the buffers*. Request abort and wait for accepted bus traffic to drain.]),
|
||||
([ERROR or ABORT_DONE],[Capture first-error code, stage, AXI response and address; verify busy/draining state before release.]),
|
||||
([RECOVERY_REQUIRED or bridge epoch change],[Coordinate resource/HP recovery, wait for the bridge clear and DATA_READY rearm, then establish ownership again.]),
|
||||
([PCLK/HP lifecycle transition],[Block new work, stop/drain, complete bridge flush and acknowledge the new epoch; source idle alone is insufficient.])),
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-image-maintenance","Selected body emphasis: image maintenance")
|
||||
|
||||
== Programming, Image Maintenance and Service Procedures <image-maintenance>
|
||||
The existing flow programs external NOR using an SRAM-resident XPI loader and an already
|
||||
configured OpenOCD/GDB connection. It does not add a hardware JTAG-to-flash master, automatic
|
||||
configured OpenOCD/GDB connection. It *does not add a hardware JTAG-to-flash master*, automatic
|
||||
OTA service or authenticated update chain. This chapter documents the operation; the publication
|
||||
build does not connect a debugger or erase/program a device.
|
||||
|
||||
@@ -16,8 +17,8 @@ build does not connect a debugger or erase/program a device.
|
||||
([System state],[HP and other masters cannot fetch/use the affected NOR region; relevant interrupts and transfers are quiesced.],[A management halt alone does not establish these system-wide conditions.])),
|
||||
widths:(0.8fr,2.05fr,1.3fr))
|
||||
The committed loader profile is #code("configs/ci/ihp130-xpi-flash-loader.mk"), using the
|
||||
#code("jtag_sram") linker layout. The ELF and its state must remain in SRAM because the boot
|
||||
NOR is unavailable during erase/program. A matching loader artifact was not newly built by
|
||||
#code("jtag_sram") linker layout. The ELF and its state *must remain in SRAM* because the boot
|
||||
NOR is *unavailable during erase/program*. A matching loader artifact was not newly built by
|
||||
this publication task; supply one from a reviewed build before using the host command.
|
||||
|
||||
The current algorithm is specialized for the documented 16 MiB Winbond-compatible flash
|
||||
@@ -94,3 +95,5 @@ from records of actual device operations.
|
||||
#source-note("app/apps/xpi_flash_loader/main.c",title:"SRAM loader and sector/page verification algorithm")
|
||||
#source-note("crt/linker/jtag_sram.lds",title:"Loader placement and retained debugger entry points")
|
||||
#source-note("docs/hazard3-debug.md",title:"Management debug scope and reset boundary")
|
||||
|
||||
#change-end("v05-emphasis-image-maintenance")
|
||||
@@ -1,7 +1,8 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-interface-subsets","Selected body emphasis: interface subsets")
|
||||
|
||||
== Interface Standards and Supported Subsets <interface-subsets>
|
||||
An interface name is not a claim that every mode in a related standard is implemented. This
|
||||
An interface name is *not a claim that every mode* in a related standard is implemented. This
|
||||
matrix summarizes the source-level subset, instance routing and software boundary of the
|
||||
reviewed snapshot. The individual IP contract and actual register/capability checks remain
|
||||
authoritative. No interface compliance certificate is attached to this matrix.
|
||||
@@ -18,8 +19,8 @@ Use the instance's protocol and availability qualifications together with its fo
|
||||
#change-end("interface-format-links")
|
||||
|
||||
=== Software and verification boundary
|
||||
Hardware mode support, a callable HAL and a qualified protocol/system result are separate
|
||||
columns. A driver may implement only a subset of the digital engine. An external PHY, device,
|
||||
Hardware mode support, a callable HAL and a qualified protocol/system result are *separate
|
||||
columns*. A driver may implement only a subset of the digital engine. An external PHY, device,
|
||||
clock, pin route or software stack may also be required before a mode is usable on a board.
|
||||
|
||||
#ds-table("interface-software-scope",[Software and verification scope for interface selection],
|
||||
@@ -34,7 +35,7 @@ clock, pin route or software stack may also be required before a mode is usable
|
||||
descriptor field is not proof of hardware support.
|
||||
+ Check transport availability separately from format support. JPEG system-integration and APU
|
||||
production-job gates remain binding.
|
||||
+ Verify a bounded normal transfer and its error/recovery case on the selected platform.
|
||||
+ Verify a *bounded normal transfer and its error/recovery case* on the selected platform.
|
||||
|
||||
Calculations and model/test availability do not establish compliance. A board-level validation
|
||||
claim must identify the actual device, mode, configuration and matching result.
|
||||
@@ -43,3 +44,5 @@ claim must identify the actual device, mode, configuration and matching result.
|
||||
#source("publications/datasheets/system-reference.json",title:"Subset evidence index") ·
|
||||
#source("publications/datasheets/features.json",title:"Per-IP feature summaries")
|
||||
]
|
||||
|
||||
#change-end("v05-emphasis-interface-subsets")
|
||||
@@ -1,16 +1,17 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-linux-runtime","Selected body emphasis: linux runtime")
|
||||
#import "../system-figures.typ": sequence-diagram
|
||||
#let platform = data.system_reference.software.platform
|
||||
|
||||
=== OpenSBI platform and console path <linux-runtime>
|
||||
The supplied OpenSBI platform exposes one application hart, with hart ID #platform.hart_id.
|
||||
The supplied OpenSBI platform exposes *one application hart*, with hart ID #platform.hart_id.
|
||||
LP remains the separate management firmware processor. The platform's ACLINT descriptor covers
|
||||
two hart-indexed register positions beginning at zero so it can address hart 1; that storage
|
||||
range is not a declaration that Linux runs on both harts. The kernel configuration disables SMP.
|
||||
range is not a declaration that Linux runs on both harts. The *kernel configuration disables SMP*.
|
||||
|
||||
The early platform setup programs UART1, registers its polled console and initializes machine
|
||||
software-interrupt support. Timer initialization uses the ACLINT machine timer. Console writes
|
||||
wait while TX is full; this loop has no local timeout. These implemented callbacks do not
|
||||
wait while TX is full; this loop has *no local timeout*. These implemented callbacks do not
|
||||
establish that all optional SBI services or all peripherals have native Linux drivers.
|
||||
|
||||
#figure(sequence-diagram((
|
||||
@@ -54,6 +55,7 @@ together. A changed device-tree property does not reconfigure clocks or synthesi
|
||||
#source-note("scripts/build_hp_linux.py",title:"Actual initrd-end patch and FW_JUMP build arguments")
|
||||
|
||||
=== Kernel and rootfs ready handoff
|
||||
#change-start("v05-refresh-linux-mailbox","HAL-derived mailbox purposes and ready-only rootfs boundary")
|
||||
The rootfs service S99retrosoc-hp prints its ready message and then performs four 32-bit mailbox
|
||||
writes. The published event is an init-service checkpoint, not proof of all drivers, networking,
|
||||
storage or long-term Linux stability. The text is emitted before the mailbox writes, so the text
|
||||
@@ -62,18 +64,26 @@ alone is not the LP's readiness condition.
|
||||
#ds-table("linux-ready-writes",[Rootfs service mailbox publication order],
|
||||
([Order],[Address],[Written value],[Purpose]),
|
||||
platform.ready_writes.enumerate().map(((i,row))=>(str(i+1),code(row.address),code(row.value),
|
||||
([Sequence],[Linux-ready event],[Argument / ready state],[Interrupt request]).at(i))),
|
||||
[#code(row.register) \ #row.purpose])),
|
||||
widths:(0.4fr,1.1fr,1.1fr,1.85fr))
|
||||
|
||||
The script uses devmem from the supplied userland with CONFIG_DEVMEM enabled in the kernel.
|
||||
It contains no explicit readback or per-write failure handling. The LP loader checks the
|
||||
expected sequence/event in its existing mailbox loop; that final wait has no firmware-local
|
||||
deadline. A rootfs message, process exit, mailbox publication and final SYSCTRL TEST_STATUS are
|
||||
different observations. Preserve them with their stage and use an external timeout when a
|
||||
required checkpoint never arrives.
|
||||
exact sequence, event and argument with a bounded iteration budget. A rootfs message, process
|
||||
exit, mailbox publication and final SYSCTRL TEST_STATUS are different observations.
|
||||
The current loader subsequently requests GA2D acceptance and cache-clean responses before
|
||||
returning ownership to LP and writing a successful verdict. This rootfs script implements *only
|
||||
the first ready event*; it supplies none of those later responses. Reaching Linux init is
|
||||
therefore insufficient for a complete loader acceptance pass. Use the matching freestanding
|
||||
acceptance payload for that protocol, or provide and validate the missing Linux service as
|
||||
separate integration work. See @boot-configuration for the exact message identities and budget.
|
||||
|
||||
Resource ownership and non-coherent buffer rules still apply after Linux starts. Follow
|
||||
@software-support before choosing a driver path, and @multicore-operation for later LP/HP
|
||||
transactions. This description adds no new successful boot or board-validation claim.
|
||||
#source-note("app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp",title:"Ready message and actual mailbox write order")
|
||||
#source-note("crt/src/hal/hp_mailbox.c",title:"Event, argument and sequence register purposes")
|
||||
#source-note("app/apps/hp_boot/main.c",title:"LP sequence/event checks and final terminal result")
|
||||
#change-end("v05-refresh-linux-mailbox")
|
||||
|
||||
#change-end("v05-emphasis-linux-runtime")
|
||||
@@ -1,10 +1,11 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-media-formats","Selected body emphasis: media formats")
|
||||
|
||||
==== Data Formats and Peripheral Interoperability <media-interoperability>
|
||||
#change-start("dev-media-formats","Current format compatibility and transport qualifications")
|
||||
Matching names such as RGB565, YUV422 or PCM are only the beginning of an interoperability
|
||||
check. Compare the exact byte order, container width, stride, alignment, stream boundary and
|
||||
software lifetime. A shared address space does not convert formats or make an unavailable
|
||||
check. Compare the *exact byte order, container width, stride, alignment, stream boundary and
|
||||
software lifetime*. A shared address space does not convert formats or make an unavailable
|
||||
transport usable.
|
||||
|
||||
#ds-table("media-format-layouts",[Media representations and their storage/stream boundaries],
|
||||
@@ -25,7 +26,7 @@ with bounded normal SoC private-DMA admission through master 6 as documented in
|
||||
@bus-programming; this is not full-system workload qualification. GA2D adds explicit color-format
|
||||
conversion and opaque composition as described in @ga2d; it does not supply RGB/YUV conversion.
|
||||
NPU tensors follow a separate static INT8 layout and quantization contract. A camera frame or
|
||||
audio PCM buffer is not directly an NPU model input: CPU preprocessing must produce the
|
||||
audio PCM buffer is *not directly an NPU model input*: *CPU preprocessing must produce* the
|
||||
compiler's expected features, byte layout and zero points. NPU receives memory jobs, not a
|
||||
dedicated camera/audio stream, and its model format is not the APU APUM container.
|
||||
|
||||
@@ -69,3 +70,5 @@ buffer rather than passing partially valid data onward.
|
||||
#source-note("docs/ip/jpeg.md",title:"JPEG raster formats, strides and alignment")
|
||||
#source-note("docs/ip/apu.md",title:"APU transport and production availability boundary")
|
||||
#change-end("dev-media-formats")
|
||||
|
||||
#change-end("v05-emphasis-media-formats")
|
||||
@@ -1,9 +1,10 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-memory-use","Selected body emphasis: memory use")
|
||||
#import "../system-figures.typ": sequence-diagram
|
||||
#import "../diagram-packages.typ": cache-boundary-diagram
|
||||
|
||||
== Memory Attributes, Cache and DMA Coherency <memory-coherency>
|
||||
The LP and HP cores do not form a cache-coherent SMP system. Shared memory is visible through
|
||||
The LP and HP cores *do not form a cache-coherent SMP system*. Shared memory is visible through
|
||||
different initiators, and non-CPU masters do not snoop the HP caches. A correct address and a
|
||||
successful bus response therefore do not prove that a consumer observed the latest data.
|
||||
|
||||
@@ -18,7 +19,7 @@ because its pads are inactive, the target is not ready, or an extension range ch
|
||||
[R: #p.read_targets.join(", ") \ W: #p.write_targets.join(", ")])),
|
||||
widths:(1fr,0.7fr,0.9fr,1.8fr))
|
||||
"No policy requirement" does not configure the CPU MMU or create cacheability for MMIO.
|
||||
Keep device registers uncached and use their documented access width and side-effect rules.
|
||||
*Keep device registers uncached* and use their documented access width and side-effect rules.
|
||||
The HP uncached MMIO path is distinct from its cache data path. Do not map one shared physical
|
||||
buffer with inconsistent aliases and then rely on a fence to repair the aliasing.
|
||||
|
||||
@@ -29,8 +30,8 @@ used as scratch space. Physical device capacity must match the controller and bo
|
||||
|
||||
=== Buffer ownership and alignment
|
||||
The supplied HP platform metadata declares Zicbom with a 64-byte cache-maintenance block. Round shared
|
||||
maintenance ranges to full blocks and prevent unrelated owners from sharing a boundary block.
|
||||
Check address-plus-length overflow before rounding. Device descriptors can impose additional
|
||||
maintenance ranges to full blocks and *prevent unrelated owners from sharing a boundary block*.
|
||||
*Check address-plus-length overflow* before rounding. Device descriptors can impose additional
|
||||
alignment, byte-count, stride and memory-placement constraints; the DMA TCD is a separate
|
||||
64-byte descriptor contract, not a universal transfer-alignment rule for every IP.
|
||||
|
||||
@@ -93,3 +94,5 @@ transaction at the protocol level; retries require a new ownership decision.
|
||||
#source-note("docs/ip/resource-controller.md",title:"Cache request and clean acknowledgement")
|
||||
#source-note("docs/ip/dma.md",title:"DMA descriptors, transfer restrictions and completion")
|
||||
#source-note("app/ports/linux/linux/retrosoc_hp.dts",title:"Linux RAM and cache-maintenance properties")
|
||||
|
||||
#change-end("v05-emphasis-memory-use")
|
||||
@@ -3,7 +3,7 @@
|
||||
#let npu-functional() = [
|
||||
#let n=data.system_reference.npu_implementation
|
||||
#minor-title("Deployed configuration and arithmetic")
|
||||
The default PRODUCT integration contains an executable NPU. The control registers use PCLK;
|
||||
The default PRODUCT integration contains an *executable NPU*. The control registers use PCLK;
|
||||
computation, private SRAM and payload DMA use HP. Launch, completion, snapshot and lifecycle
|
||||
state cross through explicit control mailboxes. There is no payload CDC or AXI width converter
|
||||
on the NPU master. The NPU is independent of the APU's fixed KWS engine.
|
||||
@@ -16,9 +16,9 @@
|
||||
([Transport],[AXI64; up to #n.max_burst_beats beats],[One read and one write may overlap; source ID zero.]),
|
||||
([Job records],[#n.descriptor_bytes bytes],[Linear descriptor list; one active job token.])),widths:(0.9fr,1.1fr,2fr))
|
||||
|
||||
Tensor elements are signed INT8. Subtracting the input zero point produces signed nine-bit
|
||||
activations; multiplication uses signed 9-by-8 operands. Accumulation uses checked INT32
|
||||
arithmetic. Bias is applied once per output, while K slices preserve the partial sum. Overflow
|
||||
Tensor elements are *signed INT8*. Subtracting the input zero point produces signed nine-bit
|
||||
activations; multiplication uses signed 9-by-8 operands. Accumulation uses *checked INT32
|
||||
arithmetic*. Bias is applied once per output, while K slices preserve the partial sum. Overflow
|
||||
is a reported arithmetic fault, not silent wraparound. Numeric profile 1 uses the implemented
|
||||
double-rounding multiplier/shift rules, then output zero point and activation clamp.
|
||||
Preserve tie handling and negative values; a host floating-point rescale is not bit equivalent.
|
||||
@@ -26,7 +26,7 @@
|
||||
#source-note("rtl/ip/multimedia/npu_requantizer.sv",title:"Implemented integer requantization")
|
||||
|
||||
#minor-title("Supported operator subset")
|
||||
The compiler uses static batch-one NHWC tensors. Each dimension is within 1…#n.max_dimension;
|
||||
The compiler uses *static batch-one NHWC tensors*. Each dimension is within 1…#n.max_dimension;
|
||||
a spatial tile contains at most eight output positions and each K slice is at most #n.max_k_slice.
|
||||
These individual maxima do not imply that every combination fits local storage or a valid job.
|
||||
Padding, allocation spans, packing, alignment and overlap are checked before execution.
|
||||
@@ -39,9 +39,9 @@
|
||||
([6],[Average pool],[Same geometry restrictions as max pool; integer rounding follows profile 1.]),
|
||||
([7],[Global average pool],[One output position per channel; input/output zero point preserved.]),
|
||||
([8],[Clamp],[Shape, channels and zero point preserved; no weights or parameter payload.])),widths:(0.4fr,0.95fr,2.65fr))
|
||||
Unused descriptor fields and reserved words must be zero. Conv/pool output geometry must
|
||||
Unused descriptor fields and *reserved words must be zero*. Conv/pool output geometry must
|
||||
match kernel, stride and padding; Add/Clamp are not implicit reshape operations. The compiler
|
||||
can remove storage-preserving reshapes, but unknown operators fail compilation. Only the
|
||||
can remove storage-preserving reshapes, but *unknown operators fail compilation*. Only the
|
||||
explicitly supported terminal Softmax becomes a CPU finalizer; this is not arbitrary CPU fallback.
|
||||
#source-note("rtl/ip/multimedia/npu_job_decoder.sv",title:"Descriptor and operator admission checks")
|
||||
#source-note("scripts/npu_compiler_p0.py",title:"Static lowering and explicit CPU boundary")
|
||||
@@ -49,8 +49,8 @@
|
||||
#minor-title("Local memory and parameter ownership")
|
||||
The sixteen 4 KiB banks are partitioned into raw gather, packed activation, packed weights,
|
||||
output staging and descriptor/parameter regions. The bank-backed implementation has synchronous
|
||||
reads and byte write strobes. Reset invalidates ownership and control metadata; it does not
|
||||
erase SRAM contents. Software cannot treat that reset as sanitization. Input packing, local-bank
|
||||
reads and byte write strobes. Reset invalidates ownership and control metadata; it *does not
|
||||
erase SRAM contents*. Software cannot treat that reset as sanitization. Input packing, local-bank
|
||||
conflicts and scalar requantization can limit useful throughput below the dense-MAC ceiling.
|
||||
Descriptor, weight and parameter bases are 64-byte aligned. Tensor payload edges may use
|
||||
narrower reads or write strobes, but the declared allocation and stride bounds still apply.
|
||||
|
||||
@@ -1,17 +1,18 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-operating-states","Selected body emphasis: operating states")
|
||||
#import "../system-figures.typ": sequence-diagram
|
||||
|
||||
=== System Operating States and Reset Effects <operating-states>
|
||||
The states below describe the digital control contract. They are not voltage states or
|
||||
The states below describe the digital control contract. They are *not voltage states* or
|
||||
qualified Sleep/Stop/Standby modes. In particular, stopping the HP leaf clock leaves the
|
||||
fabric and stable memory clock available for management recovery and other masters.
|
||||
|
||||
#ds-table("operating-states",[System operating states and transition responsibilities],
|
||||
([State],[Available activity],[Required transition condition]),
|
||||
(([LP management; HP held],[LP root control, memory initialization and diagnostics.],[Prepare HP memory and software before release.]),
|
||||
([LP + HP running],[Asymmetric firmware/Linux operation with explicit resource ownership.],[Stop new work before transferring resources or shutting down HP.]),
|
||||
([LP + HP running],[Asymmetric firmware/Linux operation with explicit resource ownership.],[*Stop new work before transferring resources* or shutting down HP.]),
|
||||
([Clock transition],[AON sequences quiesce, drain, safe source and qualification.],[Run the software transition from safe memory; obey timeout and capability.]),
|
||||
([HP cache / drain phase],[HP receives a cache-clean window before admission is blocked.],[Complete shared-range maintenance and acknowledge before drain.]),
|
||||
([HP cache / drain phase],[HP receives a cache-clean window before admission is blocked.],[Complete shared-range maintenance and *acknowledge before drain*.]),
|
||||
([HP stopped / reset],[LP retains recovery authority; fabric and memory remain separately controlled.],[Check actual hardware status before selecting debug or reinitializing HP.]),
|
||||
([Fault recovery],[Sticky status identifies clock, access, drain or target errors.],[Capture evidence, stop affected producers and follow the relevant reset/isolation contract.])),
|
||||
widths:(0.9fr,1.55fr,1.65fr))
|
||||
@@ -19,7 +20,7 @@ fabric and stable memory clock available for management recovery and other maste
|
||||
==== Controlled clock changes
|
||||
+ Inspect the current clock status and capability. The publication reference profile keeps
|
||||
the PLL disabled; the generic eight-selector model does not establish eight silicon speed grades.
|
||||
+ Place the transition routine and required state in a safe memory region. Disable affected
|
||||
+ Place the transition routine and required state in a *safe memory region*. Disable affected
|
||||
interrupts and quiesce frequency-sensitive transfers, DMA and external serial transactions.
|
||||
+ Use #code("rs_clock_set_frequency()") with a bounded timeout. Let the hardware controller
|
||||
perform its safe-source and lock qualification sequence; do not write raw PLL fields in parallel.
|
||||
@@ -66,3 +67,5 @@ before accessing a serial-memory aperture.
|
||||
#source-note("docs/lp-hp-architecture.md",title:"AON lifecycle, warm flush and memory-pad retention")
|
||||
#source-note("docs/hazard3-debug.md",title:"Management debug-reset scope")
|
||||
#source-note("crt/src/hal/sysctrl.c",title:"Requested and actual HP status exposed by the HAL")
|
||||
|
||||
#change-end("v05-emphasis-operating-states")
|
||||
@@ -3,13 +3,14 @@
|
||||
|
||||
// Publication status is explicit; successful build/tests do not change these marks.
|
||||
#let artifact-status = (
|
||||
(name:"Available",selected:true),
|
||||
(name:"Functional",selected:false),
|
||||
(name:"Reproduced",selected:false),
|
||||
(name:"Tapedout",selected:false),
|
||||
(name:"Available",fill:"full"),
|
||||
(name:"Functional",fill:"left-half"),
|
||||
(name:"Reproduced",fill:"empty"),
|
||||
(name:"Tapedout",fill:"empty"),
|
||||
)
|
||||
|
||||
#cover(evaluation:artifact-status)[
|
||||
#change-start("v05-emphasis-cover","Cover contact, partial Functional mark and selected feature emphasis")
|
||||
#change-start("v05-product-brief","v0.5 document identity and implemented accelerator features")
|
||||
#text(9pt, weight: "semibold", fill: gold)[PRODUCT DATASHEET / #doc.status]
|
||||
#v(rhythm.cover-gap)
|
||||
@@ -21,7 +22,7 @@
|
||||
#v(rhythm.cover-meta-gap)
|
||||
#grid(columns: (1fr, 1fr),
|
||||
[*#doc.document_id* · v#doc.version \ #doc.date],
|
||||
align(right)[#doc.author \ #doc.maintainer],
|
||||
align(right)[#doc.author#link("mailto:"+doc.author_email)[(#doc.author_email)] \ #doc.maintainer],
|
||||
)
|
||||
#v(rhythm.cover-rule-gap)
|
||||
#line(length:100%, stroke:1.1pt + gold)
|
||||
@@ -34,15 +35,15 @@
|
||||
*Compute and control*
|
||||
- Hazard3 LP: boot, clocks, resource ownership and fault recovery.
|
||||
- Dual-issue VexiiRiscv HP: RV32IMAFDC + Zicbom, Sv32.
|
||||
- NPU: 64 dense MACs, eight INT8 operator classes and 64 KiB private SRAM.
|
||||
- NPU: *64 dense MACs*, eight INT8 operator classes and 64 KiB private SRAM.
|
||||
- JTAG debug; fixed EXT-L control and EXT-H AXI64 slots.
|
||||
|
||||
*Memory and interconnect*
|
||||
- 32 KiB banked SRAM in this profile; 4/16/32/64/128 KiB build options.
|
||||
- *32 KiB banked SRAM* in this profile; 4/16/32/64/128 KiB build options.
|
||||
- AXI32 control, native AXI64 data paths and APB4 registers.
|
||||
- SDRAM, QPI PSRAM and OPI/HyperBus-style external-memory controllers.
|
||||
- XPI: four chip selects, 16 LUT sequences, 1/2/4-bit SDR transfers.
|
||||
- Eight DMA channels; linked-list TCDs, 16-beat bursts and stream endpoints.
|
||||
- *Eight DMA channels*; linked-list TCDs, 16-beat bursts and stream endpoints.
|
||||
|
||||
*Platform services*
|
||||
- Two 32-bit timers with 16-bit prescalers; four-channel PWM.
|
||||
@@ -53,8 +54,8 @@
|
||||
|
||||
#colbreak()
|
||||
*Connectivity*
|
||||
- 32 GPIOs: atomic outputs, pin interrupts and two alternate-function selections.
|
||||
- Two UARTs with 64-byte TX/RX FIFOs; UART0 DMA and RTS/CTS.
|
||||
- *32 GPIOs*: atomic outputs, pin interrupts and two alternate-function selections.
|
||||
- Two UARTs with *64-byte TX/RX FIFOs*; UART0 DMA and RTS/CTS.
|
||||
- Two I2C controllers: 7/10-bit addressing and 16-entry command/RX FIFOs.
|
||||
- SPI-SD, two 1/4-bit SDR SDIO hosts and bidirectional PS/2.
|
||||
- USB2: 8 endpoints, 16 host channels, 16 KiB packet RAM; external ULPI PHY.
|
||||
@@ -77,10 +78,12 @@
|
||||
speed grades, electrical limits, production availability or certification. Gen2/Gen2+ is the
|
||||
retained document title; no separate derivative specifications are inferred.]
|
||||
#change-end("v05-product-brief")
|
||||
#change-end("v05-emphasis-cover")
|
||||
]
|
||||
|
||||
#pagebreak()
|
||||
== Overview
|
||||
#change-start("v05-emphasis-overview","Cover-adjacent overview and evidence context")
|
||||
#change-start("v05-overview","NPU-inclusive functional inventory and configuration reference")
|
||||
retroSoC Mini combines a small management processor with an application processor and shared
|
||||
memory and I/O. Hazard3 retains authority over startup, clock transitions, resource ownership
|
||||
@@ -90,6 +93,7 @@ experimentation, education and ASIC prototyping.
|
||||
|
||||
#figure(product-diagram(), caption:[Integrated Mini PRODUCT IP inventory, organized by function.])<product-diagram>
|
||||
|
||||
#change-start("v05-refresh-identity","Reviewed source identity for this same-version revision")
|
||||
#ds-table("profile", [Document reference configuration],
|
||||
([Property], [Reference]),
|
||||
(
|
||||
@@ -103,3 +107,6 @@ experimentation, education and ASIC prototyping.
|
||||
), widths:(0.8fr,1.9fr),
|
||||
)
|
||||
#change-end("v05-overview")
|
||||
#change-end("v05-refresh-identity")
|
||||
|
||||
#change-end("v05-emphasis-overview")
|
||||
@@ -1,16 +1,17 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-performance-reference","Selected body emphasis: performance reference")
|
||||
|
||||
== Performance and Power Characterization <performance-characterization>
|
||||
#change-start("dev-performance","Current benchmark counters and missing performance evidence")
|
||||
This section defines reproducible measurement conditions for the documented implementation.
|
||||
No new hardware measurement was performed for this publication update. The current evidence
|
||||
*No new hardware measurement* was performed for this publication update. The current evidence
|
||||
index contains no matching reviewed performance report, so numerical product results remain
|
||||
unfilled. Configuration frequencies, analytic ceilings and historical projections are not
|
||||
substituted for measurements.
|
||||
unfilled. Configuration frequencies, analytic ceilings and historical projections are *not
|
||||
substituted for measurements*.
|
||||
|
||||
A published result or curve must retain its raw report, workload/transfer size, achieved
|
||||
A published result or curve must retain its *raw report*, workload/transfer size, achieved
|
||||
clock, memory placement and concurrent traffic, together with sample count and measurement
|
||||
boundaries. Use a distinct series for each configuration and show failed or incomplete runs
|
||||
boundaries. Use a distinct series for each configuration and show *failed or incomplete runs*
|
||||
in the supporting report. The evidence summary is @release-verification; the currently empty
|
||||
result fields below remain unmeasured.
|
||||
|
||||
@@ -78,10 +79,14 @@ boundaries and clock changes affect interpretation. A read/write permission matr
|
||||
admission, not bandwidth or latency guarantees.
|
||||
|
||||
=== Boot and power experiments
|
||||
#change-start("v05-refresh-boot-measurement","Measure current boot checkpoints and bounded polling correctly")
|
||||
Use the loader's existing checkpoint messages or a reviewed instrumentation change with defined
|
||||
timing boundaries. Separate simulator elapsed time from wall-clock tool duration. The current
|
||||
ready wait has no firmware-local deadline; report the external observation timeout when boot
|
||||
does not complete. Avoid timing a debugger-halted run as a normal boot.
|
||||
timing boundaries. Separate initial readiness from the complete acceptance/cache-clean sequence,
|
||||
and simulator elapsed time from wall-clock tool duration. The HP loader uses bounded polling
|
||||
iterations; those counts are not milliseconds or a guarantee against stalled MMIO. Report
|
||||
the actual failure stage and external observation timeout if the run cannot progress. Avoid
|
||||
timing a debugger-halted run as a normal boot.
|
||||
#change-end("v05-refresh-boot-measurement")
|
||||
|
||||
For power, identify each rail and exclude or separately report the external PHY, memory and
|
||||
board regulators. Record LP/HP state, active peripherals and duty cycle. Gate-level estimates
|
||||
@@ -94,7 +99,7 @@ electrical conditions remain those of @electrical-specifications.
|
||||
|
||||
= Known Limitations and Revision Compatibility <known-limitations>
|
||||
#change-end("dev-performance")
|
||||
#change-start("dev-limitations","Current feature gates and revision limitations")
|
||||
#change-start("v05-refresh-limitations","Current feature gates and revision limitations")
|
||||
The following items describe the reviewed implementation and its publication boundary. They
|
||||
are not silicon errata for an identified manufactured part. A new source revision requires
|
||||
review of both the limitation and the proposed workaround; a document version alone cannot
|
||||
@@ -144,4 +149,6 @@ that snapshot, and record changed offsets, field meanings or reset behavior in a
|
||||
before claiming backward compatibility. This publication adds no hardware or software ABI.
|
||||
#source-note("publications/datasheets/system-reference.json",title:"Versioned limitation and evidence index")
|
||||
#source-note("publications/datasheets/register-profiles.json",title:"Published register extraction boundary")
|
||||
#change-end("dev-limitations")
|
||||
#change-end("v05-refresh-limitations")
|
||||
|
||||
#change-end("v05-emphasis-performance-reference")
|
||||
@@ -1,9 +1,10 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-pins","Selected body emphasis: pins")
|
||||
|
||||
== Packaging
|
||||
=== Pin Mapping
|
||||
The following inventory describes the logical signal-pad ABI. It does not assign package pin
|
||||
numbers, die-pad sequence numbers or FPGA ball locations. Numeric suffixes in bus signal names
|
||||
The following inventory describes the *logical signal-pad ABI*. It *does not assign package pin
|
||||
numbers*, die-pad sequence numbers or FPGA ball locations. Numeric suffixes in bus signal names
|
||||
identify signal indices only. Power pads are technology-wrapper additions and are not assigned
|
||||
physical package numbers here.
|
||||
|
||||
@@ -14,7 +15,7 @@ together. Reset electrical properties require the selected PDK and board specifi
|
||||
|
||||
#note[SDIO1 and USB2 ULPI have dedicated pad groups that are intentionally unbound in the generic
|
||||
FPGA wrapper until board pin locations, 3.3 V I/O-bank allocation and timing are approved.
|
||||
Do not derive a package drawing from the order of rows in this table.]
|
||||
*Do not derive a package drawing from the order of rows* in this table.]
|
||||
|
||||
#ds-table("pads", [Logical signal-pad inventory - reference profile],
|
||||
([Signal pad], [RTL direction], [Pad kind]),
|
||||
@@ -96,3 +97,5 @@ availability for that exact part. The source SHA and draft document version iden
|
||||
publication; they are not a manufactured-device marking or a sales part number.
|
||||
|
||||
#include "electrical-reference.typ"
|
||||
|
||||
#change-end("v05-emphasis-pins")
|
||||
@@ -1,9 +1,10 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-processor-details","Selected body emphasis: processor details")
|
||||
#let cpu = data.system_reference.product_details.cpu
|
||||
|
||||
=== Processor Configuration and Software-visible Capabilities <processor-details>
|
||||
The table separates the actual LP instance arguments, the explicit HP generator settings and
|
||||
the selected firmware build. It is a configuration summary, not a replacement for the CPU
|
||||
the selected firmware build. It is a *configuration summary*, not a replacement for the CPU
|
||||
ISA/CSR manuals. A software compiler option does not remove a hardware extension or CSR block.
|
||||
|
||||
#ds-table("processor-config",[Processor settings and the reference software configuration],
|
||||
@@ -23,14 +24,14 @@ ISA/CSR manuals. A software compiler option does not remove a hardware extension
|
||||
The reference LP build uses #code(cpu.build.ISA) with #code("HAVE_CSR="+cpu.build.HAVE_CSR).
|
||||
Those build choices are separate from the instantiated LP extension and mandatory CSR settings.
|
||||
The HP profile selects #code(cpu.build.HP_CONFIG). OpenSBI, the device tree and the kernel
|
||||
configuration must remain consistent with the core that is actually generated and used.
|
||||
configuration *must remain consistent with the core that is actually generated and used*.
|
||||
|
||||
==== Cache geometry and evidence basis
|
||||
#ds-table("processor-cache-evidence",[Cache and generated-core evidence boundaries],
|
||||
([Item],[Recorded configuration],[Qualification]),
|
||||
(([HP instruction cache],[Enable setting #cpu.hp.fetchL1Enable with #cpu.hp.fetchL1Sets sets and #cpu.hp.fetchL1Ways ways; minimum memory data width #cpu.hp.fetchMemDataWidthMin bits.],[Explicit generator settings.]),
|
||||
([HP data cache],[Enable setting #cpu.hp.lsuL1Enable with #cpu.hp.lsuL1Sets sets and #cpu.hp.lsuL1Ways ways; minimum memory data width #cpu.hp.lsuMemDataWidthMin bits.],[Explicit generator settings.]),
|
||||
([Cache total capacity],cpu.hp_cache_capacity,[Sets multiplied by ways is not a byte capacity without the reviewed block size.]),
|
||||
([Cache total capacity],cpu.hp_cache_capacity,[Sets multiplied by ways is *not a byte capacity* without the reviewed block size.]),
|
||||
([Cache maintenance],[Zicbom selected; supplied platform metadata declares a 64-byte CBO block.],[Keep platform metadata and the eventual generated implementation consistent.]),
|
||||
([Locked HP source],[#code(cpu.hp_revision.slice(0,12))],[The full dependency revision is recorded in the lock and publication manifest.]),
|
||||
([Generated HP artifact],cpu.generated_artifact_basis,[No new HP RTL generation or independent generated-manifest validation was performed for this publication.])),
|
||||
@@ -62,3 +63,5 @@ two harts into a symmetric cache-coherent SMP platform.
|
||||
#source("scripts/generate_vexiiriscv.py",title:"Artifact manifest") ·
|
||||
#source("app/ports/linux/linux/retrosoc_hp.dts",title:"HP platform properties")
|
||||
]
|
||||
|
||||
#change-end("v05-emphasis-processor-details")
|
||||
@@ -1,9 +1,11 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-product-use","Selected body emphasis: product use")
|
||||
#change-start("dev-product-availability","Current IP availability and media-composition limits")
|
||||
#import "../system-figures.typ": *
|
||||
#change-start("v05-refresh-product-use","Current resource summaries and Linux acceptance boundary")
|
||||
|
||||
== Product Configuration and Feature Availability <product-configuration>
|
||||
This publication describes one reviewed integration, not every combination of build options.
|
||||
This publication describes *one reviewed integration*, not every combination of build options.
|
||||
Use the configuration identity with the IP capability registers before selecting a firmware
|
||||
image, external component or operating-system driver. An integrated controller may still need
|
||||
board wiring, a technology macro or additional software. A reserved address range is not an IP.
|
||||
@@ -25,7 +27,7 @@ profile. Other committed technology profiles must be checked independently for a
|
||||
The following rows cover every actual IP chapter, including the two MPW-only examples.
|
||||
Repeated instances have separate rows where their routing differs; shared functional blocks
|
||||
such as the dual timer and dual I2C retain their documented instance counts in the scope column.
|
||||
"Integrated" describes the documented digital block, not a qualified silicon feature.
|
||||
"Integrated" describes the documented digital block, *not a qualified silicon feature*.
|
||||
"Partial" identifies an explicit implementation or qualification boundary.
|
||||
#ds-table("feature-availability",[IP availability and system dependencies],
|
||||
([IP / status],[Implemented scope],[Integration dependency]),
|
||||
@@ -48,7 +50,7 @@ does not establish all optional modes in a standard or a compliance certificate.
|
||||
+ Match the firmware or Linux path to the support matrix in @software-support. Keep unsupported
|
||||
resources under LP control until an appropriate driver and handoff protocol are supplied.
|
||||
|
||||
On a probe mismatch, stop initialization and report the image/profile and diagnostic identity.
|
||||
On a probe mismatch, *stop initialization* and report the image/profile and diagnostic identity.
|
||||
Reserved or disabled registers do not prove compatibility; see @known-limitations.
|
||||
#block(above:5pt,below:0pt)[
|
||||
#text(9pt)[#source("publications/datasheets/mini.json",title:"Configuration identity") ·
|
||||
@@ -96,9 +98,11 @@ SBI-based, even though OpenSBI accesses UART1 underneath. Native custom peripher
|
||||
and an application resource-handoff service are separate work.
|
||||
|
||||
Before boot, validate the external memory configuration and the exact bundle generated for
|
||||
the selected snapshot. After boot, an expected mailbox event provides the acceptance marker;
|
||||
it does not establish that all peripheral drivers or workloads have been validated. Follow
|
||||
@boot-configuration for failure handling, including the unbounded firmware-local ready wait.
|
||||
the selected snapshot. The Linux rootfs publishes an initial ready event. The current HP
|
||||
acceptance loader also requires GA2D result, cache-clean and resource-return checkpoints;
|
||||
the rootfs ready service does not implement those later exchanges. Follow @boot-configuration
|
||||
for the bounded polling budgets, matching acceptance payload and failure/ownership policy.
|
||||
Neither an initial event nor a complete acceptance pass establishes all Linux peripheral drivers.
|
||||
|
||||
=== Camera and audio data paths
|
||||
#change-start("system-media", "Camera and audio circuit composition")
|
||||
@@ -128,3 +132,6 @@ the conditions in @performance-characterization rather than adding individual IP
|
||||
#source-note("app/README.md",title:"Application and middleware ownership")
|
||||
#source-note("app/ports/linux/README.md",title:"Current HP Linux composition")
|
||||
#source-note("docs/axi4-stream.md",title:"DMA, audio and camera stream integration")
|
||||
#change-end("v05-refresh-product-use")
|
||||
|
||||
#change-end("v05-emphasis-product-use")
|
||||
@@ -1,9 +1,16 @@
|
||||
#import "../style.typ": *
|
||||
Clock values above describe the selected digital configuration, not characterized maximum
|
||||
frequencies. Larger memory-map apertures describe addressability and do not imply fitted devices.
|
||||
#change-start("v05-emphasis-reading","Selected body emphasis: reading")
|
||||
Clock values above describe the selected digital configuration, *not characterized maximum
|
||||
frequencies*. Larger memory-map apertures describe addressability and *do not imply fitted devices*.
|
||||
|
||||
== Reading this datasheet
|
||||
The architecture and peripheral sections describe PRODUCT mode unless explicitly marked MPW.
|
||||
Address, LP IRQ, pad and access-matrix tables are generated from the same reviewed inputs used
|
||||
by the SoC integration. Per-IP references point to detailed contracts or executable sources at
|
||||
the recorded commit. Features marked *partial*, *prototype* or *TBD* are not qualified product claims.
|
||||
the recorded commit. Features marked *partial*, *prototype* or *TBD* are *not qualified product claims*.
|
||||
#change-start("v05-refresh-reading", "Link the reading guide to the existing document and evidence map", category: "cross-reference")
|
||||
Use @document-map to choose the relevant address, programming, boot, diagnostic, board or
|
||||
verification reference. It also explains the distinction between implementation and evidence status.
|
||||
#change-end("v05-refresh-reading")
|
||||
|
||||
#change-end("v05-emphasis-reading")
|
||||
@@ -1,4 +1,5 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-register-index","Selected body emphasis: register index")
|
||||
#import "../ip-reference.typ": inline
|
||||
|
||||
= Appendix: Global Register and Address Index <global-register-index>
|
||||
@@ -10,15 +11,15 @@ separate PRODUCT and selected MPW contexts. A shared definition can therefore ap
|
||||
more than one instance base without creating another register ABI.
|
||||
|
||||
Use the absolute address to identify a bank, then follow its register-name link for fields,
|
||||
side effects and software requirements. The offset column is relative to that instance's
|
||||
base for element zero, including the register-group base. An array row denotes
|
||||
#code("first address + n * stride") only for its printed index range; gaps between elements
|
||||
are not additional registers. All accesses shown are 32 bits, subject to the individual
|
||||
side effects and software requirements. The offset column is *relative to that instance's
|
||||
base* for element zero, including the register-group base. An array row denotes
|
||||
#code("first address + n * stride") only for its printed index range; *gaps between elements
|
||||
are not additional registers*. All accesses shown are 32 bits, subject to the individual
|
||||
byte-strobe and permission rules in @register-programming.
|
||||
|
||||
Reset text preserves fixed, conditional, dynamic and non-retained meanings from the detailed
|
||||
reference. It does not promise the value of a later live status read. Register addressability
|
||||
also does not grant an initiator access or establish that an optional feature is available.
|
||||
also *does not grant an initiator access* or establish that an optional feature is available.
|
||||
|
||||
#let index = data.system_reference.retrieval.register_index
|
||||
#let bank-table(bank) = {
|
||||
@@ -62,3 +63,5 @@ individual chapters. Mapping, exclusions and instance qualifications are reviewe
|
||||
the canonical topology and the selected register decoder.
|
||||
#source-note("publications/datasheets/register-profiles.json",title:"Shared register families and repeated-bank geometry")
|
||||
#source-note("publications/datasheets/system-reference.json",title:"Register-window mapping and reviewed instance qualifications")
|
||||
|
||||
#change-end("v05-emphasis-register-index")
|
||||
@@ -1,8 +1,9 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-register-programming","Selected body emphasis: register programming")
|
||||
|
||||
== Register Access and Programming Conventions <register-programming>
|
||||
The following conventions explain how to read the IP register chapters. They do not override
|
||||
an individual register's access width, strobe, reset or side-effect contract. Use the current
|
||||
The following conventions explain how to read the IP register chapters. They *do not override
|
||||
an individual register*'s access width, strobe, reset or side-effect contract. Use the current
|
||||
IP version and capability before interpreting a familiar offset from another device or revision.
|
||||
|
||||
For an address-first lookup, use @global-register-index. Its instance-qualified formulas
|
||||
@@ -14,7 +15,7 @@ lead back to the same register definitions used in this chapter's access convent
|
||||
(([RO],[Hardware supplies a value; software writes are not part of the interface.],[Do not assume a write is harmless; an IP can reject it.]),
|
||||
([RW],[Software can update documented writable fields.],[Read-modify-write is valid only when reads and writes have no conflicting side effects.]),
|
||||
([WO / command],[A write submits an action or value; reads need not return the last write.],[Use the command encoding and required state; do not read it to construct another command.]),
|
||||
([W1C / RW1C],[Writing one clears the selected documented status bit.],[Write an explicit acknowledgement mask; a read-modify-write can clear unrelated pending events.]),
|
||||
([W1C / RW1C],[Writing one clears the selected documented status bit.],[Write an *explicit acknowledgement mask*; a read-modify-write can clear unrelated pending events.]),
|
||||
([Set / clear / toggle alias],[A specific IP provides a dedicated operation.],[Use only that IP's documented address/mask; there is no global SoC alias scheme.]),
|
||||
([Read/pop or clear-on-read],[Reading consumes data or changes state.],[Avoid speculative reads, repeated debugger watches and reads used only for display.]),
|
||||
([Live / snapshot],[A live value can change between accesses; a snapshot is captured by a defined operation.],[Use the register's snapshot/latch sequence before combining multiple words.]),
|
||||
@@ -27,8 +28,8 @@ all peripherals. Clear only events already captured by the handler and re-check
|
||||
using the documented sequence before reenabling interrupts.
|
||||
|
||||
=== Access width, byte lanes and alignment
|
||||
Use naturally aligned 32-bit register operations unless the IP explicitly supports another
|
||||
width. APB4 PSTRB support is per register and per instance. A data window can require all four
|
||||
Use *naturally aligned 32-bit register operations* unless the IP explicitly supports another
|
||||
width. APB4 PSTRB support is *per register and per instance*. A data window can require all four
|
||||
byte strobes while adjacent configuration registers accept partial updates. The bus fabric's
|
||||
supported beat sizes do not imply that a byte store is meaningful for every peripheral.
|
||||
|
||||
@@ -84,3 +85,5 @@ describe the result as separate samples rather than claiming an atomic 64-bit re
|
||||
#source-note("docs/ip/dvp.md",title:"DVP PIO/stream exclusion and frame semantics")
|
||||
#source-note("docs/ip/gpio.md",title:"GPIO-specific atomic operations and pad control")
|
||||
#source-note("rtl/ip/peripheral/dma_reg.sv",title:"DMA register legality and busy-state handling")
|
||||
|
||||
#change-end("v05-emphasis-register-programming")
|
||||
@@ -1,18 +1,19 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-release-verification","Selected body emphasis: release verification")
|
||||
|
||||
== Release Verification Summary <release-verification>
|
||||
#change-start("dev-release-evidence","Commit-bound CI outcomes and qualification boundaries")
|
||||
#change-start("v05-refresh-ci","Current commit CI outcomes and installation/check/runtime boundaries")
|
||||
This summary separates the existence of an implementation or test from evidence for a
|
||||
particular release. Every reported pass must identify the reviewed source revision, exact
|
||||
configuration, platform stage and matching report. A newer source-tree result cannot
|
||||
particular release. Every reported pass must identify the *reviewed source revision, exact
|
||||
configuration, platform stage and matching report*. A newer source-tree result cannot
|
||||
silently qualify this publication's older hardware snapshot.
|
||||
|
||||
The current #(data.system_reference.support.len())-IP inventory records
|
||||
#data.system_reference.retrieval.verification.support_counts.at("Source reviewed") source-reviewed entries,
|
||||
#data.system_reference.retrieval.verification.support_counts.at("Tests available") entries with test sources,
|
||||
and #data.system_reference.retrieval.verification.support_counts.at("Reported pass") entries with a matching
|
||||
reported pass. These counts describe publication evidence, not a percentage of functional
|
||||
coverage. See @software-support and @known-limitations for the per-IP qualifications.
|
||||
reported pass. These counts describe publication evidence, *not a percentage of functional
|
||||
coverage*. See @software-support and @known-limitations for the per-IP qualifications.
|
||||
|
||||
=== CI snapshot for the reviewed commit
|
||||
#let ci=data.system_reference.ci_snapshot
|
||||
@@ -26,6 +27,27 @@ per-IP reports tied to the exact profile, test selection and platform stage belo
|
||||
an unfinished workflow has no pass/fail conclusion. Its eventual result must be read from the
|
||||
identified run and cannot qualify stages that it did not execute.
|
||||
|
||||
#let environment-runs=ci.runs.filter(r=>r.at("observations",default:()).len()>0)
|
||||
#if environment-runs.len()>0 {
|
||||
let stage-rows=()
|
||||
let stage-names=("installation":[Installation],"environment-check":[Environment check],
|
||||
"runtime-regression":[Runtime regression])
|
||||
for run in environment-runs {
|
||||
for stage in run.observations {
|
||||
stage-rows.push((link(stage.url,stage.name),stage-names.at(stage.scope),
|
||||
[#stage.status \ #if stage.conclusion==none {[No conclusion yet]} else {stage.conclusion}]))
|
||||
}
|
||||
}
|
||||
ds-table("ci-environment-stages",[Observed development-environment stages],
|
||||
([Entrypoint and step],[Evidence stage],[Status / conclusion]),
|
||||
stage-rows,
|
||||
widths:(2.25fr,0.95fr,1fr))
|
||||
par[Installation, environment checking and runtime regression are *separate observations*.
|
||||
The runtime command includes environment checks followed by the selected behavioral
|
||||
regression. A failure in that combined step does not identify its cause or prove that
|
||||
simulation reached a particular stage. Job links retain the complete step record.]
|
||||
}
|
||||
|
||||
=== Historical reports and current-source gaps
|
||||
#ds-table("historical-accelerator-evidence",[Earlier recorded results and their publication boundary],
|
||||
([Record],[What the repository records],[Current-source interpretation]),
|
||||
@@ -83,4 +105,6 @@ For the ordered checks performed by bringup and CI smoke, see @application-diagn
|
||||
@firmware-application-results. An application's terminal pass qualifies only that selected
|
||||
sequence; controller self-test, CPU interrupt delivery and external-device traffic remain
|
||||
separate coverage statements.
|
||||
#change-end("dev-release-evidence")
|
||||
#change-end("v05-refresh-ci")
|
||||
|
||||
#change-end("v05-emphasis-release-verification")
|
||||
@@ -1,8 +1,9 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-reset-summary","Selected body emphasis: reset summary")
|
||||
|
||||
=== Reset-State Summary and Initialization Dependencies <reset-summary>
|
||||
Distinguish an asserted reset, a reset assignment's initial value and a later software
|
||||
observation. A counter, event flag or external input can change immediately after local reset
|
||||
observation. A counter, event flag or external input *can change immediately after local reset*
|
||||
release. A physical supply ramp is also different from a digital reset transition; board
|
||||
sequencing remains subject to @electrical-specifications.
|
||||
|
||||
@@ -14,9 +15,9 @@ sequencing remains subject to @electrical-specifications.
|
||||
"Fixed" identifies the traced digital reset assignment, not a guarantee that firmware will
|
||||
read that value after arbitrary elapsed time. "Configured" depends on selected integration
|
||||
settings. "Input-dependent" requires the external or technology context, and "Dynamic" must
|
||||
be observed using the IP's live/snapshot rules.
|
||||
be observed using the IP's *live/snapshot rules*.
|
||||
|
||||
The Resource Controller owner flops reset to LP, while its quiesce and resource-reset request
|
||||
The Resource Controller *owner flops reset to LP*, while its quiesce and resource-reset request
|
||||
bits reset clear. Its IRQ outputs combine raw causes with the owner and resource-reset request.
|
||||
Asserting #code("CONTROL.RESET") masks those owner routes; resetting the controller is not a
|
||||
separate universal IRQ-enable policy. Check each producer's local reset, cause and enable state.
|
||||
@@ -37,10 +38,14 @@ separate universal IRQ-enable policy. Check each producer's local reset, cause a
|
||||
+ Configure legal idle DMA/peripheral state and verify bounded operations before releasing HP
|
||||
or starting a sustained producer.
|
||||
|
||||
#change-start("v05-refresh-reset-waits","Separate bounded HP polling from generic startup waits")
|
||||
An initialization dependency is not a fixed delay specification. Prefer documented ready,
|
||||
idle, lock and error observations with bounded software waits. Keep the existing HP-loader
|
||||
ready-wait limitation separate: that loader currently has no firmware-local final Linux-ready
|
||||
deadline, even though other controller waits are bounded.
|
||||
idle, lock and error observations with bounded software waits. The HP loader bounds its
|
||||
ready/result/cache-clean polls by iteration counts, not fixed elapsed time; stalled MMIO can
|
||||
still prevent progress. Its initial ready event is separate from complete acceptance and
|
||||
ownership return. The generic LP CRT's earlier PSRAM-ready loop remains unbounded; see
|
||||
@lp-runtime and @boot-configuration for the distinct startup stages.
|
||||
#change-end("v05-refresh-reset-waits")
|
||||
|
||||
==== Restart and failure handling
|
||||
After a debug or local reset, do not assume unrelated peripherals and clocks returned to their
|
||||
@@ -58,3 +63,5 @@ approved physical implementation for those properties.
|
||||
#source-note("rtl/ip/peripheral/dma_reg.sv",title:"DMA context and interrupt-enable reset assignments")
|
||||
#source-note("rtl/ip/peripheral/gpio_reg.sv",title:"GPIO control reset-flop connections")
|
||||
|
||||
|
||||
#change-end("v05-emphasis-reset-summary")
|
||||
@@ -1,9 +1,10 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-routing-reference","Selected body emphasis: routing reference")
|
||||
#let programming = data.system_reference.programming
|
||||
|
||||
== DMA Request, Interrupt and Event Routing <dma-routing>
|
||||
Request selectors describe pacing or stream endpoints. Channel numbers describe software
|
||||
contexts, and interrupt numbers describe completion delivery. None can be inferred from another.
|
||||
contexts, and interrupt numbers describe completion delivery. *None can be inferred from another*.
|
||||
Central DMA channel conventions are not independent hardware ownership or privilege domains.
|
||||
|
||||
=== Central DMA request map
|
||||
@@ -17,7 +18,7 @@ the other paced clients use peripheral data windows through the MM-to-MM path. S
|
||||
selector zero has no dedicated peripheral request wire. WS2812 uses that software-paced path.
|
||||
|
||||
The endpoint IRQ column identifies the peripheral's own event line where one exists; it is
|
||||
not the DMA transfer-completion interrupt. Central DMA channel events aggregate at the DMA
|
||||
*not the DMA transfer-completion interrupt*. Central DMA channel events aggregate at the DMA
|
||||
resource's LP IRQ or HP PLIC source according to the central resource owner. Crypto has no
|
||||
separate LP vector entry in this integration; inspect its register status and DMA completion path.
|
||||
|
||||
@@ -26,7 +27,7 @@ separate LP vector entry in this integration; inspect its register status and DM
|
||||
([Channel],[Client / convention],[Basis]),
|
||||
programming.channels.map(r=>(str(r.number),r.label,source(r.sources.last(),title:"Driver / allocation source"))),
|
||||
widths:(0.5fr,2.7fr,0.9fr))
|
||||
The bulk convention is shared and must be serialized by the application. XPI accepts an
|
||||
The bulk convention is *shared and must be serialized* by the application. XPI accepts an
|
||||
explicit channel argument, but selecting another number does not bypass an active stream
|
||||
endpoint, resource ownership or buffer-lifetime restriction. Crypto uses separate input/output
|
||||
contexts. The HP boot loader uses its declared boot context; channel 7 remains reserved.
|
||||
@@ -65,3 +66,5 @@ PIO handling or a separately implemented extension; do not discard the partial-w
|
||||
#source-note("crt/include/retrosoc/hal/dma.h",title:"SDK selectors, contexts and descriptor type")
|
||||
#source-note("rtl/mini/top/apb4_periph.sv",title:"Request, stream and PLIC wiring")
|
||||
#source-note("rtl/ip/peripheral/dma_core.sv",title:"Start validation, endpoint exclusion and stream acceptance")
|
||||
|
||||
#change-end("v05-emphasis-routing-reference")
|
||||
@@ -1,4 +1,5 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-software-runtime","Selected body emphasis: software runtime")
|
||||
#import "../system-figures.typ": sequence-diagram
|
||||
#import "../diagram-packages.typ": storage-figures
|
||||
#let sw = data.system_reference.software
|
||||
@@ -6,8 +7,8 @@
|
||||
=== LP ordinary startup <lp-runtime>
|
||||
The firmware's startup implementation is selected before its application entry point. The
|
||||
generic CRT is used unless the application's manifest supplies an explicit CRT replacement.
|
||||
Selecting another linker layout changes placement; it does not by itself replace the startup
|
||||
instructions. The reference bringup build therefore has a different initialization contract
|
||||
Selecting another linker layout changes placement; it *does not by itself replace the startup
|
||||
instructions*. The reference bringup build therefore has a different initialization contract
|
||||
from the dedicated debug and flash-loader images.
|
||||
|
||||
#figure(sequence-diagram((
|
||||
@@ -22,11 +23,11 @@ from the dedicated debug and flash-loader images.
|
||||
With CSR support selected, the generic entry disables global and individual interrupt enables
|
||||
and installs a direct-mode trap vector before the later register/stack initialization. It then
|
||||
configures the PSRAM alternate-function group, requests initialization and waits for READY.
|
||||
The loop contains no software timeout. If it does not finish, neither main nor that application's
|
||||
The loop contains *no software timeout*. If it does not finish, neither main nor that application's
|
||||
TEST_STATUS writer has run; an external simulator or debugger may still observe a timeout.
|
||||
|
||||
This PSRAM initialization precedes the LMA/VMA comparisons. An in-place image or an SRAM linker
|
||||
layout does not skip it when using this generic CRT. Check the actual startup selection before
|
||||
layout *does not skip it* when using this generic CRT. Check the actual startup selection before
|
||||
assuming that an SRAM-resident image is independent of external-memory initialization. See
|
||||
@known-limitations and @connection-constraints for the associated readiness and pad constraints.
|
||||
|
||||
@@ -107,3 +108,5 @@ hardware routes and @fault-code-reference for interpreting captured results.
|
||||
#source-note("crt/src/core/system_irq_handler.c",title:"Registration, supported enables and default dispatch behavior")
|
||||
#source-note("crt/src/core/irq.c",title:"Machine timer/software IRQ example")
|
||||
#include "api-semantics.typ"
|
||||
|
||||
#change-end("v05-emphasis-software-runtime")
|
||||
@@ -1,31 +1,36 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-software","Selected body emphasis: software")
|
||||
#change-start("dev-software","NPU/APU support, boot ownership and current application diagnostics")
|
||||
#import "../figures.typ": *
|
||||
#let boot = data.system_reference.software.boot_acceptance
|
||||
#change-start("v05-refresh-hp-boot","Current bounded HP boot and complete acceptance protocol")
|
||||
|
||||
= Software
|
||||
== Boot Configuration, Initialization and Recovery <boot-configuration>
|
||||
The management hart starts from the reset flash alias. Normal firmware composition and memory
|
||||
placement depend on the committed application and linker profile. The HP acceptance example
|
||||
instead uses the SRAM-resident `hp_boot` image and validates an external boot bundle before
|
||||
instead uses the *SRAM-resident `hp_boot` image* and validates an external boot bundle before
|
||||
releasing HP. It must not be assumed that every bringup image automatically boots Linux.
|
||||
The separate APU P7 acceptance profile performs LP image/model loading and bare-metal HP
|
||||
audio/KWS work; it is not the Linux boot profile. NPU compiler output and HP smoke payloads
|
||||
likewise do not supply a native Linux driver. See @apu and @npu for their software boundaries.
|
||||
|
||||
#figure(boot-diagram(), caption:[HP boot example. Validation failure retains LP recovery control and prevents normal HP handoff.])<boot-flow>
|
||||
#figure(boot-diagram(), caption:[Linux image loading and initial ready checkpoint. The loader's complete acceptance protocol continues below.])<boot-flow>
|
||||
|
||||
The HP bundle contains locked OpenSBI, Linux, device-tree and initramfs inputs. LP validates
|
||||
the header and payload bounds, attempts transfer with the boot DMA context and CRC, and
|
||||
falls back to a software copy/CRC if that attempt fails. It fences memory, clears the LP
|
||||
mailbox interrupt and requests HP release. It then waits for the expected readiness event;
|
||||
it does not publish entry/DTB addresses through a boot mailbox before release.
|
||||
it does not publish entry/DTB addresses through a boot mailbox before release. The same loader
|
||||
also serves freestanding HP acceptance payloads. Its later GA2D/cache-clean protocol is required
|
||||
before a successful TEST_STATUS write; the *initial ready message alone does not complete it*.
|
||||
#source-note("docs/lp-hp-architecture.md", title:"Boot-bundle ABI, lifecycle and failure handling")
|
||||
|
||||
=== Prerequisites and image layout
|
||||
Use the dedicated HP profile for the acceptance loader. It runs from on-chip SRAM and waits
|
||||
for the SDRAM controller to be ready and free of initialization/error state. The software
|
||||
does not choose an arbitrary external device timing configuration during this wait. External
|
||||
flash placement, SDRAM wiring and timing must already match the selected integration.
|
||||
flash placement, SDRAM wiring and timing *must already match the selected integration*.
|
||||
|
||||
#ds-table("hp-image-layout",[HP image locations extracted from the boot-bundle header],
|
||||
([Artifact],[Load address],[Maximum allocation]),
|
||||
@@ -34,7 +39,7 @@ flash placement, SDRAM wiring and timing must already match the selected integra
|
||||
The build uses OpenSBI FW_JUMP with a fixed Linux entry and DTB address, without a U-Boot
|
||||
stage. The bundle header contains a format version, required entry types, lengths, fixed
|
||||
load locations and CRCs. Keep the image builder, package builder, loader header and selected
|
||||
source revision together. A larger image must not be silently truncated to fit its allocation.
|
||||
source revision together. A larger image *must not be silently truncated* to fit its allocation.
|
||||
|
||||
The manual preparation/build entry points are the existing #code("make setup-hp-linux") and
|
||||
#code("make CONFIG=configs/ci/ihp130-hp.mk hp-linux") flows. Setup obtains locked resources;
|
||||
@@ -51,10 +56,34 @@ port guide for the generated output layout and boot packaging commands.
|
||||
total size, fixed entry order, flash bounds, destination bounds and header CRC.
|
||||
+ For each entry, attempt the DMA TCD transfer with expected CRC and check status, transferred
|
||||
length and CRC result. If that attempt fails, execute the existing software-copy/CRC fallback.
|
||||
+ Probe the mailbox, confirm that GA2D is safely idle under LP ownership, transfer it to HP,
|
||||
and confirm HP-owned safe idle. NPU ownership participates only when
|
||||
#code(boot.npu_defines.join(" or ")) is compiled.
|
||||
+ Apply the memory fence, clear the LP mailbox interrupt, request release, and check the
|
||||
immediate HP status result. Observe #code("HP_BOOT_RELEASED") only as a release checkpoint.
|
||||
+ Wait for a nonzero-sequence mailbox message. The expected event/argument reports
|
||||
#code("HP_LINUX_READY") and the common sticky test pass. An unexpected message is a failure.
|
||||
+ Wait for the exact ready event, argument and sequence. #code("HP_LINUX_READY") marks this
|
||||
checkpoint; a freestanding acceptance payload uses the same marker without booting Linux.
|
||||
+ Send the GA2D start command and wait for the result message with its distinct sequence.
|
||||
Confirm GA2D safe idle before requesting HP hold.
|
||||
+ Observe the cache-clean request, receive the cache message, acknowledge clean state and
|
||||
confirm HP held without a forced fault. Return GA2D to LP and verify safe idle; return NPU
|
||||
as well when its acceptance option is enabled. Only then write the sticky successful verdict.
|
||||
|
||||
#ds-table("hp-boot-mailbox-checkpoints",[Required HP-to-LP acceptance messages],
|
||||
([Checkpoint],[Event],[Argument],[Sequence]),
|
||||
boot.messages.map(r=>(r.title,str(r.event),code("0x"+upper(str(r.argument,base:16))),str(r.sequence))),
|
||||
widths:(1.65fr,0.45fr,1.15fr,0.65fr))
|
||||
The ready, result and cache waits each have a firmware polling budget of
|
||||
#boot.event_poll_iterations iterations (#boot.event_poll_multiplier × RS_TIMEOUT_DEFAULT).
|
||||
The budget is *not a duration in milliseconds*, and a stalled MMIO access can prevent loop
|
||||
progress. A different sequence remains pending until the budget expires; matching the sequence
|
||||
with a wrong event or argument fails immediately. A mailbox API error also fails the wait.
|
||||
|
||||
The supplied Linux rootfs service sends *only the initial ready message*. It contains no GA2D
|
||||
command responder or cache-clean service. A Linux init checkpoint therefore does not satisfy
|
||||
the complete current acceptance loader. A matching HP acceptance payload supplies those later
|
||||
responses; deploying a Linux service that does so is additional integration work, not a native
|
||||
graphics-driver capability established by this publication. See @linux-runtime.
|
||||
|
||||
The software fallback computes CRC from bytes read from the source while copying. It performs
|
||||
full destination readback only for entries up to the loader's small-entry threshold; it must
|
||||
@@ -62,25 +91,19 @@ not be described as a complete large-image destination readback test. CRC checks
|
||||
integrity, not image origin or rollback policy.
|
||||
|
||||
=== Failure branches and supervision boundary
|
||||
#ds-table("hp-boot-failures",[HP loader checkpoints and diagnostic result codes],
|
||||
([Checkpoint],[Code / observation],[Result and required response]),
|
||||
(([Console initialization],[1],[Common failed verdict; establish a usable diagnostic path.]),
|
||||
([HP prerequisite state],[2],[HP presence/reset/debug setup did not meet requirements.]),
|
||||
([SDRAM readiness],[3],[Bounded wait failed; inspect memory configuration and controller status.]),
|
||||
([Bundle header],[4],[Reject the bundle; rebuild matching images and header rather than relaxing bounds.]),
|
||||
([Payload loading],[5-8],[Both DMA and software paths failed for the respective entry.]),
|
||||
([Release/checkpoint],[9],[Inspect requested/actual HP state and lifecycle faults.]),
|
||||
([Unexpected ready event],[10],[Check software revisions, mailbox payload and boot epoch.]),
|
||||
([No ready message],[No firmware-local deadline],[The loop keeps waiting. The simulator deadline is external to the loader.])),
|
||||
widths:(1fr,0.85fr,2.25fr))
|
||||
The failure helper requests HP reset and writes a failed test verdict; it does not implement
|
||||
an automatic image retry or signed recovery image selection. A board-level watchdog,
|
||||
supervisor deadline or replacement loader policy is additional integration work. After a
|
||||
failed release or forced stop, inspect actual reset/drain state before reusing HP memory.
|
||||
Use the source-checked result codes in @firmware-application-results for the producing stage;
|
||||
they include missing ready, result and cache-clean checkpoints. The failed verdict alone does
|
||||
not prove that HP, its dirty cache or accepted bus traffic has stopped.
|
||||
The failure helper requests HP hold/reset *only while GA2D is not recorded as HP-owned*.
|
||||
After that handoff, it preserves the ownership state and writes a failed verdict without an
|
||||
unconditional HP reset. Capture actual reset, drain, cache and resource state before recovery
|
||||
or buffer reuse. No automatic image retry or signed recovery image selection is implemented.
|
||||
A board supervisor/watchdog remains a separate protection against stalled accesses or software.
|
||||
|
||||
For target acceptance, capture profile/image hashes, LP load/release checkpoints, the expected
|
||||
Linux readiness event and the final simulator verdict. Do not treat UART startup alone as
|
||||
success. A complete Linux peripheral qualification requires the separate support matrix.
|
||||
For target acceptance, capture profile/image hashes, enabled acceptance options, LP load/release
|
||||
checkpoints, ready/result/cache messages, final ownership and the simulator verdict. Do not treat
|
||||
UART startup or the ready marker alone as success. Linux peripheral qualification requires
|
||||
the separate support matrix and matching platform evidence.
|
||||
|
||||
#block(above:rhythm.metadata-before,below:rhythm.metadata-after,breakable:false)[
|
||||
#set text(size:9pt)
|
||||
@@ -90,6 +113,7 @@ success. A complete Linux peripheral qualification requires the separate support
|
||||
#source("scripts/build_hp_linux.py",title:"OpenSBI FW_JUMP and Linux artifact composition") ·
|
||||
#source("scripts/package_hp_boot.py",title:"Bundle generation and layout checks")
|
||||
]
|
||||
#change-end("v05-refresh-hp-boot")
|
||||
|
||||
|
||||
#include "image-maintenance.typ"
|
||||
@@ -189,6 +213,8 @@ Canonical memory, topology and pin generators emit build-local bindings. Managed
|
||||
toolchains and external inputs are revision-locked. This document does not modify those
|
||||
hardware interfaces or create another register source of truth.
|
||||
|
||||
#include "development-environment.typ"
|
||||
|
||||
== RTL Simulation
|
||||
Verilator and Icarus support behavioral verification; the repository also defines synthesis,
|
||||
netlist simulation, static timing, warning and metric collection flows. The supported PR
|
||||
@@ -227,3 +253,5 @@ and bringup record. Publish the design-file revision with each drawing or downlo
|
||||
and identify which routes were actually tested. The current XDC provides constraints for its
|
||||
named FPGA board; the missing circuit and acceptance records remain listed in @release-verification.
|
||||
#source-note("fpga/mini/starrysky_v2.xdc",title:"Existing board-specific FPGA constraint input")
|
||||
|
||||
#change-end("v05-emphasis-software")
|
||||
@@ -1,12 +1,13 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-system-management","Selected body emphasis: system management")
|
||||
#import "../system-figures.typ": sequence-diagram
|
||||
|
||||
#include "routing-reference.typ"
|
||||
|
||||
== Multicore Operation and Resource Ownership <multicore-operation>
|
||||
Hazard3 is the root-management hart; VexiiRiscv is the application hart. Linux does not take
|
||||
Hazard3 is the *root-management hart*; VexiiRiscv is the application hart. Linux does not take
|
||||
over the SoC's root clock, reset, admission and recovery controls merely by booting. Decide
|
||||
which software owns each resource and buffer before enabling interrupts or bus mastering.
|
||||
which software owns each resource and buffer *before enabling interrupts or bus mastering*.
|
||||
|
||||
=== Control and interrupt authority
|
||||
#ds-table("root-authority",[System authority and software responsibilities],
|
||||
@@ -21,7 +22,7 @@ which software owns each resource and buffer before enabling interrupts or bus m
|
||||
The central Resource Controller covers ten resources: DMA, USB2, SDIO0/1, SPI-SD,
|
||||
EXT-H, JPEG, APU, GA2D and NPU. Resource ABI 1.2 assigns NPU to slot 9.
|
||||
#change-end("v05-resource-ownership")
|
||||
An owner selects one interrupt route, not both LP and HP simultaneously. The resource
|
||||
An owner selects one interrupt route, *not both LP and HP simultaneously*. The resource
|
||||
#code("CONTROL.RESET") request masks both routes; controller reset assignments and dynamic
|
||||
IRQ observations are distinguished in @reset-summary. Owner locks are sticky under their
|
||||
reset contract. Per-IP local interrupt causes
|
||||
@@ -152,3 +153,5 @@ target-timeout and warm-flush conditions need distinct recovery decisions.
|
||||
#source-note("docs/ip/fabric-monitor.md",title:"Counter snapshots and sticky fault attribution")
|
||||
#source-note("docs/axi4-interconnect.md",title:"Timeout, isolation and finite-error contract")
|
||||
#source-note("docs/engineering.md",title:"Simulation verdict and reproducibility rules")
|
||||
|
||||
#change-end("v05-emphasis-system-management")
|
||||
@@ -1,11 +1,12 @@
|
||||
#import "../style.typ": *
|
||||
#change-start("v05-emphasis-usage-appendices","Selected body emphasis: usage appendices")
|
||||
#import "../diagram-packages.typ": storage-figures
|
||||
|
||||
= Appendix: Software Memory and Buffer Requirements <software-memory-budget>
|
||||
Memory-map capacity, image allocation, linked image size and peak runtime use are different
|
||||
quantities. This appendix supplies source-based layouts and illustrative budgets. No matching
|
||||
ELF/MAP files or measured stack/runtime high-water report were available for this update;
|
||||
actual firmware occupation remains unprovided.
|
||||
*actual firmware occupation remains unprovided*.
|
||||
|
||||
== Linker Layout and Runtime Accounting
|
||||
#ds-table("software-memory-accounting",[Memory quantities and the evidence needed to publish them],
|
||||
@@ -15,7 +16,7 @@ actual firmware occupation remains unprovided.
|
||||
([Runtime static memory],[VMA for code/rodata/data/BSS in the chosen linker layout.],[Actual section sizes not supplied. Placement differs between SRAM, SDRAM and PSRAM layouts.]),
|
||||
([Stack / working space],[Linker constraints plus reviewed worst-case or measured runtime demand.],[A stack-top symbol does not reserve or measure a safe stack budget.]),
|
||||
([Boot artifacts],[Loader header allocation bounds and actual package entries.],[Maximum allocations are already listed in the boot chapter; actual image lengths must come from the bundle.]),
|
||||
([DMA and media buffers],[Packing, alignment, lifetime, descriptor count and buffer multiplicity.],[The examples below are calculations, not measured allocations.])),
|
||||
([DMA and media buffers],[Packing, alignment, lifetime, descriptor count and buffer multiplicity.],[The examples below are calculations, *not measured allocations*.])),
|
||||
widths:(1fr,1.7fr,1.5fr))
|
||||
|
||||
The all-SRAM script places the main code/rodata/data/BSS in SRAM with initialized content
|
||||
@@ -38,7 +39,7 @@ Each diagram preserves its actual linker regions and selected startup boundary.
|
||||
|
||||
== Worked Buffer Budgets
|
||||
The examples use 64-byte allocation alignment for shared HP cache-block ownership. This does
|
||||
not replace the peripheral's minimum alignment. Each independent buffer receives its own aligned
|
||||
*not replace the peripheral's minimum alignment*. Each independent buffer receives its own aligned
|
||||
stride so a maintenance operation does not include another owner's boundary bytes.
|
||||
|
||||
#storage-figures("software-memory-budget",section:"software")
|
||||
@@ -115,18 +116,20 @@ qualification. Reserved, unsupported and TBD are different states; use the speci
|
||||
rather than assuming that an absent value is zero or that an address window guarantees a device.
|
||||
|
||||
== Document and Evidence Navigation
|
||||
#change-start("v05-refresh-document-map", "Link the existing task rows to their detailed references", category: "cross-reference")
|
||||
#ds-table("document-navigation",[Where to find an authoritative answer],
|
||||
([Question],[Primary reference],[How to use this datasheet]),
|
||||
(([Addresses, routes and pins],[Canonical memory/topology/pin inputs and generated bindings.],[Use the generated tables and cross-IP route/conflict summaries.]),
|
||||
([Register behavior],[Current RTL, handwritten C definitions and reviewed IP contract.],[Use Register Programming plus the individual register exceptions.]),
|
||||
([Driver sequence],[SDK implementation, platform source and the IP's software contract.],[Follow the supported path and its error/ownership boundaries.]),
|
||||
([LP startup / traps],[Selected CRT, linker and conditional IRQ implementation.],[Use Runtime, SDK and Shell; separate pre-main stalls from application results.]),
|
||||
([Linux readiness],[OpenSBI, generated DTB and rootfs mailbox publisher.],[Follow the platform handoff and distinguish console, ready event and terminal verdict.]),
|
||||
([Diagnostic coverage],[Selected application's actual checks and result branches.],[Use Applications and Firmware Application Results; retain stage logs for repeated codes.]),
|
||||
([Board connection],[Approved board constraints/schematic and selected device/pad specifications.],[Use connection/compatibility tables to identify prerequisites and missing evidence.]),
|
||||
([Validation or performance],[Matching source/profile report, tool versions, device/model and conditions.],[Use the support and characterization sections without promoting source presence to a pass.]),
|
||||
([Publication identity],[This PDF's manifest and matching publication source set.],[Use Sources and Reproducibility for publication-only metadata links.])),
|
||||
(([Addresses, routes and pins],[Canonical memory/topology/pin inputs and generated bindings.],[Use @global-register-index, @dma-routing and @gpio-mux; check @resource-conflicts.]),
|
||||
([Register behavior],[Current RTL, handwritten C definitions and reviewed IP contract.],[Use @register-programming and the owning register's exceptions.]),
|
||||
([Driver sequence],[SDK implementation, platform source and the IP's software contract.],[Start at @software-support; follow @api-completion and @multicore-operation.]),
|
||||
([LP startup / traps],[Selected CRT, linker and conditional IRQ implementation.],[Use @lp-runtime and @irq-runtime; separate pre-main stalls from application results.]),
|
||||
([Linux readiness],[OpenSBI, generated DTB and rootfs mailbox publisher.],[Use @linux-runtime; distinguish console, ready event and terminal verdict.]),
|
||||
([Diagnostic coverage],[Selected application's actual checks and result branches.],[Use @application-diagnostics and @firmware-application-results; retain stage logs for repeated codes.]),
|
||||
([Board connection],[Approved board constraints/schematic and selected device/pad specifications.],[Use @connection-constraints and @device-compatibility for prerequisites and missing evidence.]),
|
||||
([Validation or performance],[Matching source/profile report, tool versions, device/model and conditions.],[Use @release-verification and @performance-characterization; source presence is not a pass.]),
|
||||
([Publication identity],[This PDF's manifest and matching publication source set.],[Use @publication-provenance for publication-only metadata links.])),
|
||||
widths:(0.85fr,1.75fr,1.55fr))
|
||||
#change-end("v05-refresh-document-map")
|
||||
The datasheet presents the reviewed snapshot for integration. Detailed IP contracts explain
|
||||
local behavior; SDK sources show the implemented calling sequence; board guides define a
|
||||
particular physical system; result reports establish only the scope actually tested. Where
|
||||
@@ -134,3 +137,5 @@ an old narrative conflicts with current executable integration, use the current
|
||||
and record the discrepancy rather than silently copying the older statement.
|
||||
#source-note("publications/datasheets/system-reference.json",title:"Publication content and evidence index")
|
||||
#source-note("docs/README.md",title:"Engineering document map")
|
||||
|
||||
#change-end("v05-emphasis-usage-appendices")
|
||||
@@ -1,8 +1,11 @@
|
||||
# Mini Datasheet Layout Standard
|
||||
|
||||
This document records the implemented layout of the English **retroSoC Mini
|
||||
Gen2/Gen2+**, **v0.5 DRAFT**, datasheet. It is a maintenance specification, not a
|
||||
new visual design or a hardware specification. The spacing follows the reviewed
|
||||
This document records the implemented layout and maintenance rules of the English
|
||||
**retroSoC Mini Gen2/Gen2+** datasheet. The current publication identity belongs in
|
||||
[mini.json](mini.json); release-specific decisions and comparisons belong in the
|
||||
[content review](content-review.md) and [chapter review](chapter-review.md).
|
||||
This is a maintenance specification, not a new visual design or a hardware
|
||||
specification. The spacing follows the reviewed
|
||||
ST RM0486 Rev 4 reference, adapted to the retained Mini page width and fonts.
|
||||
|
||||
[style.typ](style.typ), especially its `rhythm` configuration, is the executable
|
||||
@@ -13,6 +16,53 @@ Update this document together with any intentional change to those rules. If
|
||||
documentation and rendering disagree, inspect the implementation and the PDF;
|
||||
do not silently apply an older proposal instead.
|
||||
|
||||
## Content refresh and evidence rules
|
||||
|
||||
Bind each refresh to the complete reviewed dev commit SHA, not a moving branch
|
||||
name or an abbreviated hash. Record when the branch and its CI were checked in
|
||||
UTC; this observation time is separate from the publication date. Recheck before
|
||||
handoff. A later branch advance requires a reviewed source delta before changing
|
||||
the declared snapshot. Preserve unrelated work and the frozen structure, stable
|
||||
anchors and existing layout unless that change is explicitly in scope.
|
||||
|
||||
Review every frozen chapter entry against its declared scope. If the current
|
||||
implementation and document are already adequate, state that they are retained
|
||||
and give only a concrete maintenance recommendation. Distinguish a documentation
|
||||
correction, an implementation/specification discrepancy and a missing evidence
|
||||
record. A new version number, more pages or repeated caveats do not improve
|
||||
coverage by themselves. Keep the previous delivered PDF and its digest as the
|
||||
comparison baseline even when the publication version and date are unchanged.
|
||||
|
||||
Check the same fact in Features, product/support summaries, tables, detailed
|
||||
prose, code examples and diagrams. Follow the actual configuration, producing
|
||||
branch and lifecycle conditions; a source snippet that still matches is not
|
||||
proof that its surrounding description is current. Update inconsistent summaries
|
||||
with their detailed reference, and retain configuration-dependent and unsupported
|
||||
cases. Do not change RTL, SDK APIs or engineering contracts to fit publication text.
|
||||
|
||||
Separate implemented code, default-enabled/advertised capability, available test
|
||||
facilities, executed tests and physical qualification. A successful report needs
|
||||
its complete source SHA, profile, platform/runtime stage, workload, result and
|
||||
original artifact. Distinguish an ordinary Linux path from a freestanding HP
|
||||
acceptance payload even when they use the same mailbox value or log marker.
|
||||
Describe polling budgets in their implemented units and follow every prerequisite
|
||||
through terminal completion; a ready event or early return is not the final pass.
|
||||
|
||||
For CI, retain the complete source SHA, UTC observation time, run URL, status,
|
||||
nullable conclusion and job/step scope. Pending, failed prerequisites, skipped
|
||||
downstream tests and completed tests must remain distinguishable. A workflow pass
|
||||
is not an exact-profile IP report; a workflow failure does not prove every runtime
|
||||
stage failed. Prior test counts and narrative summaries are historical until the
|
||||
matching current run and artifacts are reviewed. Never convert a missing corpus,
|
||||
tool or report into a successful execution or physical result.
|
||||
|
||||
Use official commercial references to improve organization and clarity. Record
|
||||
document identity, version/revision, release date, check date and relevant sections
|
||||
in the content review, together with the specific organization adopted. Do not
|
||||
transfer product features, electrical limits, performance figures, certification
|
||||
claims or a vendor's release-status policy into Mini. Source/spec discrepancies
|
||||
and missing measurements need explicit follow-up advice, not invented values.
|
||||
|
||||
## System-use content and evidence
|
||||
|
||||
The publication includes a complete system-use reference around the detailed IP
|
||||
@@ -229,9 +279,10 @@ their actual device and report revisions. Missing physical data remain unprovide
|
||||
Runtime, SDK and Shell owns ordinary LP startup, selected linker/CRT behavior and
|
||||
conditional exception/IRQ support. Distinguish hardware CSRs from HAVE_CSR and
|
||||
CSR_ENABLE, handler registration from enable/acknowledgement, and generic CRT
|
||||
initialization from an APP_CRT_SRCS replacement. A linker selection alone does
|
||||
not remove the generic PSRAM-ready wait. Source loops without a local deadline
|
||||
must remain identified; no new timeout or automatic TEST_STATUS result is implied.
|
||||
initialization from an APP_CRT_SRCS replacement. Read the selected startup guards
|
||||
as well as linker placement before claiming a wait is present or bypassed.
|
||||
Source loops without a local deadline must remain identified; no new timeout or
|
||||
automatic TEST_STATUS result is implied.
|
||||
|
||||
Linux and Driver Status owns the supplied OpenSBI/DT/kernel/rootfs handoff.
|
||||
Separate software template declarations from the generated core and actual clock
|
||||
@@ -338,6 +389,31 @@ spans for each new editing round so a prior round's changes are not relabeled as
|
||||
|
||||
## Page, typography and color
|
||||
|
||||
### Selective emphasis in body content
|
||||
|
||||
Use **Inter Bold (weight 700)** for explicitly selected key phrases, retaining
|
||||
the surrounding font size and color. Emphasize decisive capabilities/parameters,
|
||||
prerequisites, required operation order, restrictions, failure conditions and
|
||||
evidence boundaries. Normally select one to three short spans in a paragraph;
|
||||
do not bold entire paragraphs, tables or every numerical value. Review each
|
||||
chapter rather than applying a global keyword rule.
|
||||
|
||||
Handwritten Typst uses `*strong spans*`. Publication JSON and imported prose use
|
||||
explicit `**strong spans**` through the IP inline renderer. It preserves emphasis
|
||||
across adjacent text and inline code; backtick code remains opaque, including
|
||||
literal asterisks. This is a limited inline grammar, not executable Typst or a
|
||||
general Markdown interpreter. Preserve code, addresses and register identifiers
|
||||
in regular FiraCode. Avoid unmatched delimiters and verify mixed text/code output.
|
||||
|
||||
Heading, table-header and Contents rules remain separate. Do not propagate body
|
||||
emphasis into diagram labels, waveforms, register bit cells or source links.
|
||||
In particular, preserve the 172 mm architecture's regular 8 pt CDC/Gateway,
|
||||
bold 9 pt bus/domain and regular 9 pt remaining labels. Reflow longer bold text
|
||||
without shrinking type. Check representative long tables, section transitions,
|
||||
color/grayscale output and actual embedded Bold glyphs in the resulting PDF.
|
||||
|
||||
### Base typography
|
||||
|
||||
| Element | Current rule |
|
||||
| --- | --- |
|
||||
| Paper | A4 portrait, 210 x 297 mm, including the matrix page |
|
||||
@@ -485,6 +561,13 @@ Retain the page break after each complete directory and avoid additional blank
|
||||
pages. The two figure-directory titles are unnumbered, excluded from Contents,
|
||||
included as PDF bookmarks, and used as the running header on their pages.
|
||||
|
||||
Reading this datasheet links to the existing Terminology, Notation and Document
|
||||
Map appendix. Its existing question-based navigation table links to the relevant
|
||||
internal anchors; keep those destinations meaningful and checked. Improve this
|
||||
single navigation table rather than adding another reader guide or duplicating
|
||||
the detailed reference material. Navigation edits do not change the frozen
|
||||
heading hierarchy or remove deeper PDF bookmarks.
|
||||
|
||||
Level-one Contents chapter numbers and complete titles use bold Inter. Dot
|
||||
leaders and page numbers remain regular. Keep the rule local to Contents;
|
||||
body headings, bookmarks and both flat figure/table directories are unaffected.
|
||||
@@ -665,6 +748,12 @@ with approximately 3 pt extra between items. Keep all six groups, both columns,
|
||||
the Integration Note to accommodate this rhythm, not smaller type or an extra
|
||||
page.
|
||||
|
||||
Keep `author` and `author_email` separate in the document identity. The cover
|
||||
contact reads exactly `Yuchi Miao(miaoyuchi@ict.ac.cn)`, with no space before the
|
||||
opening parenthesis; the parenthesized address links to `mailto:miaoyuchi@ict.ac.cn`.
|
||||
PDF author metadata remains `Yuchi Miao`. Retain the maintenance organization,
|
||||
metadata row alignment and single-page cover.
|
||||
|
||||
The Product Brief heading shares a normal-flow row with an Artifact Evaluation
|
||||
component at the right. Keep the original heading body, numbering, contents
|
||||
entry and bookmark unchanged; the component is separate display content, not a
|
||||
@@ -673,9 +762,15 @@ numbered figure or an additional heading.
|
||||
The outer box is 92 x 10 mm with a 1.5 mm corner radius, a 0.6 pt ink border and
|
||||
white fill (no gray background). Four equal columns show **Available**, **Functional**, **Reproduced**
|
||||
and **Tapedout**, with 9 pt Inter Regular labels above 3 mm circles. The current
|
||||
explicit `artifact-status` configuration in `sections/overview.typ` fills only
|
||||
Available in the existing pale gold (`#F4EFE4`), with a 0.6 pt gold outline;
|
||||
the other circles are white with 0.6 pt ink outlines.
|
||||
explicit `artifact-status` configuration in `sections/overview.typ` uses the
|
||||
states `full`, `left-half` and `empty`, not a selected/unselected boolean.
|
||||
Available is fully pale gold (`#F4EFE4`). Functional has the **vertical left
|
||||
semicircle** filled in the same pale gold and its right semicircle white; split
|
||||
at the circle center, without an extra divider line. Both retain a complete
|
||||
0.6 pt gold circular outline. Reproduced and Tapedout remain white with 0.6 pt
|
||||
ink outlines. Use clipped native vector geometry, not a font glyph or raster.
|
||||
The half mark denotes partial functional status, not complete verification or
|
||||
qualification; it does not alter the scoped evidence tables or per-IP results.
|
||||
Keep 4 mm between the heading and box, and vertically center the heading against
|
||||
the box body. The unnumbered 9 pt black label **Artifact Evaluation** is centered
|
||||
2 pt below the box. These are native Typst vector shapes and grid content, not
|
||||
@@ -694,32 +789,21 @@ Do not achieve this by absolute positioning or shrinking the text.
|
||||
|
||||
### Specialized diagram packages
|
||||
|
||||
#### Implementation refresh and evidence scope
|
||||
#### Source-bound diagram maintenance
|
||||
|
||||
The 2026-09-22 v0.5 refresh adds NPU after APU: 42 IP entries and 109 frozen
|
||||
structural records. Preserve the previous anchors and add source-bound NPU
|
||||
functional, descriptor/parameter, storage, protocol, register and HAL material.
|
||||
Keep the APU `(partial)` title while MP3 remains unsupported and KWS is explicitly
|
||||
configuration-dependent. Default PRODUCT and P7 acceptance identities are separate.
|
||||
Audit semantics as well as source snippets: a binding that still matches code
|
||||
does not prove that every surrounding capability or limitation sentence is true.
|
||||
Retain the reviewed IP inventory and its functional, descriptor/parameter,
|
||||
storage, protocol, register and HAL material when it remains accurate. Keep
|
||||
source-level logical storage distinct from a completed technology-macro
|
||||
implementation. Configuration-dependent capabilities and delivery restrictions
|
||||
must agree between diagrams, summaries and the owning IP reference.
|
||||
|
||||
Separate implemented code, default-enabled/advertised capability, test facilities,
|
||||
matching successful runs and physical qualification. Record CI revision, checked
|
||||
date, run URL, status, nullable conclusion and scope, including failed prerequisites and skipped
|
||||
downstream tests. A workflow pass is not a substitute for an exact-profile IP
|
||||
report and behavioral-only regression is not synthesis, netlist, STA or silicon.
|
||||
Do not fill electrical, thermal, power or throughput fields with borrowed device
|
||||
figures, target clocks or analytic ceilings.
|
||||
Never promote a historical narrative or a smoke test that did not execute its
|
||||
full workload into a current-revision Reported pass. Record missing raw artifacts
|
||||
and source/spec discrepancies as explicit recommendations. In particular, APU's
|
||||
inferred KWS storage must not be described as a completed macro implementation.
|
||||
|
||||
Use `v05-` for new content and activate only the reviewed existing content,
|
||||
navigation and revision markers listed in `current-change`. NPU is added;
|
||||
retained GA2D/APU and system material is modified. Earlier closing-page work
|
||||
must not be relabeled as new content. Pagination movement remains separate.
|
||||
Choose a distinct marker prefix for each editing round and record it in the
|
||||
content review and `mini.json.change_prefix`. The renderer reads that prefix;
|
||||
build/check and change reporting reject markers from earlier rounds. Only the
|
||||
three navigation-directory identifiers may be shared, with navigation status.
|
||||
Activate only the reviewed content and revision markers through `current-change`.
|
||||
Retained chapters and previous figure work
|
||||
must not be relabeled as newly added. Keep pagination movement separate.
|
||||
|
||||
Use the existing Overview icon artwork, including its reverted outline style.
|
||||
The six Multimedia entries use two rows of three cells within the same
|
||||
@@ -992,7 +1076,7 @@ The catalog records semantic node roles, clock sources, gateway inputs/output,
|
||||
literal interface widths, stream connections, source files and external pin
|
||||
groups. Validate those against current sources and include them in the manifest.
|
||||
Record the CeTZ category in the 109-entry coverage report and require the actual
|
||||
render. The v0.5 specialized inventory has 142 figures, including the new NPU
|
||||
render. The reviewed specialized inventory has 142 figures, including the NPU
|
||||
circuit, descriptor/parameter layouts and storage views. Preserve the existing
|
||||
package renderers and use source-bound content for every changed figure.
|
||||
|
||||
|
||||
@@ -66,12 +66,9 @@
|
||||
}
|
||||
|
||||
#let minor-title(body) = block(above:rhythm.minor-before,below:rhythm.minor-after,sticky:true,strong(body))
|
||||
// v0.5: only this refresh's reviewed content and dependent navigation markers.
|
||||
#let current-change(id) = id.starts-with("v05-") or id in (
|
||||
"soc-functional","dev-architecture","dev-product-availability","dev-media-formats",
|
||||
"dev-ip-apu","dev-ip-resource","dev-ip-monitor","dev-ip-i2s","ga2d-chapter",
|
||||
"dev-performance","dev-limitations","dev-release-evidence","dev-software",
|
||||
"revision-history","contents","table-directory","figure-directory")
|
||||
// Only this editing round emits active ranges; earlier markers remain historical.
|
||||
#let current-change(id) = id.starts-with(doc.change_prefix) or id in (
|
||||
"contents","table-directory","figure-directory")
|
||||
#let change-start(id, title, category:"modified") = context {
|
||||
if current-change(id) {metadata((
|
||||
kind:"publication-change-start",id:id,title:title,category:category,page:here().page()))}
|
||||
@@ -84,6 +81,21 @@
|
||||
#set par(leading:rhythm.small-leading,spacing:rhythm.small-spacing)
|
||||
#body
|
||||
]
|
||||
#let artifact-mark(state) = {
|
||||
assert(state in ("empty", "left-half", "full"), message:"Unknown artifact mark")
|
||||
box(width:3mm,height:3mm)[
|
||||
#place(top + left,circle(radius:1.5mm,fill:white,stroke:none))
|
||||
#if state=="left-half" {
|
||||
place(top + left,box(width:1.5mm,height:3mm,clip:true)[
|
||||
#circle(radius:1.5mm,fill:pale-gold,stroke:none)
|
||||
])
|
||||
} else if state=="full" {
|
||||
place(top + left,circle(radius:1.5mm,fill:pale-gold,stroke:none))
|
||||
}
|
||||
#place(top + left,circle(radius:1.5mm,fill:none,
|
||||
stroke:0.6pt + if state=="empty" {ink} else {gold}))
|
||||
]
|
||||
}
|
||||
#let artifact-evaluation(states) = rect(width:92mm,height:10mm,radius:1.5mm,
|
||||
fill:white,stroke:0.6pt + ink,inset:(x:2mm,y:1mm))[
|
||||
#set text(size:9pt,weight:"regular",fill:ink)
|
||||
@@ -91,9 +103,7 @@
|
||||
#align(center + horizon)[
|
||||
#grid(columns:(1fr,1fr,1fr,1fr),row-gutter:2pt,align:center,
|
||||
..states.map(state=>state.name),
|
||||
..states.map(state=>circle(radius:1.5mm,
|
||||
fill:if state.selected {pale-gold} else {white},
|
||||
stroke:0.6pt + if state.selected {gold} else {ink})),
|
||||
..states.map(state=>artifact-mark(state.fill)),
|
||||
)
|
||||
]
|
||||
]
|
||||
@@ -187,7 +197,7 @@
|
||||
set text(fill:if text.fill==link-color {link-color} else {inline-code-color})
|
||||
body
|
||||
}
|
||||
#let code(value) = inline-code(text(font: mono, size: 9pt,
|
||||
#let code(value) = inline-code(text(font: mono, size: 9pt, weight:"regular",
|
||||
value.replace("_", "_\u{200b}").replace(".", ".\u{200b}")))
|
||||
#let source(path, title: "Interface and implementation reference", line:none) = {
|
||||
// Publication metadata can postdate the frozen hardware commit. Route readers
|
||||
@@ -303,6 +313,7 @@
|
||||
set document(title: doc.title, author: doc.author,
|
||||
keywords: ("retroSoC", "Mini", "Gen2", "Gen2+", "datasheet", doc.document_id, "v"+doc.version, doc.status))
|
||||
set text(font: "Inter", size: 10.5pt, fill: ink, lang: "en", weight: "regular")
|
||||
show strong: it => text(weight:"bold",it.body)
|
||||
set par(justify: false, leading: rhythm.body-leading, spacing: rhythm.body-spacing,first-line-indent:0pt)
|
||||
set list(indent:rhythm.list-indent,body-indent:rhythm.list-body-indent,spacing:rhythm.list-spacing)
|
||||
set enum(indent:rhythm.list-indent,body-indent:rhythm.list-body-indent,spacing:rhythm.list-spacing)
|
||||
@@ -339,7 +350,7 @@
|
||||
)
|
||||
set heading(numbering: "1.1.1.1.1", outlined: true)
|
||||
show heading: heading-layout
|
||||
show raw: set text(font: mono, size: 9pt)
|
||||
show raw: set text(font: mono, size: 9pt, weight:"regular")
|
||||
show raw.where(block:false): inline-code
|
||||
show link: set text(fill:link-color)
|
||||
show link: it => underline(stroke:0.4pt + link-color,offset:2pt,it)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"source_revision": "ca4b06d30456599a2d3fd676d832f8d4dd2f78af",
|
||||
"source_revision": "c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b",
|
||||
"sources": [
|
||||
"Makefile",
|
||||
"app/README.md",
|
||||
@@ -77,7 +77,18 @@
|
||||
"scripts/npu_descriptors.py",
|
||||
"scripts/package_hp_boot.py",
|
||||
"scripts/parse_performance_log.py",
|
||||
"tests/test_lp_irq.py"
|
||||
"tests/test_lp_irq.py",
|
||||
"rtl/mini/top/retrosoc.sv",
|
||||
"rtl/mini/top/apb4_periph.sv",
|
||||
"docs/development-environment.md",
|
||||
"scripts/development_environment.py",
|
||||
"dependencies/dependencies.lock.json",
|
||||
"docker/Dockerfile",
|
||||
"flake.nix",
|
||||
".github/workflows/development-environment.yml",
|
||||
".github/workflows/quality.yml",
|
||||
"CONTRIBUTING.md",
|
||||
"docs/git-workflow.md"
|
||||
],
|
||||
"support": [
|
||||
{
|
||||
@@ -633,7 +644,7 @@
|
||||
"id": "resource",
|
||||
"title": "Resource Controller",
|
||||
"implementation": "Partial",
|
||||
"scope": "Ten independently managed shared resources; resource 8 owns the active P5 GA2D direct 2D engine and IRQ route.",
|
||||
"scope": "Ten independently managed shared resources; resource 8 owns GA2D and resource 9 owns NPU execution, including lifecycle and LP/HP IRQ routing.",
|
||||
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
|
||||
"hal": "Published API and syntax example; see the IP chapter.",
|
||||
"linux": "Native driver support not established in this publication.",
|
||||
@@ -653,7 +664,7 @@
|
||||
"id": "monitor",
|
||||
"title": "Fabric Monitor",
|
||||
"implementation": "Integrated",
|
||||
"scope": "Ten master and six target observation banks; bank 8 observes active P5 GA2D direct 2D traffic.",
|
||||
"scope": "Ten master and six target observation banks; master bank 8 observes GA2D traffic and master bank 9 observes NPU descriptor and data DMA traffic.",
|
||||
"dependencies": "No additional off-chip component implied; use the selected clock/reset and access policy.",
|
||||
"hal": "Published API and syntax example; see the IP chapter.",
|
||||
"linux": "Native driver support not established in this publication.",
|
||||
@@ -981,14 +992,16 @@
|
||||
},
|
||||
{
|
||||
"id": "hp-ready-wait",
|
||||
"title": "HP loader has no firmware-local ready timeout",
|
||||
"impact": "LP can wait indefinitely for the expected Linux mailbox event.",
|
||||
"trigger": "No mailbox message after HP release.",
|
||||
"workaround": "Use the simulator deadline during acceptance. A board supervisor/watchdog policy is integration work; no automatic retry is implemented here.",
|
||||
"title": "Linux ready service does not complete loader acceptance",
|
||||
"impact": "The supplied rootfs publishes the initial ready checkpoint but does not provide the later GA2D result and cache-clean service required by the current hp_boot acceptance sequence.",
|
||||
"trigger": "Using the ready-only Linux service where the loader expects the full acceptance mailbox protocol.",
|
||||
"workaround": "Pair the loader with a matching acceptance payload or service. Current polling is bounded by iteration budgets and missing handshakes fail their stage; an initial ready message is not a terminal pass.",
|
||||
"applies_to": "Reviewed v0.5 PRODUCT snapshot; MPW differences are stated separately.",
|
||||
"sources": [
|
||||
"app/apps/hp_boot/main.c",
|
||||
"configs/ci/ihp130-hp.mk"
|
||||
"configs/ci/ihp130-hp.mk",
|
||||
"app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp",
|
||||
"crt/src/hal/hp_mailbox.c"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -2639,7 +2652,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"64-byte TX and RX FIFOs; fractional baud-rate generator.\""
|
||||
"text": "\"**64-byte TX and RX FIFOs**; fractional baud-rate generator.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2663,7 +2676,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Two controller instances with 7-bit and 10-bit addressing.\""
|
||||
"text": "\"Two controller instances with **7-bit and 10-bit addressing**.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2688,7 +2701,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Stereo master TX/RX with independent audio clock.\""
|
||||
"text": "\"**Stereo master TX/RX** with independent audio clock.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2712,7 +2725,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Bidirectional open-drain host interface.\""
|
||||
"text": "\"Bidirectional **open-drain** host interface.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2736,7 +2749,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"24-bit GRB transmission on one GPIO alternate function.\""
|
||||
"text": "\"**24-bit GRB** transmission on one GPIO alternate function.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2761,7 +2774,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"SD card SPI-mode command/data host.\""
|
||||
"text": "\"SD card **SPI-mode** command/data host.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2787,7 +2800,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Native one-bit/four-bit SDR operation.\""
|
||||
"text": "\"Native **one-bit/four-bit SDR** operation.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2812,7 +2825,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Dual-role digital controller with external 8-bit ULPI PHY.\""
|
||||
"text": "\"Dual-role digital controller with **external 8-bit ULPI PHY**.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2837,7 +2850,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Four chip-select slots and 16 programmable LUT sequences.\""
|
||||
"text": "\"Four chip-select slots and **16 programmable LUT sequences**.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2862,7 +2875,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Four ESP-PSRAM64H devices addressable through a 32 MiB window.\""
|
||||
"text": "\"Four ESP-PSRAM64H devices addressable through a **32 MiB window**.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2887,7 +2900,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"One octal DDR memory interface and one selected protocol profile.\""
|
||||
"text": "\"One octal DDR memory interface and **one selected protocol profile**.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2912,7 +2925,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Fixed 64 MiB, x16 SDR geometry with bank/row tracking.\""
|
||||
"text": "\"Fixed **64 MiB, x16 SDR** geometry with bank/row tracking.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2936,7 +2949,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"8-bit parallel RGB565/YUV422 capture.\""
|
||||
"text": "\"**8-bit parallel RGB565/YUV422** capture.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2961,7 +2974,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"8-bit Baseline Sequential JPEG encode or decode.\""
|
||||
"text": "\"8-bit **Baseline Sequential JPEG** encode or decode.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2985,7 +2998,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Coreless microcode sequencer with private DMA and local storage.\""
|
||||
"text": "\"**Coreless microcode sequencer** with private DMA and local storage.\""
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -3309,7 +3322,7 @@
|
||||
{
|
||||
"file": "publications/datasheets/features.json",
|
||||
"kind": "snippet",
|
||||
"text": "\"Coreless microcode sequencer with private DMA and local storage.\""
|
||||
"text": "\"**Coreless microcode sequencer** with private DMA and local storage.\""
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -5138,7 +5151,7 @@
|
||||
],
|
||||
"expected_entries": 4,
|
||||
"meanings": {
|
||||
"0": "Linux-ready and P5 GA2D/NPU mailbox/cache-clean handoff completed; successful terminal status.",
|
||||
"0": "Ready checkpoint, GA2D acceptance result, cache-clean and ownership return completed; successful terminal status. NPU ownership checks apply only with RS_NPU_P5_ACCEPTANCE or RS_NPU_P6_ACCEPTANCE.",
|
||||
"1": "UART initialization failed; terminal failure is written directly without requiring a printable console.",
|
||||
"2": "HP hold/reset/debug-selection/presence prerequisite failed.",
|
||||
"3": "SDRAM did not reach the required ready/error-free state within the firmware wait.",
|
||||
@@ -5198,7 +5211,12 @@
|
||||
"rtl/mini/integration/soc_topology.json",
|
||||
"rtl/mini/mk/software.mk",
|
||||
"scripts/build_hp_linux.py",
|
||||
"scripts/regress.py"
|
||||
"scripts/regress.py",
|
||||
"crt/src/hal/hp_mailbox.c",
|
||||
"crt/include/retrosoc/core/status.h",
|
||||
"rtl/ip/peripheral/hp_mailbox_define.svh",
|
||||
"rtl/mini/address_map/memory_map.json",
|
||||
"rtl/ip/peripheral/apb4_hp_mailbox.sv"
|
||||
],
|
||||
"bindings": [
|
||||
{
|
||||
@@ -7330,65 +7348,111 @@
|
||||
"soc_architecture_catalog": "publications/datasheets/soc-architecture.json"
|
||||
},
|
||||
"ci_snapshot": {
|
||||
"revision": "ca4b06d30456599a2d3fd676d832f8d4dd2f78af",
|
||||
"checked_date": "2026-09-22",
|
||||
"boundary": "Observed public GitHub workflow status for this exact commit. Pending runs have no conclusion. Workflow success is not per-IP corpus, physical, FPGA or silicon qualification.",
|
||||
"revision": "c3de7c602a7ca0f0f9ade9d3ffb59339bc34fb8b",
|
||||
"checked_date": "2026-09-23",
|
||||
"checked_at": "2026-09-23T08:26:42Z",
|
||||
"boundary": "Observed public GitHub workflow status for this exact commit. Unfinished runs have no conclusion. Installation, environment checking and runtime regression are separate evidence; workflow outcomes do not qualify unexecuted physical or silicon stages.",
|
||||
"runs": [
|
||||
{
|
||||
"name": "quality",
|
||||
"run_id": 35833990836,
|
||||
"status": "in_progress",
|
||||
"conclusion": null,
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990836",
|
||||
"scope": "Repository quality checks and script/RTL fixture tests",
|
||||
"note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred."
|
||||
},
|
||||
{
|
||||
"name": "regression-smoke",
|
||||
"run_id": 35686910251,
|
||||
"run_id": 35833991124,
|
||||
"status": "completed",
|
||||
"conclusion": "success",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35686910251",
|
||||
"scope": "Bounded smoke regression",
|
||||
"note": "Selected workflow jobs completed successfully. This workflow-level result does not establish a full per-IP corpus pass or physical, FPGA or silicon qualification."
|
||||
},
|
||||
{
|
||||
"name": "regression-ics55",
|
||||
"run_id": 35686910426,
|
||||
"status": "completed",
|
||||
"conclusion": "failure",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35686910426",
|
||||
"scope": "ICS55 behavioral regression workflow",
|
||||
"note": "Failed job: verified-open-source-flows / regression. Workflow outcome only; no current per-IP pass or physical closure is inferred."
|
||||
},
|
||||
{
|
||||
"name": "regression-sky130",
|
||||
"run_id": 35686910216,
|
||||
"status": "completed",
|
||||
"conclusion": "success",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35686910216",
|
||||
"scope": "SKY130 behavioral regression workflow",
|
||||
"note": "Selected workflow jobs completed successfully. This workflow-level result does not establish a full per-IP corpus pass or physical, FPGA or silicon qualification."
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991124",
|
||||
"scope": "Bounded IHP130 smoke regression",
|
||||
"note": "Selected workflow stages completed successfully. No per-IP corpus or physical qualification is inferred."
|
||||
},
|
||||
{
|
||||
"name": "regression-ihp130",
|
||||
"run_id": 35686910339,
|
||||
"status": "completed",
|
||||
"conclusion": "success",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35686910339",
|
||||
"scope": "IHP130 behavioral regression workflow",
|
||||
"note": "Selected workflow jobs completed successfully. This workflow-level result does not establish a full per-IP corpus pass or physical, FPGA or silicon qualification."
|
||||
"run_id": 35833991071,
|
||||
"status": "in_progress",
|
||||
"conclusion": null,
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991071",
|
||||
"scope": "IHP130 hosted behavioral regression",
|
||||
"note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred."
|
||||
},
|
||||
{
|
||||
"name": "quality",
|
||||
"run_id": 35686910055,
|
||||
"status": "completed",
|
||||
"conclusion": "failure",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35686910055",
|
||||
"scope": "Repository quality workflow",
|
||||
"note": "The scripts job failed in Test scripts and RTL fixtures; source formatting passed. Subsequent YAML, Actions and regression-definition checks were skipped. This record does not diagnose the failed fixture."
|
||||
"name": "regression-sky130",
|
||||
"run_id": 35833991199,
|
||||
"status": "in_progress",
|
||||
"conclusion": null,
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991199",
|
||||
"scope": "SKY130 hosted behavioral regression",
|
||||
"note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred."
|
||||
},
|
||||
{
|
||||
"name": "regression-gf180",
|
||||
"run_id": 35686910233,
|
||||
"status": "completed",
|
||||
"conclusion": "success",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35686910233",
|
||||
"scope": "GF180 behavioral regression workflow",
|
||||
"note": "Selected workflow jobs completed successfully. This workflow-level result does not establish a full per-IP corpus pass or physical, FPGA or silicon qualification."
|
||||
"run_id": 35833991194,
|
||||
"status": "in_progress",
|
||||
"conclusion": null,
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991194",
|
||||
"scope": "GF180 hosted behavioral regression",
|
||||
"note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred."
|
||||
},
|
||||
{
|
||||
"name": "regression-ics55",
|
||||
"run_id": 35833991306,
|
||||
"status": "in_progress",
|
||||
"conclusion": null,
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833991306",
|
||||
"scope": "ICS55 hosted behavioral regression",
|
||||
"note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred."
|
||||
},
|
||||
{
|
||||
"name": "development-environment",
|
||||
"run_id": 35833990893,
|
||||
"status": "in_progress",
|
||||
"conclusion": null,
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893",
|
||||
"scope": "Docker/Nix installation, environment checks and hosted IHP130 behavioral regression",
|
||||
"note": "No terminal conclusion has been observed. No per-IP corpus or physical qualification is inferred.",
|
||||
"observations": [
|
||||
{
|
||||
"name": "docker: Build Docker development environment",
|
||||
"scope": "installation",
|
||||
"status": "completed",
|
||||
"conclusion": "success",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965761"
|
||||
},
|
||||
{
|
||||
"name": "docker: Run IHP130 regression in development environment",
|
||||
"scope": "runtime-regression",
|
||||
"status": "in_progress",
|
||||
"conclusion": null,
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965761"
|
||||
},
|
||||
{
|
||||
"name": "nix: Install Nix",
|
||||
"scope": "installation",
|
||||
"status": "completed",
|
||||
"conclusion": "success",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965933"
|
||||
},
|
||||
{
|
||||
"name": "nix: Check Nix flake",
|
||||
"scope": "environment-check",
|
||||
"status": "completed",
|
||||
"conclusion": "success",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965933"
|
||||
},
|
||||
{
|
||||
"name": "nix: Run IHP130 regression in development environment",
|
||||
"scope": "runtime-regression",
|
||||
"status": "completed",
|
||||
"conclusion": "success",
|
||||
"url": "https://github.com/retroSoC/retroSoC/actions/runs/35833990893/job/107092965933"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"checked_at": "2026-09-22T06:00:43Z"
|
||||
]
|
||||
}
|
||||
}
|
||||
+150
-31
@@ -1,7 +1,7 @@
|
||||
"""Snapshot-bound publication facts; compilation is distinct from hardware qualification."""
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import date
|
||||
from datetime import date, datetime
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
@@ -9,8 +9,16 @@ import subprocess
|
||||
import sys
|
||||
|
||||
from publications.storage_reference import constants
|
||||
from publications.software_reference import function_body
|
||||
from publications.waveform_reference import uncomment
|
||||
|
||||
APU_CONFIGURATION_SOURCES = (
|
||||
"Makefile", "configs/ci/ihp130.mk", "configs/ci/ihp130-apu.mk",
|
||||
"rtl/mini/top/retrosoc.sv", "rtl/mini/top/apb4_periph.sv",
|
||||
"rtl/ip/multimedia/apb4_apu.sv", "rtl/ip/multimedia/apu_reg.sv",
|
||||
"rtl/ip/multimedia/apu_define.svh", "crt/include/retrosoc/hal/apu_regs.h",
|
||||
)
|
||||
|
||||
APU_SOURCES = (
|
||||
"scripts/apu_mcasm.py", "scripts/apu_isa.py", "scripts/apu_p5_coefficients.py",
|
||||
"scripts/apu_kws.py", "scripts/build_apu_p5_bundle.py",
|
||||
@@ -18,7 +26,8 @@ APU_SOURCES = (
|
||||
"rtl/ip/multimedia/apb4_apu.sv", "rtl/ip/multimedia/apu_local_sram.sv",
|
||||
"rtl/ip/multimedia/apu_kws_sram_client.sv",
|
||||
"rtl/ip/multimedia/apu_reg.sv", "crt/include/retrosoc/hal/apu_regs.h",
|
||||
"configs/ci/ihp130-apu.mk", "Makefile", "scripts/apu_abi_digest.py",
|
||||
"scripts/apu_abi_digest.py", "app/apps/apu_release/main.c",
|
||||
*APU_CONFIGURATION_SOURCES,
|
||||
)
|
||||
|
||||
NPU_SOURCES = (
|
||||
@@ -31,28 +40,150 @@ NPU_SOURCES = (
|
||||
)
|
||||
|
||||
|
||||
def validate_ci_state(record: dict, subject: str) -> None:
|
||||
status, conclusion = record.get("status"), record.get("conclusion")
|
||||
if status not in {"queued", "in_progress", "completed", "waiting", "requested", "pending"}:
|
||||
raise ValueError(f"invalid {subject} status")
|
||||
if status == "completed":
|
||||
if conclusion not in {"success", "failure", "cancelled", "skipped", "timed_out", "neutral", "action_required", "stale", "startup_failure"}:
|
||||
raise ValueError(f"invalid completed {subject} outcome")
|
||||
elif conclusion is not None:
|
||||
raise ValueError(f"unfinished {subject} cannot have a conclusion")
|
||||
|
||||
|
||||
def validate_ci_snapshot(snapshot: dict, revision: str) -> None:
|
||||
if snapshot.get("revision") != revision or not snapshot.get("boundary"):
|
||||
raise ValueError("CI snapshot must identify the reviewed revision and evidence boundary")
|
||||
date.fromisoformat(snapshot["checked_date"])
|
||||
checked_at = snapshot.get("checked_at", "")
|
||||
if not re.fullmatch(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z", checked_at):
|
||||
raise ValueError("CI snapshot requires an exact UTC sampling time")
|
||||
datetime.strptime(checked_at, "%Y-%m-%dT%H:%M:%SZ")
|
||||
if checked_at[:10] != snapshot["checked_date"]:
|
||||
raise ValueError("CI snapshot date differs from its UTC sampling time")
|
||||
ids = set()
|
||||
for run in snapshot["runs"]:
|
||||
identifier = run["run_id"]
|
||||
if type(identifier) is not int or identifier < 1 or identifier in ids:
|
||||
raise ValueError("invalid or duplicate CI run")
|
||||
ids.add(identifier)
|
||||
status, conclusion = run.get("status"), run.get("conclusion")
|
||||
if status not in {"queued", "in_progress", "completed", "waiting", "requested", "pending"}:
|
||||
raise ValueError("invalid CI run status")
|
||||
if status == "completed":
|
||||
if conclusion not in {"success", "failure", "cancelled", "skipped", "timed_out", "neutral", "action_required", "stale", "startup_failure"}:
|
||||
raise ValueError("invalid completed CI outcome")
|
||||
elif conclusion is not None:
|
||||
raise ValueError("unfinished CI run cannot have a conclusion")
|
||||
validate_ci_state(run, "CI run")
|
||||
if run["url"] != f"https://github.com/retroSoC/retroSoC/actions/runs/{identifier}":
|
||||
raise ValueError("CI run URL does not match its recorded identifier")
|
||||
if not all(run.get(key) for key in ("name", "scope", "note")):
|
||||
raise ValueError("CI outcome lacks scope or qualification")
|
||||
for stage in run.get("observations", []):
|
||||
validate_ci_state(stage, "CI stage")
|
||||
if not stage.get("name") or stage.get("scope") not in {
|
||||
"installation", "environment-check", "runtime-regression"
|
||||
}:
|
||||
raise ValueError("CI stage lacks its installation/check/runtime boundary")
|
||||
if not re.fullmatch(re.escape(run["url"]) + r"/job/\d+", stage.get("url", "")):
|
||||
raise ValueError("CI stage URL does not belong to its recorded run")
|
||||
|
||||
|
||||
def apu_configurations(root: Path) -> list[dict]:
|
||||
"""Follow the committed Make selection through deployed instance parameters."""
|
||||
def read(path: str) -> str:
|
||||
return uncomment((root / path).read_text(encoding="utf-8"))
|
||||
|
||||
def parameter(source: str, module: str, instance: str, name: str) -> str:
|
||||
blocks = re.findall(r"\b" + re.escape(module) + r"\s*#\((.*?)\)\s*"
|
||||
+ re.escape(instance) + r"\s*\(", source, re.S)
|
||||
values = re.findall(r"\." + re.escape(name) + r"\s*\(([^()]*)\)", blocks[0]) if len(blocks) == 1 else []
|
||||
if len(values) != 1:
|
||||
raise ValueError(f"APU deployed parameter missing or ambiguous: {instance}.{name}")
|
||||
return re.sub(r"\s+", "", values[0])
|
||||
|
||||
make = (root / "Makefile").read_text(encoding="utf-8")
|
||||
defaults = re.findall(r"^APU_ENABLE_P7\s*\?=\s*(YES|NO)\s*$", make, re.M)
|
||||
if len(defaults) != 1 or not re.search(
|
||||
r"ifeq\s*\(\$\(APU_ENABLE_P7\),\s*YES\)\s*DEF_LIST\s*\+=\s*\+define\+APU_ENABLE_P7\s*endif", make):
|
||||
raise ValueError("APU P7 Make selection changed")
|
||||
soc = read("rtl/mini/top/retrosoc.sv")
|
||||
if not re.search(r"`ifdef\s+APU_ENABLE_P7\s+localparam\s+bit\s+ApuEnableP7\s*=\s*1'b1\s*;\s*"
|
||||
r"`else\s+localparam\s+bit\s+ApuEnableP7\s*=\s*1'b0\s*;\s*`endif", soc):
|
||||
raise ValueError("APU P7 top-level selection changed")
|
||||
peripheral = read("rtl/mini/top/apb4_periph.sv")
|
||||
top = read("rtl/ip/multimedia/apb4_apu.sv")
|
||||
if (parameter(soc, "apb4_periph", "u_apb4_periph", "EnableP7") != "ApuEnableP7"
|
||||
or parameter(peripheral, "apb4_apu", "u_apb4_apu", "EnableP7") != "EnableP7"
|
||||
or parameter(top, "apu_reg", "u_apu_reg", "EnableP7") != "EnableP7"):
|
||||
raise ValueError("APU P7 deployed propagation changed")
|
||||
for module, instance in (("apu_reg", "u_apu_reg"), ("apu_microcode_loader", "u_microcode_loader"),
|
||||
("apu_codec_sequencer", "u_codec_sequencer")):
|
||||
if parameter(top, module, instance, "EnableP5") != "1'b1":
|
||||
raise ValueError("APU deployed WAV/FLAC EnableP5 path changed")
|
||||
|
||||
regs = read("rtl/ip/multimedia/apu_reg.sv")
|
||||
p5 = re.findall(r"P5Capability0\s*=\s*EnableP5\s*\?\s*32'h([\da-fA-F_]+)", regs)
|
||||
p7 = re.findall(r"\bCapability0\s*=\s*EnableP7\s*\?\s*32'h([\da-fA-F_]+)\s*:\s*P5Capability0", regs)
|
||||
digest = re.findall(r"AbiDigest\s*=\s*EnableP7\s*\?\s*32'h([\da-fA-F_]+)\s*:\s*32'd0", regs)
|
||||
if len(p5) != 1 or len(p7) != 1 or len(digest) != 1:
|
||||
raise ValueError("APU configured capability/digest selection changed")
|
||||
bits = constants(root, "rtl/ip/multimedia/apu_define.svh")
|
||||
rows = []
|
||||
for name, profile in (("Default PRODUCT", "configs/ci/ihp130.mk"),
|
||||
("P7 acceptance", "configs/ci/ihp130-apu.mk")):
|
||||
source = (root / profile).read_text(encoding="utf-8")
|
||||
assignments = re.findall(r"^APU_ENABLE_P7\s*[:?+]?=\s*([^\n#]+)", source, re.M)
|
||||
if len(assignments) > 1 or (assignments and assignments[0].strip() not in {"YES", "NO"}):
|
||||
raise ValueError("APU publication requires a literal committed P7 selection")
|
||||
enabled = (assignments[0].strip() if assignments else defaults[0]) == "YES"
|
||||
capability = int((p7 if enabled else p5)[0].replace("_", ""), 16)
|
||||
rows.append({"name": name, "profile": profile, "enabled": enabled,
|
||||
"capability": capability, "digest": int(digest[0].replace("_", ""), 16) if enabled else 0,
|
||||
"formats": {codec: bool(capability & (1 << bits["APB4_APU__CAPABILITY0_" + codec]))
|
||||
for codec in ("WAV", "FLAC", "MP3", "KWS")}})
|
||||
if rows[-1]["formats"] != {"WAV": True, "FLAC": True, "MP3": False, "KWS": enabled}:
|
||||
raise ValueError("APU deployed format capability meanings changed")
|
||||
if name == "P7 acceptance" and (re.findall(r"^APP\s*:=\s*(\w+)\s*$", source, re.M) != ["apu_release"]
|
||||
or re.findall(r"^HAVE_CSR\s*:=\s*(\w+)\s*$", source, re.M) != ["YES"]):
|
||||
raise ValueError("APU P7 acceptance application or IRQ configuration changed")
|
||||
if [(r["enabled"], r["capability"], r["digest"]) for r in rows] != [
|
||||
(False, 0x1BD, 0), (True, 0x1FD, 0xF5005D7C)]:
|
||||
raise ValueError("review APU configuration identities")
|
||||
values = constants(root, "crt/include/retrosoc/hal/apu_regs.h")
|
||||
if (values.get("RS_APU_DIGEST_P7_IMPLEMENTED"), values.get("RS_APU_CAPABILITY0_P5_IMPLEMENTED"),
|
||||
values.get("RS_APU_CAPABILITY0_P7_IMPLEMENTED")) != (rows[1]["digest"], rows[0]["capability"], rows[1]["capability"]):
|
||||
raise ValueError("APU published digest differs from the HAL")
|
||||
return rows
|
||||
|
||||
|
||||
def apu_acceptance_steps(root: Path) -> list[dict]:
|
||||
"""Bind the rendered LP procedure to ordered, failure-checked application calls."""
|
||||
source = "app/apps/apu_release/main.c"
|
||||
text = (root / source).read_text(encoding="utf-8")
|
||||
body = function_body(text, "rs_apu_release_run")
|
||||
stages = (
|
||||
("probe", "rs_apu_probe", 5, "After holding HP in reset, waiting for SDRAM and loading the HP bundle, LP checks the P7 capability and ABI digest."),
|
||||
("quiesce", "rs_apu_release_quiesce", 6, "LP quiesces the APU resource and waits for LP ownership, asserted quiesce, reset released and engine idle."),
|
||||
("stage", "rs_apu_release_stage_assets", 7, "With the resource quiesced, LP stages the APUMC image, APUM model, WAV input and KWS PCM window in SDRAM."),
|
||||
("acl", "rs_apu_set_acl", 8, "LP configures the permitted read and write address ranges before requesting either image load."),
|
||||
("load", "rs_apu_release_load_images", 9, "LP loads the microcode, checks its valid/lock state and CRC, then loads the model and checks its status and CRC."),
|
||||
("handoff", "rs_apu_release_handoff", 10, "LP hands ownership to HP after successful image loading, then publishes the shared page and mailbox request before releasing HP."),
|
||||
)
|
||||
calls = list(re.finditer(r"\b(" + "|".join(row[1] for row in stages) + r")\s*\(", body))
|
||||
if [match[1] for match in calls] != [row[1] for row in stages]:
|
||||
raise ValueError("APU acceptance call order changed")
|
||||
for index, (match, stage) in enumerate(zip(calls, stages, strict=True)):
|
||||
stop = calls[index + 1].start() if index + 1 < len(calls) else body.index("rs_apu_release_fill_page", match.end())
|
||||
failures = re.findall(r"rs_apu_release_fail\(\s*UINT8_C\((\d+)\)\s*\)", body[match.end():stop])
|
||||
if failures != [str(stage[2])]:
|
||||
raise ValueError("APU acceptance failure checkpoint changed")
|
||||
loads = function_body(text, "rs_apu_release_load_images")
|
||||
if re.findall(r"\b(rs_apu_(?:microcode|kws_model)_load)\s*\(", loads) != [
|
||||
"rs_apu_microcode_load", "rs_apu_kws_model_load"]:
|
||||
raise ValueError("APU acceptance image-load order changed")
|
||||
tail = body[calls[-1].end():]
|
||||
if re.findall(r"\b(rs_apu_release_fill_page|rs_hp_mailbox_clear_lp_interrupt|rs_hp_mailbox_send_to_hp|"
|
||||
r"rs_sysctrl_set_hp_release)\s*\(", tail) != [
|
||||
"rs_apu_release_fill_page", "rs_hp_mailbox_clear_lp_interrupt", "rs_hp_mailbox_send_to_hp",
|
||||
"rs_sysctrl_set_hp_release"] or not re.search(r"rs_sysctrl_set_hp_release\(\s*true\s*\)", tail):
|
||||
raise ValueError("APU acceptance HP publication/release order changed")
|
||||
return [{"id": identifier, "call": call, "failure_code": failure, "description": description,
|
||||
"source": source, "function": "rs_apu_release_run"}
|
||||
for identifier, call, failure, description in stages]
|
||||
|
||||
|
||||
def apu_implementation(root: Path) -> dict:
|
||||
@@ -86,26 +217,8 @@ print(json.dumps({'abi':assembly.mc_abi,'instruction_words':len(assembly.instruc
|
||||
if len(enabled) != 1:
|
||||
raise ValueError("APU P7 default parameter is missing or ambiguous")
|
||||
result["p7_default_enabled"] = enabled[0] == "1"
|
||||
regs = uncomment((root / "rtl/ip/multimedia/apu_reg.sv").read_text(encoding="utf-8"))
|
||||
values = constants(root, "crt/include/retrosoc/hal/apu_regs.h")
|
||||
p5 = re.findall(r"P5Capability0\s*=\s*EnableP5\s*\?\s*32'h([\da-fA-F_]+)", regs)
|
||||
p7 = re.findall(r"\bCapability0\s*=\s*EnableP7\s*\?\s*32'h([\da-fA-F_]+)\s*:\s*P5Capability0", regs)
|
||||
digest = re.findall(r"AbiDigest\s*=\s*EnableP7\s*\?\s*32'h([\da-fA-F_]+)\s*:\s*32'd0", regs)
|
||||
if len(p5) != 1 or len(p7) != 1 or len(digest) != 1:
|
||||
raise ValueError("APU configured capability/digest selection changed")
|
||||
result["profiles"] = [
|
||||
{"name": "Default PRODUCT", "profile": "configs/ci/ihp130.mk", "enabled": False,
|
||||
"capability": int(p5[0].replace("_", ""), 16), "digest": 0},
|
||||
{"name": "P7 acceptance", "profile": "configs/ci/ihp130-apu.mk", "enabled": True,
|
||||
"capability": int(p7[0].replace("_", ""), 16), "digest": int(digest[0].replace("_", ""), 16)},
|
||||
]
|
||||
if [(r["capability"], r["digest"]) for r in result["profiles"]] != [(0x1BD, 0), (0x1FD, 0xF5005D7C)]:
|
||||
raise ValueError("review APU configuration identities")
|
||||
if (values.get("RS_APU_DIGEST_P7_IMPLEMENTED"), values.get("RS_APU_CAPABILITY0_P5_IMPLEMENTED"),
|
||||
values.get("RS_APU_CAPABILITY0_P7_IMPLEMENTED")) != (0xF5005D7C, 0x1BD, 0x1FD):
|
||||
raise ValueError("APU published digest differs from the HAL")
|
||||
if not re.search(r"APU_ENABLE_P7\s*:=\s*YES", (root / "configs/ci/ihp130-apu.mk").read_text()):
|
||||
raise ValueError("APU acceptance profile no longer enables P7")
|
||||
result["profiles"] = apu_configurations(root)
|
||||
result["acceptance_steps"] = apu_acceptance_steps(root)
|
||||
result["qualification"] = "Static assembly and source inspection only; no codec corpus, KWS accuracy or physical qualification."
|
||||
return result
|
||||
|
||||
@@ -152,7 +265,13 @@ def validate_accelerator_claims(reference: dict, catalog: list, features: dict,
|
||||
r"implemented and verified|passed differential evidence")
|
||||
if any(re.search(stale, text, re.I) for text in texts):
|
||||
raise ValueError("NPU live publication claims contradict enabled execution")
|
||||
for text in features["apu"] + content["apu"]["notes"]:
|
||||
apu = reference["apu_implementation"]
|
||||
texts = [row["summary"] for row in catalog if row["id"] == "apu"]
|
||||
texts += features["apu"] + content["apu"]["notes"]
|
||||
for text in texts:
|
||||
if (all(row["formats"]["WAV"] and row["formats"]["FLAC"] for row in apu["profiles"])
|
||||
and re.search(r"(?:codec jobs|WAV[/ ]FLAC).*remain(?:s)? disabled", text, re.I)):
|
||||
raise ValueError("APU publication contradicts deployed WAV/FLAC capability")
|
||||
if (re.search(r"MP3(?: and |/)KWS.*not advertised", text, re.I)
|
||||
and not re.search(r"default|P7|configuration", text, re.I)):
|
||||
raise ValueError("APU publication loses the configured KWS distinction")
|
||||
@@ -0,0 +1,37 @@
|
||||
"""Publication facts for the repository's supported development environment."""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
|
||||
ENVIRONMENT_SOURCES = (
|
||||
"dependencies/dependencies.lock.json", "docker/Dockerfile", "flake.nix",
|
||||
"scripts/development_environment.py", "docs/development-environment.md",
|
||||
".github/workflows/development-environment.yml", "docs/engineering.md",
|
||||
)
|
||||
|
||||
|
||||
def development_environment(root: Path) -> dict:
|
||||
lock = json.loads((root / ENVIRONMENT_SOURCES[0]).read_text(encoding="utf-8"))
|
||||
docker = (root / "docker/Dockerfile").read_text(encoding="utf-8")
|
||||
nix = (root / "flake.nix").read_text(encoding="utf-8")
|
||||
workflow = (root / ".github/workflows/development-environment.yml").read_text(encoding="utf-8")
|
||||
python = re.findall(r"\bpython(\d)(\d+)Full\b", nix)
|
||||
java_nix = re.findall(r"\bjdk(\d+)_headless\b", nix)
|
||||
java_docker = re.findall(r"\bopenjdk-(\d+)-jre-headless\b", docker)
|
||||
system = re.findall(r'\bsystem\s*=\s*"([^"]+)";', nix)
|
||||
ubuntu = re.findall(r'base\.name="ubuntu:([\d.]+)"', docker)
|
||||
if (len(python) != 1 or len(java_nix) != 1 or java_nix != java_docker
|
||||
or system != ["x86_64-linux"] or ubuntu != ["22.04"]):
|
||||
raise ValueError("review the published development environment runtime/platform contract")
|
||||
if any("scripts/development_environment.py" not in text for text in (docker, nix)):
|
||||
raise ValueError("development entrypoints no longer share the documented bootstrap")
|
||||
if "--behavioral-only" not in workflow:
|
||||
raise ValueError("review the environment workflow's published runtime evidence boundary")
|
||||
return {
|
||||
"platform": "Linux x86_64", "ubuntu": ubuntu[0],
|
||||
"python": ".".join(python[0]), "java": java_nix[0],
|
||||
"sbt": lock["toolchains"]["ubuntu-22.04"]["sbt"]["version"],
|
||||
"sources": list(ENVIRONMENT_SOURCES),
|
||||
}
|
||||
@@ -19,6 +19,23 @@ def digest(path: Path) -> str:
|
||||
return hashlib.sha256(path.read_bytes()).hexdigest()
|
||||
|
||||
|
||||
def validate_change_scope(markers: list[dict], document: dict) -> None:
|
||||
"""Apply this edition's change namespace without reclassifying earlier work."""
|
||||
prefix = document.get("change_prefix")
|
||||
if prefix is None:
|
||||
return # Historical manifests predate explicit change namespaces.
|
||||
if not isinstance(prefix, str) or not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*-", prefix):
|
||||
raise ValueError("invalid publication change prefix")
|
||||
navigation = {"contents", "table-directory", "figure-directory"}
|
||||
for marker in markers:
|
||||
identifier = marker["id"]
|
||||
if identifier in navigation:
|
||||
if marker["kind"] == "publication-change-start" and marker.get("category") != "navigation":
|
||||
raise ValueError("shared navigation marker cannot claim substantive content")
|
||||
elif not identifier.startswith(prefix):
|
||||
raise ValueError(f"change marker belongs to an earlier publication round: {identifier}")
|
||||
|
||||
|
||||
def page_ranges(markers: list[dict], page_count: int) -> list[dict]:
|
||||
starts, ends, rows = {}, {}, []
|
||||
for marker in markers:
|
||||
@@ -68,6 +85,16 @@ def repository_footer_pages(reader) -> list[int]:
|
||||
return pages
|
||||
|
||||
|
||||
def printed_page_number(text: str, page_count: int) -> int:
|
||||
"""Read the canonical footer, excluding nearby body ratios such as CAS 2/3."""
|
||||
_, separator, footer = text.rpartition(REPOSITORY_URL)
|
||||
found = re.findall(r"\b(\d+)\s*/\s*(\d+)\b", footer)
|
||||
if (not separator or len(found) != 1 or int(found[0][1]) != page_count
|
||||
or not 1 <= int(found[0][0]) <= page_count):
|
||||
raise ValueError("missing or ambiguous printed footer")
|
||||
return int(found[0][0])
|
||||
|
||||
|
||||
def report_changes(pdf: Path, baseline: Path) -> dict:
|
||||
reader, final_hash = verified_pdf(pdf)
|
||||
old, baseline_hash = verified_pdf(baseline)
|
||||
@@ -79,6 +106,7 @@ def report_changes(pdf: Path, baseline: Path) -> dict:
|
||||
if manifest["change_markers_sha256"] != digest(marker_file):
|
||||
raise ValueError("change markers do not match the delivered manifest")
|
||||
markers = json.loads(marker_file.read_text(encoding="utf-8"))
|
||||
validate_change_scope(markers, manifest.get("document", {}))
|
||||
ranges = page_ranges(markers, len(reader.pages))
|
||||
if not ranges:
|
||||
raise ValueError("no tracked changes in this publication")
|
||||
@@ -92,10 +120,10 @@ def report_changes(pdf: Path, baseline: Path) -> dict:
|
||||
labels[page] = None
|
||||
continue
|
||||
text = reader.pages[page - 1].extract_text() or ""
|
||||
found = re.findall(r"\b(\d+)\s*/\s*(\d+)\b", text[-200:])
|
||||
if len(found) != 1 or int(found[0][1]) != len(reader.pages):
|
||||
raise ValueError(f"missing or ambiguous printed footer on page {page}")
|
||||
labels[page] = int(found[0][0])
|
||||
try:
|
||||
labels[page] = printed_page_number(text, len(reader.pages))
|
||||
except ValueError as error:
|
||||
raise ValueError(f"missing or ambiguous printed footer on page {page}") from error
|
||||
row["printed_start"] = labels[row["start_page"]]
|
||||
row["printed_end"] = labels[row["end_page"]]
|
||||
row["numbering"] = ("unprinted" if all(page in unnumbered for page in range(row["start_page"], row["end_page"] + 1))
|
||||
|
||||
@@ -8,10 +8,13 @@ from pathlib import Path
|
||||
|
||||
from publications.implementation_reference import without_comments
|
||||
from publications.api_bundle_reference import bundle_layout, validate_api, dependencies as api_bundle_dependencies
|
||||
from publications.boot_acceptance_reference import SOURCES as BOOT_SOURCES, collect_boot_acceptance, ready_mailbox
|
||||
|
||||
|
||||
def dependencies(spec: dict) -> set[str]:
|
||||
paths = set(spec.get("sources", []))
|
||||
if spec:
|
||||
paths.update(BOOT_SOURCES)
|
||||
paths.update(api_bundle_dependencies(spec))
|
||||
paths.update(spec.get("runtime_profiles", []))
|
||||
for row in spec.get("bindings", []):
|
||||
@@ -174,18 +177,11 @@ def linux_platform(root: Path) -> dict:
|
||||
raise ValueError("CPU and UART device-tree clock declarations disagree")
|
||||
if dt_value("linux,initrd-start") != dt_value("linux,initrd-end"):
|
||||
raise ValueError("reviewed initrd template placeholder changed")
|
||||
ready = (root / "app/ports/linux/rootfs-overlay/etc/init.d/S99retrosoc-hp").read_text(encoding="utf-8")
|
||||
writes = [(int(a, 0), int(v, 0)) for a, v in re.findall(r"^\s*devmem\s+(0x[\da-fA-F]+)\s+32\s+(0x[\da-fA-F]+)", ready, re.M)]
|
||||
expected = [(0x10019020, 1), (0x10019024, 0x4C4E5801), (0x10019028, 1), (0x1001902C, 1)]
|
||||
if writes != expected:
|
||||
raise ValueError("Linux ready mailbox sequence changed")
|
||||
if ready.find('echo "retroSoC HP Linux ready"') < 0 or ready.index('echo "retroSoC HP Linux ready"') > ready.index("devmem"):
|
||||
raise ValueError("Linux ready message/publication order changed")
|
||||
return {"hart_id": 1, "timebase_hz": timebase, "clock_hz": int(clocks[0]),
|
||||
"cbom_bytes": dt_value("riscv,cbom-block-size"), "memory_base": memory[0][0],
|
||||
"memory_bytes": int(memory[0][1], 0), "initrd_start": dt_value("linux,initrd-start"),
|
||||
"initrd_template_end": dt_value("linux,initrd-end"), "bootargs": bootargs[0],
|
||||
"ready_writes": [{"address": f"0x{a:08X}", "value": f"0x{v:08X}"} for a, v in writes]}
|
||||
"ready_writes": ready_mailbox(root)}
|
||||
|
||||
|
||||
def collect_software(root: Path, spec: dict) -> dict:
|
||||
@@ -195,6 +191,7 @@ def collect_software(root: Path, spec: dict) -> dict:
|
||||
raise ValueError("software diagnostic application coverage changed")
|
||||
return {**copy.deepcopy(spec), "sources": sorted(dependencies(spec)), "profiles": runtime_profiles(root, spec),
|
||||
"irq": irq_support(root), "platform": linux_platform(root),
|
||||
"boot_acceptance": collect_boot_acceptance(root, function_body),
|
||||
"api_reference": validate_api(root, spec["api_semantics"], function_body),
|
||||
"bundle_reference": bundle_layout(root, spec["boot_bundle"], function_body),
|
||||
"applications": [application_diagnostics(root, app) for app in spec["applications"]]}
|
||||
@@ -10,6 +10,7 @@ from publications.implementation_reference import collect_details, dependencies
|
||||
from publications.retrieval_reference import dependencies as retrieval_dependencies
|
||||
from publications.software_reference import collect_software, dependencies as software_dependencies
|
||||
from publications.diagram_reference import dependencies as diagram_dependencies
|
||||
from publications.environment_reference import ENVIRONMENT_SOURCES, development_environment
|
||||
from publications.dev_reference import (
|
||||
APU_SOURCES, NPU_SOURCES, apu_implementation, npu_implementation,
|
||||
validate_accelerator_claims, validate_ci_snapshot,
|
||||
@@ -97,6 +98,9 @@ def collect_system_reference(root: Path, revision: str) -> dict:
|
||||
reference["programming"] = collect_programming(root, reference["programming"], {row["id"] for row in index}, revision)
|
||||
reference["product_details"] = collect_details(root, reference["product_details"], {row["id"] for row in index}, {row["id"] for row in reference["limitations"]})
|
||||
reference["software"] = collect_software(root, reference["software"])
|
||||
if not set(ENVIRONMENT_SOURCES) <= source_paths(reference):
|
||||
raise ValueError("development environment dependencies missing from publication sources")
|
||||
reference["development_environment"] = development_environment(root)
|
||||
if not set(APU_SOURCES) <= source_paths(reference):
|
||||
raise ValueError("APU implementation dependencies missing from publication sources")
|
||||
reference["apu_implementation"] = apu_implementation(root)
|
||||
|
||||
@@ -0,0 +1,150 @@
|
||||
"""Prevent publication drift in HP acceptance and ready-only Linux integration."""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import shutil
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
from publications import boot_acceptance_reference as br
|
||||
from publications.software_reference import function_body
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def source_tree(tmp_path):
|
||||
for relative in br.SOURCES:
|
||||
target = tmp_path / relative
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copyfile(ROOT / relative, target)
|
||||
return tmp_path
|
||||
|
||||
|
||||
def replace(root: Path, relative: str, old: str, new: str) -> None:
|
||||
path = root / relative
|
||||
text = path.read_text(encoding="utf-8")
|
||||
assert old in text
|
||||
path.write_text(text.replace(old, new), encoding="utf-8")
|
||||
|
||||
|
||||
def test_actual_boot_requires_bounded_complete_acceptance():
|
||||
result = br.collect_boot_acceptance(ROOT, function_body)
|
||||
assert result["event_poll_iterations"] == 64000000
|
||||
assert result["npu_defines"] == ["RS_NPU_P5_ACCEPTANCE", "RS_NPU_P6_ACCEPTANCE"]
|
||||
assert [(row["event"], row["argument"], row["sequence"]) for row in result["messages"]] == [
|
||||
(1, 0x4C4E5801, 1), (2, 0x47413244, 2), (4, 0x43424F4B, 3)]
|
||||
assert result["rootfs_ready_only"]
|
||||
assert result["terminal_requires_cache_handoff"]
|
||||
assert result["failure_reset_requires_no_hp_ga2d_owner"]
|
||||
|
||||
|
||||
def test_mailbox_purposes_follow_registers_in_the_actual_write_order():
|
||||
rows = br.ready_mailbox(ROOT)
|
||||
assert [(row["address"], row["register"], row["purpose"]) for row in rows] == [
|
||||
("0x10019020", "HP_EVENT", "Linux-ready event"),
|
||||
("0x10019024", "HP_ARG0", "Ready-state argument"),
|
||||
("0x10019028", "HP_SEQUENCE", "Publication sequence"),
|
||||
("0x1001902C", "HP_DOORBELL", "LP interrupt request"),
|
||||
]
|
||||
|
||||
|
||||
@pytest.mark.parametrize("relative,old,new,match", [
|
||||
(br.HAL_SOURCE, "RS_HP_MAILBOX_HP_EVENT_OFFSET UINT32_C(0x020)",
|
||||
"RS_HP_MAILBOX_HP_EVENT_OFFSET UINT32_C(0x024)", "HAL/RTL"),
|
||||
(br.HAL_SOURCE, "message->code = *rs_hp_mailbox_register(RS_HP_MAILBOX_HP_EVENT_OFFSET);",
|
||||
"message->code = *rs_hp_mailbox_register(RS_HP_MAILBOX_HP_ARG0_OFFSET);", "field semantics"),
|
||||
(br.MAILBOX_SOURCE, "`APB4_HP_MAILBOX__HP_DOORBELL: s_lp_intr_state_d = 1'b1;",
|
||||
"`APB4_HP_MAILBOX__HP_DOORBELL: s_hp_intr_state_d = 1'b1;", "LP interrupt"),
|
||||
(br.READY_SOURCE, "0x10019024 32 0x4C4E5801", "0x10019024 32 0x4C4E5802", "sequence"),
|
||||
(br.READY_SOURCE, " ;;", " start_ga2d_responder\n ;;", "ready-only"),
|
||||
(br.READY_SOURCE, " ;;", " devmem 0x10019020 32 2\n ;;", "sequence"),
|
||||
])
|
||||
def test_mailbox_or_service_drift_requires_new_review(source_tree, relative, old, new, match):
|
||||
replace(source_tree, relative, old, new)
|
||||
with pytest.raises(ValueError, match=match):
|
||||
br.ready_mailbox(source_tree)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("old,new,match", [
|
||||
("timeout < RS_HP_BOOT_EVENT_TIMEOUT; ++timeout", "; ++timeout", "bounded poll"),
|
||||
("if (message.sequence == sequence)", "if (message.sequence != sequence)", "token/error"),
|
||||
("if (!s_hp_boot_ga2d_owned_by_hp)", "if (s_hp_boot_ga2d_owned_by_hp)", "reset ownership"),
|
||||
("rs_hp_boot_fail(UINT8_C(13));", "rs_hp_boot_fail(UINT8_C(11));", "completion condition"),
|
||||
("cache_clean_completed = true;", "cache_clean_completed = false;", "phase or ordering"),
|
||||
("rs_resource_set_owner(RS_RESOURCE_GA2D, RS_RESOURCE_OWNER_LP, false)",
|
||||
"rs_resource_set_owner(RS_RESOURCE_GA2D, RS_RESOURCE_OWNER_HP, false)", "phase or ordering"),
|
||||
("#if defined(RS_NPU_P5_ACCEPTANCE) || defined(RS_NPU_P6_ACCEPTANCE)",
|
||||
"#if 1", "optional NPU"),
|
||||
])
|
||||
def test_inaccurate_boot_protocol_claims_fail_collection(source_tree, old, new, match):
|
||||
replace(source_tree, br.BOOT_SOURCE, old, new)
|
||||
with pytest.raises(ValueError, match=match):
|
||||
br.collect_boot_acceptance(source_tree, function_body)
|
||||
|
||||
|
||||
def test_ready_marker_cannot_become_terminal_success_unnoticed(source_tree):
|
||||
replace(source_tree, br.BOOT_SOURCE, 'printf("HP_LINUX_READY\\n");',
|
||||
'printf("HP_LINUX_READY\\n");\n rs_test_finish(RS_TEST_PASSED, UINT8_C(0));')
|
||||
with pytest.raises(ValueError, match="terminal pass"):
|
||||
br.collect_boot_acceptance(source_tree, function_body)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("old,new", [
|
||||
("if (rs_hp_boot_wait_hp_held())", "if (!rs_hp_boot_wait_hp_held())"),
|
||||
("rs_resource_acknowledge_cache_clean() == RS_OK", "rs_resource_acknowledge_cache_clean() != RS_OK"),
|
||||
("if (rs_hp_boot_wait_cache_request())", "if (!rs_hp_boot_wait_cache_request())"),
|
||||
("if (rs_hp_boot_wait_message(RS_HP_BOOT_GA2D_CACHE_EVENT,", "if (!rs_hp_boot_wait_message(RS_HP_BOOT_GA2D_CACHE_EVENT,"),
|
||||
])
|
||||
def test_inverted_cache_success_guard_cannot_qualify_handoff(source_tree, old, new):
|
||||
replace(source_tree, br.BOOT_SOURCE, old, new)
|
||||
with pytest.raises(ValueError, match="positive cache-handoff"):
|
||||
br.collect_boot_acceptance(source_tree, function_body)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("function,old,new,match", [
|
||||
("rs_hp_boot_wait_hp_held", "&& hp_status.reset_asserted", "", "held-state"),
|
||||
("rs_hp_boot_wait_hp_held", "!hp_status.released", "hp_status.released", "held-state"),
|
||||
("rs_hp_boot_wait_hp_held", "!hp_status.draining", "hp_status.draining", "held-state"),
|
||||
("rs_hp_boot_wait_hp_held", "!hp_status.forced_fault &&", "", "held-state"),
|
||||
("rs_hp_boot_wait_hp_held", "rs_hp_boot_ga2d_idle(RS_RESOURCE_OWNER_HP)",
|
||||
"rs_hp_boot_ga2d_idle(RS_RESOURCE_OWNER_LP)", "held-state"),
|
||||
("rs_hp_boot_wait_hp_held", "|| defined(RS_NPU_P6_ACCEPTANCE)", "", "held-state NPU"),
|
||||
("rs_hp_boot_wait_hp_held", "&& rs_hp_boot_npu_idle(RS_RESOURCE_OWNER_HP)",
|
||||
"|| rs_hp_boot_npu_idle(RS_RESOURCE_OWNER_HP)", "held-state NPU"),
|
||||
("rs_hp_boot_wait_cache_request", "cache_status.request && !cache_status.clean",
|
||||
"cache_status.request && cache_status.clean", "cache request/clean"),
|
||||
("rs_hp_boot_ga2d_idle", "!ga2d_status.draining &&", "", "ga2d safe-idle"),
|
||||
("rs_hp_boot_npu_idle", "RS_NPU_STATUS_BUSY | RS_NPU_STATUS_DRAINING | RS_NPU_STATUS_RECOVERING",
|
||||
"RS_NPU_STATUS_BUSY | RS_NPU_STATUS_DRAINING", "npu safe-idle"),
|
||||
])
|
||||
def test_weakened_held_observation_cannot_qualify_handoff(source_tree, function, old, new, match):
|
||||
path = source_tree / br.BOOT_SOURCE
|
||||
source = path.read_text(encoding="utf-8")
|
||||
body = function_body(source, function)
|
||||
assert old in body
|
||||
path.write_text(source.replace(body, body.replace(old, new), 1), encoding="utf-8")
|
||||
with pytest.raises(ValueError, match=match):
|
||||
br.collect_boot_acceptance(source_tree, function_body)
|
||||
|
||||
|
||||
def test_poll_budget_is_derived_without_inventing_time_units(source_tree):
|
||||
replace(source_tree, br.STATUS_SOURCE, "((rs_timeout_t)1000000U)", "((rs_timeout_t)2000000U)")
|
||||
result = br.collect_boot_acceptance(source_tree, function_body)
|
||||
assert result["default_poll_iterations"] == 2000000
|
||||
assert result["event_poll_iterations"] == 128000000
|
||||
assert not any("milliseconds" in key or "seconds" in key for key in result)
|
||||
|
||||
|
||||
def test_mailbox_address_is_derived_from_the_memory_map(source_tree):
|
||||
path = source_tree / br.MAP_SOURCE
|
||||
source = json.loads(path.read_text(encoding="utf-8"))
|
||||
mailbox = next(row for row in source["regions"] if row["symbol"] == "APB4_HP_MAILBOX")
|
||||
mailbox["base"] = "0x1001A000"
|
||||
path.write_text(json.dumps(source), encoding="utf-8")
|
||||
replace(source_tree, br.READY_SOURCE, "0x100190", "0x1001A0")
|
||||
rows = br.ready_mailbox(source_tree)
|
||||
assert rows[0]["address"] == "0x1001A020"
|
||||
assert rows[0]["purpose"] == "Linux-ready event"
|
||||
@@ -0,0 +1,49 @@
|
||||
"""A same-version revision must not repeat the previous edition's added claims."""
|
||||
import copy
|
||||
|
||||
import pytest
|
||||
|
||||
from publications.report_changes import REPOSITORY_URL, page_ranges, printed_page_number, validate_change_scope
|
||||
|
||||
|
||||
def markers(identifier, category="modified"):
|
||||
return [dict(kind="publication-change-start", id=identifier, page=2, title="Reviewed content", category=category),
|
||||
dict(kind="publication-change-end", id=identifier, page=3)]
|
||||
|
||||
|
||||
def test_current_content_and_shared_navigation_keep_separate_scopes():
|
||||
values = markers("v05-refresh-hp-boot") + markers("contents", "navigation")
|
||||
before = copy.deepcopy(values)
|
||||
validate_change_scope(values, {"change_prefix": "v05-refresh-"})
|
||||
assert values == before
|
||||
assert {row["category"] for row in page_ranges(values, 3)} == {"modified", "navigation"}
|
||||
|
||||
|
||||
@pytest.mark.parametrize("identifier", ["v05-npu", "ga2d-chapter", "dev-software", "soc-functional"])
|
||||
def test_previous_round_content_cannot_reappear_in_current_change_record(identifier):
|
||||
with pytest.raises(ValueError, match="earlier publication round"):
|
||||
validate_change_scope(markers(identifier, "added"), {"change_prefix": "v05-refresh-"})
|
||||
|
||||
|
||||
def test_shared_navigation_cannot_be_relabelled_as_added_content():
|
||||
with pytest.raises(ValueError, match="navigation marker"):
|
||||
validate_change_scope(markers("contents", "added"), {"change_prefix": "v05-refresh-"})
|
||||
|
||||
|
||||
def test_historical_manifest_without_change_policy_remains_readable():
|
||||
validate_change_scope(markers("v05-npu", "added"), {})
|
||||
|
||||
|
||||
def test_body_ratios_are_not_ambiguous_footer_numbers():
|
||||
text = f"CAS 2/3, BL 2/8, write-burst, sequential only.\n{REPOSITORY_URL} 204 / 779 2026-09-22"
|
||||
assert printed_page_number(text, 779) == 204
|
||||
|
||||
|
||||
@pytest.mark.parametrize("text", [
|
||||
"CAS 2/3, BL 2/8", "204 / 779", REPOSITORY_URL,
|
||||
f"{REPOSITORY_URL} 204 / 778", f"{REPOSITORY_URL} 0 / 779",
|
||||
f"{REPOSITORY_URL} 780 / 779", f"{REPOSITORY_URL} 204 / 779 205 / 779",
|
||||
])
|
||||
def test_footer_scope_still_rejects_missing_wrong_or_duplicate_labels(text):
|
||||
with pytest.raises(ValueError, match="printed footer"):
|
||||
printed_page_number(text, 779)
|
||||
@@ -0,0 +1,45 @@
|
||||
"""Installation success must not hide missing or failing runtime evidence."""
|
||||
import copy
|
||||
|
||||
import pytest
|
||||
|
||||
from publications.dev_reference import validate_ci_snapshot
|
||||
|
||||
REVISION = "b" * 40
|
||||
|
||||
|
||||
def snapshot():
|
||||
url = "https://github.com/retroSoC/retroSoC/actions/runs/123"
|
||||
stages = [dict(name=name, scope=scope, status="completed", conclusion=outcome, url=url + "/job/456")
|
||||
for name, scope, outcome in [("Docker build", "installation", "success"),
|
||||
("Nix flake", "environment-check", "success"),
|
||||
("IHP130 runtime", "runtime-regression", "failure")]]
|
||||
return dict(revision=REVISION, checked_date="2026-09-22", checked_at="2026-09-22T14:49:18Z",
|
||||
boundary="Workflow-level observations only", runs=[dict(name="development-environment", run_id=123,
|
||||
status="completed", conclusion="failure", url=url, scope="Environment and behavioral execution",
|
||||
note="No physical qualification inferred", observations=stages)])
|
||||
|
||||
|
||||
def test_separate_successful_installation_and_failed_runtime_are_preserved():
|
||||
value = snapshot()
|
||||
before = copy.deepcopy(value)
|
||||
validate_ci_snapshot(value, REVISION)
|
||||
assert value == before
|
||||
assert value["runs"][0]["observations"][-1]["conclusion"] == "failure"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("kind,reason", [("pending", "unfinished"), ("scope", "boundary"),
|
||||
("url", "recorded run"), ("utc", "UTC")])
|
||||
def test_ci_stage_cannot_borrow_conclusion_scope_or_identity(kind, reason):
|
||||
value = snapshot()
|
||||
stage = value["runs"][0]["observations"][-1]
|
||||
if kind == "pending":
|
||||
stage["status"] = "in_progress"
|
||||
elif kind == "scope":
|
||||
stage["scope"] = "silicon-qualified"
|
||||
elif kind == "url":
|
||||
stage["url"] = stage["url"].replace("/runs/123", "/runs/124")
|
||||
else:
|
||||
value["checked_at"] = "2026-09-22"
|
||||
with pytest.raises(ValueError, match=reason):
|
||||
validate_ci_snapshot(value, REVISION)
|
||||
@@ -0,0 +1,34 @@
|
||||
"""Environment descriptions follow executable sources, without claiming a run."""
|
||||
from pathlib import Path
|
||||
import shutil
|
||||
|
||||
import pytest
|
||||
|
||||
from publications.environment_reference import ENVIRONMENT_SOURCES, development_environment
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
def test_environment_reports_current_locked_runtime_versions():
|
||||
result = development_environment(ROOT)
|
||||
assert (result["platform"], result["ubuntu"], result["python"], result["java"], result["sbt"]) == (
|
||||
"Linux x86_64", "22.04", "3.10", "17", "1.10.0")
|
||||
assert not {"passed", "qualified", "performance"} & result.keys()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("path,old,new,reason", [
|
||||
("docker/Dockerfile", "openjdk-17-jre-headless", "openjdk-21-jre-headless", "runtime/platform"),
|
||||
("flake.nix", "python310Full", "python3Full", "runtime/platform"),
|
||||
(".github/workflows/development-environment.yml", "--behavioral-only", "--full", "evidence boundary"),
|
||||
])
|
||||
def test_environment_drift_requires_publication_review(tmp_path, path, old, new, reason):
|
||||
for relative in ENVIRONMENT_SOURCES:
|
||||
target = tmp_path / relative
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copyfile(ROOT / relative, target)
|
||||
target = tmp_path / path
|
||||
original = target.read_text(encoding="utf-8")
|
||||
assert old in original
|
||||
target.write_text(original.replace(old, new), encoding="utf-8")
|
||||
with pytest.raises(ValueError, match=reason):
|
||||
development_environment(tmp_path)
|
||||
@@ -0,0 +1,94 @@
|
||||
"""APU summary and rendered procedure follow deployed configuration and source order."""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from pathlib import Path
|
||||
import shutil
|
||||
|
||||
import pytest
|
||||
|
||||
from publications.dev_reference import (
|
||||
APU_CONFIGURATION_SOURCES,
|
||||
apu_acceptance_steps,
|
||||
apu_configurations,
|
||||
validate_accelerator_claims,
|
||||
)
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
ACCEPTANCE = "app/apps/apu_release/main.c"
|
||||
|
||||
|
||||
def copy_sources(destination: Path, sources: tuple[str, ...]) -> Path:
|
||||
for relative in sources:
|
||||
target = destination / relative
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copyfile(ROOT / relative, target)
|
||||
return destination
|
||||
|
||||
|
||||
def replace_source(root: Path, relative: str, before: str, after: str) -> None:
|
||||
path = root / relative
|
||||
text = path.read_text(encoding="utf-8")
|
||||
assert before in text
|
||||
path.write_text(text.replace(before, after, 1), encoding="utf-8")
|
||||
|
||||
|
||||
def test_apu_profiles_follow_deployed_p5_and_committed_p7_selection():
|
||||
ordinary, acceptance = apu_configurations(ROOT)
|
||||
assert ordinary["formats"] == {"WAV": True, "FLAC": True, "MP3": False, "KWS": False}
|
||||
assert acceptance["formats"] == {"WAV": True, "FLAC": True, "MP3": False, "KWS": True}
|
||||
assert (ordinary["capability"], ordinary["digest"]) == (0x1BD, 0)
|
||||
assert (acceptance["capability"], acceptance["digest"]) == (0x1FD, 0xF5005D7C)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("relative,before,after,message", [
|
||||
("rtl/ip/multimedia/apb4_apu.sv", ".EnableP5(1'b1)", ".EnableP5(1'b0)", "EnableP5"),
|
||||
("rtl/mini/top/apb4_periph.sv", ".EnableP7(EnableP7)", ".EnableP7(1'b0)", "propagation"),
|
||||
("Makefile", "APU_ENABLE_P7 ?= NO", "APU_ENABLE_P7 ?= YES", "identities"),
|
||||
("configs/ci/ihp130-apu.mk", "APU_ENABLE_P7 := YES", "APU_ENABLE_P7 := NO", "identities"),
|
||||
("rtl/ip/multimedia/apu_reg.sv", "32'h0000_01bd", "32'h0000_01b9", "format capability"),
|
||||
("configs/ci/ihp130-apu.mk", "HAVE_CSR := YES", "HAVE_CSR := NO", "IRQ configuration"),
|
||||
])
|
||||
def test_changed_implementation_cannot_retain_apu_summary(tmp_path, relative, before, after, message):
|
||||
root = copy_sources(tmp_path, APU_CONFIGURATION_SOURCES)
|
||||
replace_source(root, relative, before, after)
|
||||
with pytest.raises(ValueError, match=message):
|
||||
apu_configurations(root)
|
||||
|
||||
|
||||
def test_apu_rendered_acceptance_is_source_ordered_and_failure_checked():
|
||||
steps = apu_acceptance_steps(ROOT)
|
||||
assert [step["id"] for step in steps] == ["probe", "quiesce", "stage", "acl", "load", "handoff"]
|
||||
assert [step["failure_code"] for step in steps] == list(range(5, 11))
|
||||
assert all(step["source"] == ACCEPTANCE for step in steps)
|
||||
template = (ROOT / "publications/datasheets/sections/apu-release.typ").read_text(encoding="utf-8")
|
||||
assert "#enum(..data.system_reference.apu_implementation.acceptance_steps.map(r=>r.description))" in template
|
||||
|
||||
|
||||
@pytest.mark.parametrize("before,after,message", [
|
||||
("if (!rs_apu_release_quiesce())", "if (!rs_apu_release_stage_assets())", "call order"),
|
||||
("rs_apu_release_fail(UINT8_C(6));", "rs_apu_release_fail(UINT8_C(7));", "failure checkpoint"),
|
||||
("load_status = rs_apu_microcode_load(&mc_image", "load_status = rs_apu_kws_model_load(&mc_image", "image-load order"),
|
||||
("rs_sysctrl_set_hp_release(true)", "rs_sysctrl_set_hp_release(false)", "publication/release order"),
|
||||
])
|
||||
def test_changed_acceptance_cannot_retain_published_steps(tmp_path, before, after, message):
|
||||
root = copy_sources(tmp_path, (ACCEPTANCE,))
|
||||
replace_source(root, ACCEPTANCE, before, after)
|
||||
with pytest.raises(ValueError, match=message):
|
||||
apu_acceptance_steps(root)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("stale", [False, True])
|
||||
def test_summary_rejects_disabled_jobs_without_rejecting_qualification_limits(stale):
|
||||
folder = ROOT / "publications/datasheets"
|
||||
catalog, features, content = [json.loads((folder / name).read_text(encoding="utf-8")) for name in
|
||||
("ip-catalog.json", "features.json", "ip-content.json")]
|
||||
reference = {"npu_implementation": {"capability": 0},
|
||||
"apu_implementation": {"profiles": apu_configurations(ROOT)}}
|
||||
if stale:
|
||||
next(row for row in catalog if row["id"] == "apu")["summary"] = (
|
||||
"Partially implemented coreless audio subsystem; production codec jobs remain disabled.")
|
||||
with pytest.raises(ValueError, match="contradicts deployed WAV/FLAC"):
|
||||
validate_accelerator_claims(reference, catalog, features, content, {}, {})
|
||||
else:
|
||||
validate_accelerator_claims(reference, catalog, features, content, {}, {})
|
||||
@@ -135,7 +135,10 @@ def test_linux_platform_uses_source_values_and_order():
|
||||
data = sr.linux_platform(ROOT)
|
||||
assert (data["hart_id"], data["timebase_hz"], data["cbom_bytes"]) == (1, 1000000, 64)
|
||||
assert data["initrd_start"] == data["initrd_template_end"] == 0x39000000
|
||||
assert data["ready_writes"][-1] == {"address": "0x1001902C", "value": "0x00000001"}
|
||||
assert data["ready_writes"][-1] == {
|
||||
"address": "0x1001902C", "value": "0x00000001",
|
||||
"register": "HP_DOORBELL", "purpose": "LP interrupt request",
|
||||
}
|
||||
assert data["ready_writes"][1]["value"] == "0x4C4E5801"
|
||||
|
||||
|
||||
|
||||
Reference in new issue
Block a user