flatbuffer base

flatbuffers/config/clock.fbs

@@ -0,0 +1,16 @@
+namespace hmmmm.config;
+
+// Global emulator clock constraints.
+table ClockConfig {
+    // Maximum emulated ticks per real second.
+    // 0 = unlimited (run as fast as possible).
+    limiter: uint64;
+}
+
+// Clock source and frequency relationship for one device.
+// Devices form a clock tree: each node derives its frequency from its src.
+table DeviceClockConfig {
+    src:        string;         // id of the parent device; empty = root clock
+    divider:    uint32 = 1;
+    multiplier: uint32 = 1;
+}

flatbuffers/config/config.fbs

@@ -0,0 +1,20 @@
+include "device.fbs";
+include "mem_config.fbs";
+include "clock.fbs";
+
+namespace hmmmm.config;
+
+// Top-level emulator / system configuration.
+// Equivalent to glob.toml — describes a full composite device tree.
+//
+// File use:  flatcc -a config/config.fbs  →  binary system config files
+// WS use:    embed in ConfigCtrlMessage when config-change protocol is ready
+table SystemConfig {
+    devices:     [DeviceEntry];  // ordered list; id must be unique
+    clock:       ClockConfig;
+    projections: [Projection];
+    intercepts:  [Intercept];
+    mem_setup:   [MemSetup];
+}
+
+root_type SystemConfig;

flatbuffers/config/device.fbs

@@ -0,0 +1,39 @@
+include "mem_config.fbs";
+include "clock.fbs";
+
+namespace hmmmm.config;
+
+// Configuration for a single base device (leaf node in the device tree).
+// Equivalent to a standalone device TOML (e.g. AVRrc.toml, gpio.toml).
+table BaseDeviceConfig {
+    libpath:      string;
+    mem_segments: [MemSegment];
+}
+
+// Override for one memory segment within a child device.
+// Only fields that need changing from the base config must be set.
+table MemSegOverride {
+    segment:    string;
+    start:      uint32;
+    len:        uint32;
+    word_len:   uint8;
+    executable: bool;
+}
+
+// One device entry in a composite configuration.
+table DeviceEntry {
+    // Local identifier, unique within this composite (e.g. "core", "gpio_a").
+    id: string;
+
+    // Exactly one of config or config_path must be set.
+    // config:      inline base device configuration.
+    // config_path: path to a serialised BaseDeviceConfig FlatBuffer file.
+    config:      BaseDeviceConfig;
+    config_path: string;
+
+    clock:     DeviceClockConfig;
+    overrides: [MemSegOverride];
+}
+
+// Root type when serialising a standalone device config to a binary file.
+root_type BaseDeviceConfig;

flatbuffers/config/mem_config.fbs

@@ -0,0 +1,73 @@
+namespace hmmmm.config;
+
+// Named offset within a segment — symbolic variable for protocol/tool use
+// (e.g. PIN=0, PORT=1, DDR=2 in a GPIO device).
+table NamedOffset {
+    name:   string;
+    offset: uint32;
+}
+
+// A contiguous memory segment within a base device.
+table MemSegment {
+    name:       string;
+    start:      uint32;         // base address in device flat address space
+    len:        uint32;
+    word_len:   uint8 = 1;      // word size in bytes
+    executable: bool  = false;
+    variables:  [NamedOffset];  // optional symbolic offsets within segment
+}
+
+// ── Projections ──────────────────────────────────────────────────────────────
+
+// Maps a segment from one device into the flat address space of another.
+// After projection, accesses to [base_seg + shift .. shift+len) in base_at
+// are transparently forwarded to target_at:target_seg.
+table Projection {
+    base_at:   string;   // device where the projection appears
+    base_seg:  string;   // segment in that device that is the projection window
+    target_at: string;   // device owning the real data
+    target_seg: string;
+    shift:     uint32 = 0;   // offset from base_seg start
+}
+
+// ── Intercepts ───────────────────────────────────────────────────────────────
+
+enum InterceptOp: byte {
+    op_read  = 0,
+    op_write = 1,
+    op_both  = 2,
+}
+
+enum InterceptMode: byte {
+    shadow_copy    = 1,  // duplicate write to point_at:point_addr as well
+    shadow_replace = 2,  // redirect access to point_at:point_addr instead
+    callback       = 3,  // invoke a handler registered by point_at device
+}
+
+table Intercept {
+    name:       string;
+    op:         InterceptOp  = op_both;
+    mode:       InterceptMode = callback;
+    base_at:    string;      // device where the triggering access occurs
+    base_seg:   string;
+    base_addr:  uint32;
+    point_at:   string;      // device that handles/receives the intercept
+    point_seg:  string;
+    point_addr: uint32;
+}
+
+// ── Memory initialisation ─────────────────────────────────────────────────────
+
+enum OverflowBehaviour: byte {
+    overflow_error  = 0,   // abort if file is larger than segment
+    overflow_ignore = 1,   // stop reading at segment end, no error
+    overflow_wrap   = 2,   // wrap around and continue writing from segment start
+}
+
+// Load initial segment contents from a file (e.g. firmware binary, /dev/urandom).
+table MemSetup {
+    device:    string;
+    segment:   string;
+    filepath:  string;
+    overflow:  OverflowBehaviour = overflow_error;
+}