Skip to content

Latest commit

 

History

History
528 lines (471 loc) · 36.4 KB

README.md

File metadata and controls

528 lines (471 loc) · 36.4 KB

FROST RTL

This directory holds FROST's synthesizable SystemVerilog: a single-hart RV64GCB out-of-order CPU, its memory system, and its peripherals. The CPU schedules with Tomasulo's algorithm, decodes, renames, and commits up to two instructions per cycle, and runs M, S, and U modes with Sv39 virtual memory. Around it sit 256 KiB of on-chip BRAM, a three-cache hierarchy over a configurable DDR aperture, an APLIC, a RISC-V debug module, and a 10GBASE-R NIC.

The RTL is portable. Defining FROST_XILINX_PRIMS selects explicit Xilinx primitives in a few modules. FROST_RVFI_DII, for simulation only, builds the TestRIG variant, which runs an injected instruction stream and reports every retired instruction. Board integration lives in boards/ and fpga/, and frost.f lists every source in compilation order.

Top-Level Shape

The CPU and system architecture diagram shows the datapath, translation, memory tiers, MMIO, and debug interfaces. The component cache diagram shows the line-cache hierarchy used by the component benches.

frost.sv wraps platform_top with reset synchronization, UART clock crossings, and MMIO FIFOs. platform_top connects the reusable cpu_top to the FROST soc_top through one AXI4 master and an optional coherent-agent ingress. cpu_top contains the pipeline, MMUs, caches and memory-system logic, as one hart (frost_hart) and the shared L2 and AXI master below it (frost_cluster_memory). soc_top owns low BRAM, peripheral registers, timers/APLIC, debug transport, NIC, DMA and the DDR connection. i_clk runs SoC logic; i_clk_div4 runs UART and programming logic. With the default ASYNC_CPU_CLOCK=0, the CPU also uses i_clk. With ASYNC_CPU_CLOCK=1, i_cpu_clk runs the CPU, coherent bridge, IMSIC decoder and Debug Module. AXI asynchronous FIFOs and control synchronizers in soc_top connect those domains. The standalone CPU has one clock; its integrating wrapper owns clock crossings.

Stage Main files Role
IF cpu_and_mem/cpu/if_stage/ 64-bit fetch window, branch prediction, instruction alignment
PD cpu_and_mem/cpu/pd_stage/ Compressed-instruction decoding and early branch redirects
ID cpu_and_mem/cpu/id_stage/ Decode and prepare up to two instructions for dispatch

The back end has a 32-entry ROB, separate integer and FP rename tables, four reservation stations, load and store queues, and two result-broadcast lanes. The integer station issues to two ALUs, and branches use the first; the other stations issue one operation per cycle. See the CPU guide for the front end and branch prediction, and the Tomasulo guide for scheduling, execution, and commit.

Sv39 translation uses a 16-entry ITLB, a 16-entry DTLB, a 512-entry second-level TLB with a 32-entry superpage side array, and one read-only page-table walker shared by both MMUs, with 4 KiB, 2 MiB, and 1 GiB pages. Software manages the accessed and dirty bits (Svade): an access that needs one set raises a page fault. satp.ASID is nine bits wide, and TLB entries carry their ASID and the leaf's global bit, so a satp write that changes only the ASID keeps the entries and sfence.vma flushes by address, by ASID, or both. A satp write that changes the root under one ASID flushes every entry.

Directory Map

Path Purpose
frost.sv, frost.f SoC wrapper and RTL source list
platform_top.sv FROST CPU/SoC composition
cpu_top/ Standalone CPU: one hart (frost_hart.sv), the shared L2 and outgoing AXI master (frost_cluster_memory.sv), and their composition (cpu_top.sv)
soc_top/ FROST memory, peripheral and debug integration
cpu_and_mem/ Shared pipeline and platform component implementations
cpu_and_mem/imem_predecode.sv Low-BRAM instruction memory with optional fetch metadata
cpu_and_mem/low_bram_fetch_presenter.sv Fixed-latency TestRIG and unit-bench fetch presenter
cpu_and_mem/fetch_provider.sv Cached and uncached instruction fetch buffers
cpu_and_mem/dma_test_engine.sv, dma_test_engine_axi.sv Coherent DMA copy/fill engine, and its AXI4 master
cpu_and_mem/hang_triage.sv UART diagnostics for hardware hangs (ENABLE_HANG_TRIAGE=1; default 0)
cpu_and_mem/debug/ JTAG transport and RISC-V debug module
cpu_and_mem/cpu/cpu_ooo/ CPU integration and pipeline control
cpu_and_mem/cpu/tomasulo/ Dispatch, ROB, rename tables, queues, and functional-unit adapters
cpu_and_mem/cpu/if_stage/, pd_stage/, id_stage/ Front-end pipeline stages
cpu_and_mem/cpu/mmu/ Sv39 TLBs and hardware page-table walker
cpu_and_mem/cpu/csr/, control/trap_unit.sv Privileged state, exceptions, and interrupts
cpu_and_mem/cpu/wb_stage/generic_regfile.sv Integer and FP register files
cpu_and_mem/cpu/ex_stage/ ALU, multiply/divide, FPU, and branch execution
lib/cache/ Coherent L1 caches in coherent_hart_cache.sv, the shared L2 home in coherence_home.sv, DDR bridge, and simulation DDR model
lib/axi/ AXI4 DMA interconnect, coherent ingress bridge, register slices and AXI4-Lite register bridge
lib/ RAM, FIFO, and clock-domain-crossing primitives; line_align.sv, which moves an access between register order and a pair of cache lines
peripherals/imsic/ AIA IMSIC with machine and supervisor interrupt files in each CPU, with SoC MSI store decode
peripherals/nic/ Ethernet NIC with coherent DMA
peripherals/aplic/ AIA APLIC with machine and supervisor domains, direct delivery and optional MSI forwarding
net10g/ Portable 10GBASE-R MAC/PCS
peripherals/ UART transmit and receive blocks

Memory Map

Region Address Size Contents
ROM 0x0000_0000 95 KiB Code and read-only data (low BRAM)
DEBUG 0x0001_7C00 1 KiB Debug-module execution slice (see Debug); reserved by every linker script that uses low BRAM and written only by the debug module
RAM 0x0001_8000 160 KiB Data, BSS, and stack (low BRAM)
MMIO 0x4000_0000 196 KiB Device registers (table below)
APLIC 0x4400_0000 4 MiB AIA direct and MSI delivery, M and S domains of 32 KiB each
IMSIC 0x4800_0000 2 MiB 4 KiB M and S pages at 0x4800_0000 and 0x4810_0000, with 0x1000 hart stride
DDR 0x8000_0000 Configured 1–128 GiB (1 GiB default aperture) Cached region: .ddr_text code, large data, and the heap; software must use the populated size
DDR uncached alias DDR address with bit 30 set (0xC000_0000, 1 GiB of DDR) or bit c set (a 2^c-byte DDR window, c >= 32: [2^c + 2^31, 2^(c+1))) The aliased DDR Not in the PMA map. Svpbmt: the walker gives NC and IO leaves over DDR this alias; the MMUs make such an access MMIO (at the ROB head, no AMOs, no fetch) and the SoC turns it into a single-beat coherent DMA transfer of the real DDR address. An untranslated access, or a PMA leaf, there is an access fault

With less than 1 GiB of DDR, the uncached alias is disabled and NC or IO leaves based in DDR raise an access fault.

Addresses outside the defined regions, including the rest of the device quadrant [0x4000_0000, 0x8000_0000) and addresses at or beyond the configured DDR end (0x8000_0000 + 2^FROST_DDR_CAPACITY_LOG2_BYTES), are unmapped: a fetch, load, store, or AMO there raises a precise access fault (cause 1, 5, or 7) and never aliases onto the map. DDR addresses above 4 GiB remain valid when they are inside the configured aperture. At the default 1 GiB capacity, 0xc000_0000 and higher addresses fault (the Svpbmt alias above DDR is reached only through an NC or IO page). Fetch also faults in the low BRAM above its 128 KiB code region [0, 0x2_0000). Under Sv39 the data MMU checks alignment before translation and page permissions before the physical address. For an untranslated access, the access fault takes priority over misalignment.

The ROM, DEBUG, and RAM regions divide the 256 KiB low BRAM as the unified linker script (sw/common/link.ld) does. Low BRAM holds separate instruction and data copies. The data copy covers all 256 KiB; the instruction copy covers only the first 128 KiB, the code region, which holds ROM, DEBUG, and the first 32 KiB of RAM. The JTAG loader writes both copies (the instruction copy only below 128 KiB), but outside Debug Mode CPU stores reach only the data copy, so code in low BRAM cannot be modified at run time; put self-modifying code in DDR. Low-BRAM data and instruction accesses cross the same variable-latency AXI boundary as other CPU requests. FROST enables Normal read caching: 32-byte fetches fill an 8 KiB direct instruction cache, and aligned dword data reads fill L0. Stores remain narrow write-through accesses, and the debug data page bypasses the read cache. The standalone CPU defaults to strict uncached access with 8-byte instruction fetches. The CPU computes predecode metadata from the returned bytes. The SoC executes each local access once and buffers its completion independently of AXI backpressure; see the CPU interface.

Instruction fetch and data accesses both reach the cached region. The hierarchy has a 128 KiB L1D, a 16 KiB L1I, and a shared 2 MiB L2. All three are 4-way set-associative with tree pseudo-LRU replacement (the L1D with bimodal insertion). The L1I is read-only. The L1D and L2 write back dirty data; L1D stores acquire M before changing their sector. The L1s use 32-byte lines; the L2 uses 64-byte lines, each holding two of them, and moves whole lines to and from DDR as single 512-bit AXI transfers. With L2_LINE_BYTES=32 the L2 uses the L1s' line size and the DDR port is 256 bits wide. Cached accesses have variable latency, and L1 hits proceed while misses are pending. The L1D, the page-table walker, the L1I, and DMA send their requests to the L2's coherence home, which orders them by 32-byte sector. DMA and page-table walks see dirty L1D data without software cache maintenance. Code fetched from DDR passes through a buffer of two active lines and six victim lines in front of the L1I. See the cache guide.

fence.i drains stores through L1D installation, waits for instruction-copy writes, invalidates the L1I, and flushes the fetch buffer before refetch. The home probes L1D for instruction refills and PTE reads, so dirty data can remain in L1D. Reset invalidates the caches. With ENABLE_CACHED_TIER=0 there is no hierarchy: cached-region loads return zero, stores complete without effect, fetch uses low BRAM only, and the NIC and DMA test engine windows read zero. USE_BEHAVIORAL_DDR=0 connects the DDR bridge to the board's o_ddr_axi_* ports.

MMIO registers:

Address Name Description
0x4000_0000 UART_TX UART transmit write
0x4000_0004 UART_RX_DATA UART receive read, pops one byte
0x4000_0008 FIFO0 MMIO FIFO channel 0
0x4000_000C FIFO1 MMIO FIFO channel 1
0x4000_0010 MTIME_LO Machine timer low word
0x4000_0014 MTIME_HI Machine timer high word
0x4000_0018 MTIMECMP_LO Timer compare low word
0x4000_001C MTIMECMP_HI Timer compare high word
0x4000_0020 MSIP Machine software interrupt pending
0x4000_0024 UART_RX_STATUS Bit 0 is data available
0x4000_0028 UART_TX_STATUS Bit 0 is TX ready: at least 64 more bytes fit in the transmit FIFO
0x4000_1000–101C ns16550a UART face 16550 register file (word stride) aliasing UART_TX/RX for the Linux 8250 driver
0x4001_0000 CLINT MSIP SiFive CLINT alias of MSIP
0x4001_4000/4004 CLINT MTIMECMP_LO/HI SiFive CLINT alias of MTIMECMP
0x4001_BFF8/BFFC CLINT MTIME_LO/HI SiFive CLINT alias of MTIME
0x4002_0000–0057 DMA test engine Legacy CTRL/ACK/SRC/DST/LEN/MODE/PATTERN/STATUS_ADDR/STATUS_VALUE/LINES plus versioned ABI_CTRL and SRC64/DST64/STATUS_ADDR64 (dma_test_engine.sv, sw/lib/include/dma_engine.h)
0x4002_1000–1038 Memory error unit CAPS/STATUS/IRQ_EN/CE_COUNT/UE_COUNT/AXI_RD_ERRS/AXI_WR_ERRS/CE_ADDR/UE_ADDR/AXI_ERR/ECC_POLLS (memory_error_unit.sv, sw/lib/include/memory_error.h)
0x4002_4000–7FFF External AXI4-Lite window Optional 16 KiB board peripheral window (EXT_AXIL_WINDOW=1) behind an axil_register_slice (AXI integration guide)
0x4002_F000 SYSRESET Stores at this address with both low byte strobes set and low 16 bits 0x7777 reset the core domain like ndmreset, including doubleword stores; upper data bits are ignored and reads return zero. The CPU restarts at the boot address. BRAM and DDR storage survive, but dirty cache lines are discarded. OpenSBI uses it through syscon-reboot (see reset contract).
0x4003_0000–0FFF NIC 4 KiB window: control and status, station address, rings, link and PHY, 64-bit counters (peripherals/nic/nic_pkg.sv, sw/lib/include/nic.h)

The UART console runs at 115200 baud, 8N1. For Linux, the same UART also appears as an ns16550a at 0x4000_1000 (word stride: device tree reg-shift=2, reg-io-width=4; earlycon=uart8250,mmio32), and the timer as a SiFive CLINT at 0x4001_0000 (mtimecmp at +0x4000, mtime at +0xBFF8). Both are aliases of the native registers, so the kernel's standard 8250 and CLINT drivers work without a board-specific driver. The 16550's LSR.THRE and its THRE interrupt follow UART_TX_STATUS, so the 8250 driver's 16-byte burst per THRE always fits, and LSR.TEMT reads 1 only once every byte written has been sent.

The APLIC implements AIA 1.0 direct and MSI delivery. Its machine and supervisor domains at 0x4400_0000 and 0x4400_8000 drive the CPU's IMSIC direct inputs. Each file resets to APLIC delivery; its registered line supplies mip.MEIP or the external contribution to mip.SEIP, which is ORed with the SEIP bit M-mode software can set. Each domain occupies 32 KiB and has one IDC for hart 0. Source identities are 1 for the ns16550 UART, 2 for the external pin, 3 for the DMA test engine, 4 for the NIC, and 5 for the memory error unit. OpenSBI delegates all five sources to the supervisor domain. Linux configures them for level-high delivery through the supervisor IMSIC file. Both APLIC domains reset to direct delivery for programs that do not configure MSIs. The generated firmware tree links both APLIC domains to their IMSIC nodes.

A claimi read returns the identity in bits 25:16 and priority in bits 7:0. It clears detached and edge-sensitive pending bits; a level-sensitive source stays pending until the device drops its level. There is no completion write. The SoC performs claims only on 32-bit reads (see the data-tier bus contract).

The memory error unit counts the DDR controller's corrected and uncorrectable ECC errors and the error responses DDR returns to the cache hierarchy's AXI bridge. It keeps the physical address of the latest ECC report of each kind and the response code and AXI id of the latest error response, and interrupts for the kinds IRQ_EN enables. An error response still completes the transfer, so a read delivers its data and the report arrives after the access. On the X3, boards/x3/x3_ecc_reader.sv polls the DDR4 controller's ECC registers about once a millisecond and reports to the unit; on a board without a reader, CAPS bit 0 reads 0 and only the error responses count.

If these addresses change, update soc_top/soc_top.sv, the device-window pages in riscv_pkg.sv (MmioFirstPage through ImsicLastPage), the MMIO PROVIDE symbols in the linker scripts under sw/ (sw/common/link.ld, sw/common/link_ddr.ld, and several app-specific scripts), sw/lib/include/mmio.h, the verification constants in verif/config.py, and the Linux device tree generated by linux/buildroot-external/board/frost/frost_boot_image.py. A simulation stops at time zero if the device-window pages disagree with the windows in soc_top/soc_top.sv or break the layout the PMA's page decodes assume (see the check in soc_top/soc_top.sv). The debug slice's location is riscv_pkg::DebugSliceBase; every FROST linker script that uses low BRAM reserves it as the DEBUG region.

Data-tier bus contract

The internal data-side interfaces between the queues, request router and CPU adapters carry a 64-bit dword container (riscv_pkg::MemDataBits) with an 8-lane byte strobe (MemStrbBits). The beat is selected by the configured physical address bits above bit 2, and byte lane i has that same beat address with byte offset i. Producers position data by addr[2:0] and consumers extract by addr[2:0]:

  • Stores replicate their data across the beat ({8{byte}}, {4{half}}, {2{word}}, a dword as is) and the strobe selects the lanes: BYTE = 8'h01 << addr[2:0], HALF = 8'h03 << {addr[2:1], 1'b0}, WORD = addr[2] ? 8'hF0 : 8'h0F, DOUBLE = 8'hFF (riscv_pkg::mem_strobe_for). Replication keeps the write-data mux shallow; there is no byte-lane shifter.
  • Cached reads and optional Normal read-cache fills return the whole beat. Strict uncached and Device AXI reads guarantee only the requested byte lanes and never fill L0. load_unit selects the word by addr[2], then the halfword or byte, then sign- or zero-extends. LD and FLD take the beat whole.
  • MMIO registers sit in their address-matching lanes (a 32-bit register at offset +4 occupies lanes [63:32]), so extraction has no MMIO special case.
  • A dword access never spans beats, so there is no beat-crossing logic; the size-cased misalignment checks cover the 8-byte class (|addr[2:0]).
  • The load queue's L0 cache and store-to-load forwarding work on dwords. The data BRAM's $readmemh image is the dword-paired sw64.mem (sw/common/make_dword_mem.py); sw.mem, sw.txt, and both DDR images stay in 32-bit words.
  • Cached loads are tagged. The load queue names one of its riscv_pkg::CachedLoadSlots slots on each cached launch, and the response returns it beside the beat, so several cached loads can be in flight and complete in any order. The coherent L1D tracks each load in its own read slot and sends up to seven load misses to the home at once, one per 32-byte sector. Uncached Normal and Device reads share one response owner until AXI R is consumed. The router arbitrates their completed response with cached beats; no later uncached read may overwrite that owner. The outgoing 256/512-bit AXI port preserves the original narrow Device size, address and strobes; optional Normal read caching widens only eligible reads. See the CPU interface.

The MMIO bus follows the same rules. The dword-aligned timer pairs, native and CLINT alias, support 64-bit access: an 8-byte load of mtime (0x4001_BFF8) returns the whole counter atomically, and an 8-byte mtimecmp store lands atomically. The 32-bit lo/hi aliases keep their word behavior. UART and FIFO registers are 32-bit-access-max: a wider store writes only the addressed word. Each empty FIFO contributes zero to its 32-bit read lane and an empty read pops nothing. A non-empty FIFO returns its head word; only the addressed FIFO is popped. The response is captured before the pop and stays stable through backpressure. The APLIC accepts only 32-bit accesses. Byte, halfword and doubleword writes are ignored; reads of those sizes return zero without side effects. The DMA test engine, memory error unit, and NIC windows provide 32-bit registers: a 64-bit load returns an aligned register pair, and a 64-bit store writes only the upper register. The NIC's RX_BASE64/TX_BASE64 registers and the DMA engine's SRC64/DST64/STATUS_ADDR64 bank accept complete aligned 64-bit stores; partial writes to those dwords have no effect. The NIC and DMA register windows use 64-bit AXI4-Lite. Each block's register bridge buffers AW and W independently, applies the register access once, and holds its registered OKAY response until accepted. Other windows use the local MMIO sequence. Devices take loads and stores only inside the MMIO, APLIC and IMSIC windows. A load or store elsewhere in the device quadrant raises an access fault (cause 5 or 7). An AMO, LR or SC anywhere in the quadrant raises cause 7, 5 or 7, respectively. These faults reach the ROB without issuing a device read or write. The memory map gives the fault priority.

IMSIC pages accept only aligned 32-bit stores, at offset 0 for little-endian identity data or offset 4 for big-endian data. Other sizes and offsets are ignored. All loads in the 2 MiB window return zero without side effects. The SoC registers the decoded MSI in the CPU clock domain. With the optional asynchronous boundary, a FIFO carries the MSI stores to that decoder.

MMIO is strongly ordered: accesses from one hart complete in program order without fences. Uncached stores retire only after B; reads wait for R. Errors raise precise access faults. Failed cached reads do not fill caches, and late errors on buffered cached stores stop the CPU with a sticky fatal indication. A device read waits for committed stores to drain and is shielded from interrupt replay, so a destructive read (the UART RX pop, a APLIC claim) happens exactly once. See the load queue guide.

Debug

The debug module in cpu_and_mem/debug/ implements the RISC-V Debug Spec 0.13.2: a debugger can halt, inspect, patch, single-step, and resume the hart over JTAG. In simulation and the portable synthesis targets, the transport is a generic TAP with a five-bit IR on frost's i_jtag_* pins (DEBUG_JTAG_TAP=1). Board builds drive it instead from two BSCANE2 USER chains on the FPGA's own TAP (boards/, with the OpenOCD configuration in fpga/debug/).

Halt and single-step requests use the trap machinery, which drains stores and protects atomic operations and device reads. Debug Mode saves dpc and dcsr, masks interrupts, and runs the module's commands from the reserved low-BRAM debug slice. The module supports abstract GPR access and an 8-word program buffer. Debugger memory accesses run through that buffer; there is no system bus access.

The Debug Module registers GO and its target after the instruction slice is visible. GO stays asserted with a stable target until the hart acknowledges it. Acknowledgement, module reset or a fatal stop of the hart clears GO on that clock edge. Command and resume sequencing waits for the hart's response to this request.

The system reset (the board-level reset, which on X3 follows the clock lock and DDR readiness, and the image-load reset) also resets the debug module, so dmactive, a pending halt request, and the program buffer do not survive it. Debug Spec 0.13.2 (section 3.2) resets the module only at power-up and while dmactive is 0; FROST treats these resets as power-up. ndmreset and SYSRESET reset only the core. A DMI access that arrives while the system reset is held waits, with the DTM reporting busy, and is handled when the reset ends, with dmactive 0.

A fatal memory-error stop of the hart makes the debug module report it as unavailable: dmstatus allunavail and anyunavail read 1, and allrunning, anyrunning, allhalted and anyhalted read 0, also for a hart that was already in Debug Mode when the stop arrived. haltsum0 reads 0. The hart refuses halt and step requests after the stop, in every configuration. An abstract command written while the hart is unavailable is not started and sets cmderr 4; a command in flight when the stop arrives ends the same way, so abstractcs.busy clears. A resumereq write clears the resume acknowledge and starts no resume; a resume in flight when the stop arrives ends with the acknowledge still 0. haltreq remains the level the debugger wrote, so a set haltreq halts the hart once the reset has cleared the stop. The resets that clear the hart's stop end the report: the system reset, ndmreset, SYSRESET and the DDR or fabric reset; clearing dmactive does not. Inspecting a hart after a fatal stop is not supported (see the roadmap).

A debugger write of the SYSRESET key executes through the program buffer and can leave its abstract command busy across the reset; halt the hart so it parks again and completes the command.

debug_slice_writer writes the module's words into the slice through the BRAM programming port. It also mirrors Debug-Mode stores to the low BRAM's code region into the instruction copy, so software breakpoints and debugger writes to BRAM code are fetched. FENCE.I waits for the mirror completion before invalidating fetch state. With asynchronous CPU and SoC clocks, the store response waits for the mirror, so the committed-store drain supplies that ordering. For code in DDR, OpenOCD executes fence.i; refills obtain the patch through the home probe. Debug CSRs and dret are illegal outside Debug Mode.

For OpenOCD, GDB, and VS Code use, see the FPGA guide.

Build and Simulation

The frost DDR interconnect reset asserts asynchronously. Its three-stage release synchronizer feeds a separate register for reset distribution. That register also asserts asynchronously and releases one clock edge after the synchronizer. A stopped SoC clock keeps the reset asserted. CPU owners and the fabric share this reset; CPU-only reset leaves presented AXI requests to drain through the fabric.

With a common CPU and SoC clock, a core or DDR transport reset request sampled on one rising edge asserts both the DMA bridge and CPU reset pins. The CPU pin stays high for one more edge after the bridge reset drops, giving the CPU and its coherent ingress two reset edges. With the clock stopped, the CPU reset pin holds its value. An external DDR reset pulse during the stop holds fabric reset high until the clock resumes. The first rising edge asserts the registered resets. The next edge discards the CPU and DMA owners together. After the fabric reset clears, the bridge reset drops on the next edge and the CPU reset drops on the following edge if all requests are clear.

Reset belongs at the flop, as if (rst) ... else .... Combinational outputs can stay live in a first reset cycle, when every receiver on the same reset ignores them. A reset term stays in combinational logic only where a receiver is not reset by the same signal, with a comment saying why. tests/test_combinational_reset.py fails on a term that tests/combinational_reset_allowlist.txt does not list.

Synchronous resets establish pipeline validity, queue ownership, control state, and architectural control registers. Cache reset clears tags and replacement state before accepting requests; cache data arrays do not need clearing. The coherent arrays use a per-set sweep in hardware. In simulation, SIM_FAST_MAINT=1 clears their metadata in one cycle after an observed reset, then drains pending RAM writes before accepting requests. The BTB clears its valid bits, and the return-address stack clears its occupancy. Direction and TAGE tables provide speculative hints; their contents affect prediction accuracy rather than architectural state. Payload RAMs are qualified by ownership or validity, or written before use. Integer consumers substitute zero for x0; the unwritten register-file row has an unspecified read value. Software initializes the other integer and floating-point registers it uses. Program images supply the instruction and data memories independently of reset.

platform_top.i_power_on_rst is an asynchronous power-on request, separate from system reset. Hold both resets at power-up with the selected CPU clock running: i_cpu_clk when ASYNC_CPU_CLOCK=1, otherwise i_clk. The core synchronizes the power-on request before synchronously resetting the debug transport handshake and the debug module's pending DMI request. These survive system reset. TCK reset asserts asynchronously, releases after two TCK edges, and resets the TAP and transport handshake even if TCK is stopped. TRST_N resets the TAP alone. Either transport domain may release first: a held TCK produces no request, and a request launched while the core is held waits for its answer after core reset releases.

The programming-clock domain also synchronizes power-on reset. It clears instruction-memory staged write enables and blocks writes on the first reset edge. System reset leaves this programming path available for image loading. Fetch reset clears metadata readiness and repeated-address history. FPGA tops tie the power-on request inactive, select POWER_ON_RESET_ENABLE=0 to omit its synchronizers, and use configuration-loaded initial values. platform_top enables power-on reset by default. Simulation pulses it independently of system reset in both ordinary and random power-up mode. The random mode checks dependencies on initializers and uninitialized storage.

Full-board simulation with power-on reset tied inactive uses configuration initializers. The DTM ownership assertions arm only after power-on reset in their respective clock domains, so that configuration does not check DTM ownership. Transport verification uses a bench that enables and pulses power-on reset with the core clock running.

Use the test guide for simulation, formal, and Yosys runs in the pinned container, the FPGA guide for native Vivado builds, and the ASIC guide for the OpenROAD flow. frost.f is the system source list and cpu_top/cpu_top.f the standalone CPU's. TestRIG alone compiles hw/sim/frost_rvfi_platform.sv, which provides positional instruction injection and the fixed-latency pipeline test interface.

Simulation sets parameters with Verilator -G overrides. For the frost top, tests/Makefile sets the low BRAM to its 256 KiB hardware size (SIM_MEM_SIZE_BYTES), enables the cached tier with the X3 hierarchy, sets the DDR model's size and latency, and turns on fast coherent-array reset and L1I maintenance (SIM_FAST_MAINT=1). Individual entries in tests/test_run_cocotb.py add their own overrides, such as -GFETCH_VALID_FUZZ=1 for the fetch-fuzz runs and DDR latency jitter or reordering for stress runs. The cache unit benches instantiate frost_cache_hierarchy directly, with smaller caches so that evictions are cheap to reach.

ASYNC_CPU_CLOCK=1 selects an independent CPU clock on i_cpu_clk. CLK_FREQ_HZ describes i_clk, including the NIC tick and UART divisors. The machine timer increments on i_clk; the CPU reads coherent snapshots through its time CSR. The boot address is a static parameter. Reset release waits for both clocks. Power-on reset leaves these paired system and fabric resets separate; they establish ownership in the CPU/SoC crossings. The SoC guide describes the crossings and reset ownership.

Parameters

The main parameters; frost.sv documents the rest.

Module Parameter Default Description
frost.sv CLK_FREQ_HZ Defined in frost.sv SoC clock frequency
frost.sv ASYNC_CPU_CLOCK 0 1 selects the independent i_cpu_clk input and asynchronous CPU boundary
frost.sv MEM_SIZE_BYTES 2 ** 18 Low BRAM size (256 KiB); instruction fetch reaches its first 128 KiB (riscv_pkg::LowBramCodeAddrBits)
frost.sv SIM_TIMER_SPEEDUP 1 mtime increment per cycle (simulation)
frost.sv CACHED_BASE 32'h8000_0000 Cached-region base address
riscv_pkg.sv FROST_DDR_CAPACITY_LOG2_BYTES 30 Compile-time DDR aperture size as log2 bytes; 30–37 selects 1–128 GiB and derives the physical and AXI-offset widths
frost.sv CACHED_SIZE_BYTES riscv_pkg::DdrCapacityBytes Cached-region aperture; keep equal to the package setting so PMA, caches, DMA and AXI agree
frost.sv ENABLE_CACHED_TIER 0 1 builds the cache hierarchy; simulation sets it with -G, and boards with a DDR controller pass 1
frost.sv L1_CACHE_BYTES / L1I_CACHE_BYTES / L2_CACHE_BYTES 128 KiB / 16 KiB / 2 MiB L1D, L1I, and L2 sizes
frost.sv L2_NUM_MSHR 8 Fills in the L2 coherence home, 1 to 16; a prefetch leaves a quarter of them for demand misses
frost.sv L2_PREFETCH 1 1 builds the coherence home's prefetch agent (coherence_prefetch_agent): Prefetch requests for the lines ahead of the hart's ascending data and instruction streams
frost.sv L2_PREFETCH_DISTANCE / L2_PREFETCH_INFLIGHT 8 / 3 Lines read ahead of a stream, within its 4 KiB page, and the data requests in flight, 1 to 3, beside one instruction request
frost.sv USE_BEHAVIORAL_DDR 1 1 ends the tier in the simulation DDR model; 0 exports the bridge's AXI master on o_ddr_axi_*
frost.sv DDR_MODEL_BYTES / DDR_MODEL_LATENCY 64 MiB / 80 DDR model size and access latency in cycles (simulation)
frost.sv DDR_MODEL_LATENCY_JITTER / DDR_MODEL_REORDER 0 / 0 DDR model per-transaction latency jitter, and out-of-order completion across ids (simulation); FROST_DDR_MODEL_SEED draws these and the latency for a test run (tests/README.md)
frost.sv SIM_FAST_MAINT 0 Simulation only: 1 clears coherent-array tags, states and replacement bits in one cycle and bulk-clears the L1I tag and replacement RAMs on reset and every invalidate-all; 0 keeps the per-set reset sweep. L1I invalidate-all clears valid flip-flops in one cycle in either mode
frost.sv FETCH_VALID_FUZZ 0 Simulation only: 1 delays local instruction AXI responses to exercise variable fetch latency
frost.sv L1D_NUM_MSHR 8 L1D request endpoints, 1 to 8: one for stores, LR and atomics, the rest for load misses in flight
frost.sv PERF_COUNTERS 0 1 builds the mperf* profiling counters
frost.sv VECTOR / VLEN 0 / 256 1 builds the vector state: mstatus.VS and the vector CSRs; VLEN is the vector register width, 128, 256 or 512 bits (CPU README)
frost.sv VECTOR_ADVERTISE 0 1 would set misa.V; elaboration rejects it while the vector instructions are not implemented, and software enables the vector state through mstatus.VS
frost.sv MISALIGNED_HW 0 Enables hardware completion of plain misaligned loads and stores to cached DDR. Requires ENABLE_CACHED_TIER. The X3, VCU118 and simulation defaults enable it (CPU README)
frost.sv DEBUG_JTAG_TAP 1 1 uses the generic TAP on i_jtag_*; 0 takes the BSCAN bundle from the board
frost.sv RAW_LOOPBACK 1 1 builds the NIC's raw TX-to-RX loopback, which needs one clock on both MAC clock ports; 0 for a transceiver's independent clocks
frost.sv ENABLE_1G_ETH 0 1 instantiates the secondary 1 Gb/s GMII NIC (nic_engine + nic_mac_1g) at 0x4002_2000 (VCU118); 0 omits it
frost.sv EXT_DMA_PORTS / EXT_DMA_ID_BITS 0 / 3 Number and ID width of optional external 256-bit coherent AXI4 DMA slave ports, each behind an axi_register_slice (AXI integration guide)
frost.sv EXTERNAL_MAC 0 1 omits nic_mac_10g and exports the primary nic_engine's core-clock AXI4-Stream TX/RX and MAC sideband ports
frost.sv EXT_AXIL_WINDOW 0 1 exposes a 16 KiB 64-bit AXI4-Lite master window at 0x4002_4000–0x4002_7FFF behind an axil_register_slice
cpu_ooo.sv MMIO_ADDR 32'h4000_0000 (riscv_pkg::MmioWindowAddr) MMIO window base; the UART RX data and FIFO pop registers are fixed offsets from it

The compile-time aperture is an address-transport limit, not a claim that a board has that much installed DRAM. Bare-metal links retain a safe 1 GiB usable-DRAM default and accept FROST_DDR_USABLE_LOG2_BYTES=30..37 in sw/common/common.mk; set it no larger than the installed memory and the RTL aperture. Linux obtains its usable range from the generated device tree's /memory node (frost_boot_image.py --mem-size), whose 64-bit cells support the same 1–128 GiB matrix. The boot loader must supply the installed size; neither the CPU PA width nor the 1 GiB default identifies a DIMM's capacity.

License

Copyright 2026 Two Sigma Open Source, LLC

Licensed under the Apache License, Version 2.0.