Nexus documentation content and diagram standards¶

These standards govern new/changed platform documentation so readers understand tasks, conditions, actions and results for use, integration, maintenance or acceptance. Review existing pages in batches using the implementation ledger. These standards do not establish completion of content migration, diagrams, automation, translation or publication.

Must/must not express requirements; should/should not express defaults with justified exceptions; may expresses permitted choices. Normative rules must identify actors, conditions, actions and checkable outcomes. Codex owns responsibility; independent agents review content/diagrams without invented human accounts.

1. 内容必须帮助读者完成任务¶

ID	Constraint	Acceptance method
TXT-01	Open with outcomes, applicable configuration and essential limitations.	Readers can determine applicability from the opening alone.
TXT-02	Tutorials/how-to guides focus on one primary goal, giving outcomes and necessary steps first.	Independent readers can complete the steps.
TXT-03	One paragraph addresses one question with concrete actors, active verbs and consistent terms.	Remove repeated conclusions, slogans and unexplained abbreviations.
TXT-04	Use tables for comparisons/fields, steps for order, and appropriate diagrams for structure/concurrency.	Tables, diagrams and prose each carry necessary information.
TXT-05	Link raw logs, long hashes and failed attempts as evidence without interrupting main procedures.	Readable summaries locate complete originals.
TXT-06	Separate current implementation, validation, estimates and plans precisely.	Every capability/performance claim has scope and provenance.
TXT-07	Maintain one authoritative standard; summaries/translations/diagrams link it.	Interface changes do not require two handwritten declarations to be synchronized.
TXT-08	Architecture/contract changes review affected diagrams, examples and translations together.	PRs report impacts and review results.

Set no mechanical word, sentence or diagram quotas. Complex pages need task indexes and layered explanations; simple actions need not have diagrams. Unscoped “ultimate”, “complete” or “all supported” claims do not replace cost/qualification records.

Use the five page templates. They define required questions without forcing identical headings. Architecture explanations must address why layers exist, state/resource ownership, calls, build/runtime responsibilities, legal context, failure responsibility, cost and validation boundaries.

2. 术语、单位和约束¶

Introduce bilingual terms where useful, then use one term per concept. C symbols, configuration keys, error codes, fields and machine identity values in CSV/JSON stay unchanged, including states, IDs, digests, paths, versions and configuration values. Translation must not overwrite authoritative CSV/JSON bytes. Human-facing tasks, explanations and exit conditions may have translations or derived displays while preserving original authority and evidence identities. Distinguish:

Term	Meaning in these docs
factory	Typed lookup returning existing static interfaces of this assembly.
face	Public read-only interface containing ops and instance context.
provider	Concrete implementation and private state.
controller/endpoint	Controller identity versus logical/external endpoint identity.
owner/executor	Resource/lifecycle responsibility versus actual execution/progression responsibility.
request/buffer	Request metadata versus borrowed data storage.
DMA complete	DMA phase complete; peripheral/reference drain remains.
wire complete	Peripheral wire transfer complete; other final conditions remain.
SETTLED	The provider drains required references, then release-publishes SETTLED as its final request access; the caller observes with acquire semantics.
QUARANTINED	Not safely ended; borrowing/recovery responsibility remains.

State capacity/measurement units: B/KiB, Hz/MHz, cycles and µs/ms. Record Flash LOAD, Flash footprint, reserved RAM and measured stack high-water separately. Define alignment, length granularity, inclusive limits, overflow, deadline domains and maximum configurations. Do not mix theoretical bounds, estimates and measurements.

Valid rule: after ACCEPTED, callers retain requests/buffers until acquire-observed SETTLED; reuse of adapter/observer storage also requires drained references. Invalid wording: “mind the lifecycle”, which omits actors, final conditions and failure responsibility.

3. 事实、计划和资格必须分别表达¶

Claim	Required basis
Current implementation	Corresponding source, configuration/mode and behavior scope.
Model/Native pass	Exact source, test scope and actual execution.
ARM link/resource validation	Configuration, tools, ELF/BIN/maps and checks.
Software candidate	Clean source, SDK, actual reproducibility and same-artifact evidence.
Physical pass	PCB/chip/equipment/station/image and actual measurements.
Plan/target	Unimplemented tasks/exit conditions, never described as existing capabilities.

Chip features, SDK offerings, maintained providers, Board authorization, software passes and HIL passes cannot collapse into one “supported” label. Current/target/reference scope must be visible in pages and captions. Docs establish no new platform qualification. Retain original source, failed attempts and status; never relabel old results as current HEAD.

4. 示例与命令¶

Complete examples must come from maintained fixtures or pinned external examples and be associated with actual consumer validation. Prefer literalinclude and explain fragments. Illustrations are not complete tutorials. Ordinary builds do not automatically flash devices, execute arbitrary Markdown commands or fetch remote latest.

Every command states working directory, tools/connections, inputs, expected results, success checks and cleanup. Firmware C examples retain C11, 80 columns, four spaces, attached braces, type-side pointers and backslash Doxygen. Tool/test examples retain language conventions, including Python and C++17 GoogleTest/GoogleMock. Docs do not redefine code style.

Async examples must explain rejection, accepted borrowing, progression, waits, cancel, drain and final resources. Timeout/cancel does not revoke borrows; failed stops retain QUARANTINED storage. Wakeups are hints, and infinite waits cannot conceal progression conditions. Tasks, private partitions and recovery stay external.

5. 图示身份与关系¶

Every diagram must have at least an ID, name, purpose, type, scope, relation legend, prose contract and source. IDs support indexes/migration; public anchors use explicit targets/labels rather than automatic front-matter references. Register pairs in the diagram index.

Diagram identity	Allowed meaning	Must not imply
current	Source-checked structure/contracts.	All platforms/modes or physical Boards passed.
target	Defined design awaiting implementation.	New modules/tools already exist or are deployed.
reference	Exact chip/Board/mode reference assembly.	Automatic applicability to other platforms, PCBs or security domains.

One diagram answers one primary question. Layering, build dependencies, generation, data, sequences and states have distinct relations; label each edge when mixed. Explain cross-boundary arrows; unlabeled arrows cannot simultaneously mean calls, generation and ownership transfers.

Nodes name source, interfaces or explicit concepts. Mark optional elements with text/line styles, not color alone. Returns, asynchronous events and state transitions point correctly. Aesthetic changes must not invent CPU factories, hidden tasks, unified pools or mandatory OS layers.

6. 必需图册与语义检查¶

The following diagrams correspond to DOC-43–DOC-57; order/exit conditions are in the ledger.

Diagram ID	Content	Required key facts
FIG-01	Whole-platform architecture and external boundaries	External products; Core/Arch/SoC/I/O; optional components/OS.
FIG-02	Build-target dependencies	Checked against actual CMake; private SDK; applications depend on platform.
FIG-03	Configuration/generation	TOML+facts→typed IR→atomic bundle→CMake→artifacts; failures invalidate.
FIG-04	Factory/instance structure	Existing faces, shared ops, separate contexts; controller/endpoint identities.
FIG-05	Initialization/failed-start withdrawal	Explicit startup, partial effects, reverse withdrawal and retained failure responsibility.
FIG-06	Request states	Rejection/borrowing/draining/quarantine/SETTLED; observers exit separately.
FIG-07	UART/SPI DMA sequences	Separate DMA TC, wire completion, reference drain and final publication.
FIG-08	Wait/wake/shutdown	ready-arm-ready-wait-ready, executor and join responsibility.
FIG-09	CPU/memory/DMA/Cache	Exact configurations, reachable domains, whole cache lines and maintenance timing.
FIG-10	SDK consumption	Actual external projects, relocation, configure/link/run and artifact checks.
FIG-11	Software/HIL evidence	Acquired independently then admitted by scope; no automatic physical qualification.
FIG-12	Docs/SDK publication and recovery	Identities, immutable versions, offline packages, downloads and independent restoration.
FIG-13	Cortex-M capability layers	Primitives, Runtime, SoC integration and physical qualification are separate.
FIG-14	U575 dual worlds	Selected TZEN=1 synchronous reference only; SAU/MPU/GTZC/gateway responsibilities.
FIG-15	Continuous streams and lost blocks	producer/block/consumer, overrun, stop/drain and service budgets.

Runtime diagrams must show that after factory lookup, ordinary I/O calls faces/providers directly; Arch is compile-target-selected; applications own scheduling/progression. Static structure does not determine initialization order or represent every runtime call.

REJECTED/ACCEPTED are admission outcomes, not invented nx_request_state_t enum states. Publish SETTLED only after required reference drain; cancel/deadlines never point directly to reclaimed storage. Ending QUARANTINED needs actual recovery/drain proof without implying every provider has recovery APIs. Sequence diagrams must include failure branches or link separate failure diagrams, with Task/IRQ/DMA/security domains marked.

Diagrams do not replace preconditions/contracts. Conflicts suspend affected delivery claims until sources are corrected; changing diagrams/tutorials alone must not hide contract conflicts.

7. 图源、视觉和离线交付¶

Initially use editable Graphviz DOT and local SVG pairs. Sphinx may later use its graphviz extension; new chains/locks follow DOC-25/33. Existing Mermaid is migration input, not another authority for the same diagram. Specialized sequence tools need independently reviewed closures justified by real demand.

Every diagram satisfies:

Reviewable source and stable names/IDs; regenerate after source changes.
Dark text/clear boundaries; colors are not sole meaning and grayscale remains distinguishable.
Short specific labels with detailed prose; split dense diagrams rather than shrinking unreadably.
Complete Chinese/English/C symbols without missing glyphs, overlap, clipping or blurry screenshots.
Alt text/captions; narrow screens allow zoom/standalone SVG rather than forcing tiny text.
SVG defaults exclude scripts, animation, foreignObject, external href/resources and DOCTYPE.
Offline packages include diagrams/sources; loading, font notes and checks need no CDN.
Graphviz/actual fonts belong to tool closure; missing/different tools never claim validation.

Successful SVG parsing/rendering does not prove architecture correctness. Independent review must check every call/dependency, state and failure edge. Actual display checks desktop, narrow/zoom and print; unexecuted checks remain unverified.

8. 评审与自动化职责¶

Check	Machine responsibility	Independent semantic responsibility
Prose	Formatting, fields, links, anchors and navigation.	Complete tasks, correct prerequisites and clear terminology.
Examples	Actual parsing/building, pinned inputs and exits.	Correct success/failure/recovery and ownership.
Diagrams	Source syntax, pairs, SVG resources and hashes.	Arrows/options/sequences/states match code.
Translation	Source versions, missing/fuzzy messages and status.	Preserved normative strength, units and failure conditions.
Delivery	Manifests, relative links and actual site identity.	No confusion of support, plans or qualification.

Regex prose scanning never automatically decides “supported” or “safe”. New gate behavior uses actual negative-path TDD. Prose/diagram-source changes use applicable checks/semantic review without implementation-mirroring tests.

Reviews bind pages/diagrams, code/docs sources, findings, resolution and exit conditions. Correct these before closing tasks: invalid configurations, early borrow reclamation, wrong completion order, invented modules, false support/HIL, broken links, unmarked stale translations or unreadable critical diagrams.

Ledger state determines standard application and 58-item implementation acceptance. Unified CLI runs offline commit checks, strict CI, source/output pairing and English/Chinese checks for every current page. Source digests, review markers and newly extracted complete strict-build message sets must all agree; missing/stale/fuzzy translations fail. Mixed sources may use source-language catalogs while code, identifiers and original evidence remain unchanged. Archives do not count toward current translation completion. Semantic, visual, publication and restoration records bind actual inputs; rules/workflows alone never establish execution.