L5/03 — The memory map
Node: this file is the object — the memory map, IRQ/pad tables, and the RTL-vs-metadata diff that pins them. The device models that compose with the ISA into Sys are the edge, 06.
Background
A CPU core has no instructions for "print a character" or "read a pin." It has loads and stores, and nothing else — so systems are built on a convention called memory-mapped I/O: regions of the address space are wired not to memory but to devices, and a store to such an address flips wires in a peripheral rather than writing a byte to RAM. A store to the UART's data register starts a byte transmitting; a load from the CLINT's mtime registers reads the running timer; a store to the tile-reset setter holds the processor in reset. The memory map is the table saying which address ranges mean what — and since the CPU's view of the entire world is filtered through it, a verification effort that gets the memory map wrong is proving theorems about a different machine.
The devices behind those addresses each need a formal model — a small transition system saying how register writes translate into behaviour. For the UART that means the divisor register (the programmable number that sets the baud rate by dividing the bus clock) and the framing sequence: on a write to the transmit register, the TX wire emits start bit, eight data bits, stop bit, each lasting divisor clock cycles. Interrupts are the other direction of device communication: rather than the CPU polling devices in a loop, a device raises a dedicated wire when it wants attention, and the CPU suspends the program to run a handler. In this design the wiring is the RISC-V standard shape: the CLINT drives the core's software and timer interrupt lines, and the PLIC funnels device interrupts (here just the UART) into the external-interrupt line, with a claim/complete protocol replacing ad-hoc pending registers.
There is also a fact about where this information lives that deserves a newcomer's attention: the map is generated. The SoC is elaborated from parameterised Chisel generators, and the address assignments come out of the elaboration (the framework's diplomacy layer negotiates them); the same run emits the decode logic in the RTL, a device tree describing every device and its range, and per-device register-map JSON files. Agreement among these artifacts is claimed by construction — they are renderings of one elaboration — and that is precisely the kind of claim this book checks rather than assumes: the diff of the RTL's actual decode against the emitted metadata is this chapter's first deliverable, and any drift is an elaboration bug worth a finding.
Statement
The remaining components of Sys: what each address means, what each device does, and which pad carries what — consolidated from the generated sources into one formal object, diffed against the RTL rather than trusted.
Where the information lives today
| content | authoritative source | rendered in |
|---|---|---|
| memory map | the elaboration (diplomacy) — realised as decode logic in the generated SystemVerilog | the generated device tree (.dts); per-device regmap.json files |
| IRQ map | the elaboration — CLINT→(msip, mtip), PLIC→meip, PLIC source 1 = UART | interrupts-extended / interrupt-parent annotations in the device tree |
| pad list | ChipTop's port list — 18 signals: UART pair, custom_boot, JTAG ×5, reset, clock in, clock tap, serial TileLink (32-bit phits + link clock) | the generated top-level module |
| pad electrical behaviour | sky130_fd_io (PDK) — black-box IO macros | PDK io documentation |
| boot devices | boot ROM (with its baked-in contents), boot-address register, custom_boot pin semantics | generated RTL + ROM image |
| serial TileLink | the bridge RTL (phit serialisation); the far agent is outside the chip (X4 proper) | testchipip documentation |
| UART, CLINT, PLIC | generated RTL | device tree + regmap.json |
| electrical envelope | — | PDK operating conditions — P6/Envelope material as prose |
The concrete map, from the generated device tree of this configuration:
| base | size | device |
|---|---|---|
0x0000_0000 | 4 KiB | debug module (JTAG-reached) |
0x0000_1000 | 4 KiB | boot-address register |
0x0000_3000 | 4 KiB | error device |
0x0001_0000 | 64 KiB | boot ROM |
0x0010_0000 | 4 KiB | clock gater |
0x0011_0000 | 4 KiB | tile-reset setter |
0x0200_0000 | 64 KiB | CLINT |
0x0C00_0000 | 64 MiB | PLIC |
0x1002_0000 | 4 KiB | UART |
0x8000_0000 | 16 KiB | data memory (DTIM) |
The hole semantics matter to 02's contract and are better-behaved than most systems: the fabric routes accesses to unmapped space to the error device, which answers with a TileLink denied response, and a denied response to a load raises an access fault in the core — so a stray pointer produces a precise architectural exception, not a hang or a silent 0xFFFF_FFFF. The address-decode model must say so, and the error device is thereby a spec component, not scenery.
The device models that turn these addresses into behaviour — UART, IRQ/CLINT/PLIC, boot, serial TileLink — and their composition with the ISA into Sys are the edge that this map carries, 06.
Obligations
- The RTL-vs-metadata diff for map, IRQ wiring, and the port list — re-anchoring the layer's checker to the generated artifacts; agreement is expected, and drift is a finding about the generator.
- Track the elaboration-emitted map against the hardened netlist's decode — the elaboration is authoritative for intent, the netlist for the artifact; synthesis must not have changed the table.
Effort
Weeks, mechanical; the map is the extracted table plus the two diffs that pin it. The device models that compose it into Sys are the edge, 06.