Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

GWR Platform

gwr_platform is the library used to define and build execution platforms from configuration files.

A platform in GWR is the structural description of the machine that a workload runs on. It brings together named processing elements, memories, caches, fabrics, and the connections between them into one validated object.

What It Provides

The gwr_platform library provides:

  • YAML configuration file support.
  • build functions that construct memories, processing elements, caches, and fabrics via the gwr_platform::builder module.
  • connection functions that wire a platform together via the gwr_platform::connect module.

Coherent Caches

A cache can select directory endpoints with coherency_managers: [cm0, cm1]. Each entry in the top-level coherency_managers section names a backing memory_map and a config.line_size_bytes. Set the optional positive config.operations_per_tick to limit directory processing; omitting it leaves processing unlimited. Incoming packets, queued request starts, and barrier completions share that budget. For example:

coherency_managers:
  - name: cm0
    memory_map: backing_memory
    config:
      line_size_bytes: 32
      operations_per_tick: 1

Connect the directory endpoint coherency_manager.cm0 to a fabric port, and connect the cache’s memory side to the fabric. Device routes are derived from these connections.

Every selected manager must have the same positive line size as its cache. Memory ranges must align to that size, and each physical memory can belong to only one manager. Matching sizes need not be powers of two. The selected managers must cover the connected processing element’s memory map.

Coherent caches retain max_inflight_parents and max_inflight_fills (both default to 64). The child bound includes read fills and exclusive acquisitions; large requests stream through it. Dirty writebacks and invalidation acks share one ordered control path. Barriers drain prior work without flushing resident dirty lines. Hierarchical coherence is unsupported and rejected in platform configuration.

The coherent examples demonstrate one and two managers. gen-fabric accepts --use-coherency-managers with L1 caches and no L2 cache.

A Simple Platform

An example of a simple platform could include:

  • a processing element
  • an L1 cache
  • a backing memory
  • a memory map describing what memory the PE can address

For example:

use gwr_engine::engine::Engine;
use gwr_platform::Platform;
fn main() {
let mut engine = Engine::default();
let clock = engine.default_clock();
let _ = Platform::from_string(&engine, &clock, "
memory_maps:
  - name: pe_memory_map
    devices:
      - mem0

processing_elements:
  - name: pe0
    memory_map: pe_memory_map
    config:
      lsu_access_bytes: 32
      sram_bytes: 64KiB

caches:
  - name: l1_0
    config:
      bw_bytes_per_tick: 32
      line_size_bytes: 32
      delay_ticks: 4

memories:
  - name: mem0
    kind: ddr
    base_address: 0x1_0000_0000
    config:
      capacity_bytes: 1GiB
      delay_ticks: 40

connections:
  - connect:
      - pe.pe0
      - cache.l1_0.dev
  - connect:
      - cache.l1_0.mem
      - mem.mem0
").unwrap_or_else(|err| panic!("failed to validate: {err}"));
}

Each memory in a processing element’s memory map must have a base address and capacity that are multiples of that PE’s lsu_access_bytes (32 by default). This keeps each aligned LSU access entirely within one mapped memory region. When PEs share a memory map, its memories must satisfy every PE’s access size.

Connect an unused fabric endpoint to null so its ingress and egress ports are deliberately left idle without causing an unconnected-port error when the simulator starts. For example: connect: ['null', "fabric.fabric0@(11,16)"]. Cache device and memory ports can also connect to null; processing elements and memories cannot. Quote null in YAML so it is parsed as a string. See gwr-platform/examples/platform_null_connection.yaml for a complete configuration.

Example

Load a platform from YAML and inspect the resulting structure:

use std::path::Path;
use std::rc::Rc;

use gwr_engine::engine::Engine;
use gwr_platform::Platform;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut engine = Engine::default();
    let clock = engine.default_clock();

    let platform = Rc::new(Platform::from_file(
        &engine,
        &clock,
        Path::new("gwr-platform/examples/simple_pe_cache_mem.yaml"),
    )?);

    println!("Platform has {} processing elements", platform.num_pes());
    println!("{platform}");
    Ok(())
}