README.md

simpler Documentation

Index of every document under docs/, grouped by what you are trying to do. The top-level README links only the handful of entry-point docs; this page is the complete map.

These pages are also published as a searchable site at https://hw-native-sys.github.io/simpler/, which adds a generated API reference for simpler.worker, simpler.task_interface and simpler.orchestrator. The site is built by .github/workflows/docs.yml; mkdocs.yml owns its navigation, so a new page needs a nav entry there as well as a row here.

New docs belong in one of the groups below, and in a subdirectory when the group already has one (dfx/, hardware/, troubleshooting/, investigations/). Add the row here in the same commit — an unlisted doc is invisible.

File names are kebab-case (chip-level-arch.md), including when the doc is named after a code identifier that uses underscores.

Start here

Two audiences use this tree. If you are building on simpler — writing kernels and orchestration, running and measuring them — start at user/, which routes you through install → first run → write a kernel → profile → debug. Everything else here is written for people changing simpler's own internals.

Document	What it covers
Using simpler	The user-facing entry point: how-to guides and the Python / CLI reference
Getting Started	Prerequisites, PTO-ISA setup, first example run
Installation and Runtime Environment	Install layout and the runtime environment variables
Developer Guide	Directory structure, role ownership, when to rebuild
Capability Survey	Status snapshot — what is shipped, gated, or design-only across topology, launch, and communication. Read this before assuming a mechanism works

Architecture

Document	What it covers
Chip-Level Architecture (L2)	Three-program model (host / AICPU / AICore), API layers, handshake
Hierarchical Level Runtime	The L0–L6 level model and component composition
Task Flow	Callable / TaskArgs / CallConfig pass-through, IWorker
Buffer Memory Model	How L3+ tasks name data: canonical identity, backend descriptor, strided view
Orchestrator	DAG submission: TensorMap, Scope, Ring, task state machine
Scheduler	DAG dispatch: wiring / ready / completion queues, dispatch loop
tensormap_and_ringbuffer: A2/A3 vs A5	Per-file comparison split into hardware/PTO-ISA architecture differences and implementation differences
Worker Manager	Worker pool, THREAD/PROCESS modes, fork + mailbox mechanics
hardware/	Hardware substrate: chip architecture, cache coherency, MMIO performance, CANN source references

Kernels and task authoring

Document	What it covers
AICore Kernel Programming	Writing AICore kernels for this runtime
a5 AICore SIMT Launch	a5 SIMT launch metadata and the ChipCallable alignment constraint
Manual Scope V0	Explicit scope control from orchestration code
WAR Anti-Dependencies	Write-after-read hazards and how the runtime orders them
TPUSH/TPOP Guidelines	Advisory usage rules for the push/pop instructions

Launch, linking, and callable registration

Document	What it covers
AICPU Kernel Launch Mechanisms	How the AICPU SO is bootstrapped, registered, and launched via CANN
Dynamic Linking and TLS	Binary registration, relocation, thread-local storage on device
Callable Identity Registration	How a callable is identified and registered across tiers
Dynamic Callable Registration over IPC	Registering callables into a running child process
Python Callable Serialization	Serializing Python callables for L3+ registration

Multi-chip, multi-host, and communication

Document	What it covers
Communication Domains	Dynamic CommDomain allocation and the symmetric window
L3-L2 Orchestrator Communication	Host-side L3 talking directly to the L2 AICPU orchestrator
L3-L2 Message Queue	The queue channel between an L3 host and L2
Directed NEXT_LEVEL Scheduling	Targeting a specific next-level child instead of any free one
Remote L3 Worker Design	L4 host-to-host workers — protocol, transports, status
remote-l3-worker-design/	Full design set: protocol, buffers and transports, implementation plan and record

Profiling, logging, and DFX

Document	What it covers
dfx/	Every profiling and diagnostics reference, indexed: framework and naming rules, L2/core swimlanes, PMU, host trace, device phases, scheduler-overhead model, args dump, dep_gen, scope stats, backpressure, buffer-capacity audit
Log System	Log levels, sinks, and the host/device logging split

Building, testing, and packaging

Document	What it covers
Testing	Test types (st / pyut / cpput), how to run them, writing new tests
CI Pipeline	Jobs, gating, and what each pipeline stage covers
Python Packaging	Wheel layout, simpler vs simpler_setup, asset packaging
Compiler Sanitizers	ASAN / UBSan / TSAN builds
Sim Multi-Device Isolation	How the simulator isolates concurrent virtual devices

When something is broken

Document	What it covers
troubleshooting/	Device error codes, local timeout defaults, AICPU shared-SO faults, sim oversubscription hangs, macOS build issues, cpput ABI issues
investigations/	Considered-and-dropped proposals and measured dead ends. Check here before proposing an optimization or refactor