Profiles and Pipelines

Profile structure

A timing profile is versioned JSON:

{
  "name": "my-profile",
  "version": "1.0.0",
  "description": "Purpose and target of this profile",
  "components": {
    "example-link": {
      "fixed_latency_ns": 50.0,
      "bandwidth_gbps": 100.0,
      "packet_rate_mpps": 148.8,
      "lanes": 1,
      "resource_mode": "overlap",
      "evidence": "analytic",
      "notes": "State the source of every value."
    }
  }
}

Unknown component fields are rejected. Each component key becomes its unique name.

Component fields

Field	Type	Meaning
fixed_latency_ns	non-negative number	Cost paid by every visit
instruction_rate_mips	positive number or null	Million guest instructions per second
clock_mhz	positive number or null	Component cycles per microsecond
bandwidth_gbps	positive number or null	Transfer bit rate
packet_rate_mpps	positive number or null	Million packets per second
compute_tops	positive number or null	Trillion operations per second
lanes	positive integer	Parallel service lanes
resource_mode	overlap or serial	Combine active dynamic terms by maximum or sum
evidence	analytic or calibrated	Result class
target	string or null	Required for calibrated components
calibration_scale	positive number	Fitted (\alpha)
calibration_offset_ns	finite number	Fitted (\beta)
uncertainty_pct	non-negative number or null	Declared uncertainty, when justified
notes	string	Source, assumptions, and use limits

Work dimensions

A pipeline stage can request:

Work field	Use
instructions	Guest CPU work under an instruction-rate profile
cycles	Device, memory, or accelerator architectural cycles
bytes	PCIe, link, memory, DMA, or bus transfer
packets	Packet-rate-limited NIC or switch work
operations	Accelerator arithmetic

All work values are finite and non-negative. If a stage requests a dimension for which its component has no rate, simulation fails. This prevents accidental zero-cost work.

Overlap versus serial

For overlap, active dynamic costs compete and the slowest wins:

[ t=t_0+\max(t_I,t_C,t_B,t_P,t_O). ]

Use this for a resource where throughput is bounded by either packet rate or byte rate, or where compute and memory can overlap.

For serial, active costs add:

[ t=t_0+t_I+t_C+t_B+t_P+t_O. ]

Use this when each requested resource is a distinct sequential phase. If the phases need separate queues or lane counts, model them as separate pipeline stages instead.

Lanes

lanes is the number of jobs a component can serve in parallel. Each lane has an independent availability timestamp. A new event chooses:

1. the earliest available lane;
2. the lowest lane number when availability ties.

This is deterministic and work-conserving. It does not model priorities or pre-emption.

Pipeline structure

{
  "stages": [
    {
      "name": "guest-submit",
      "component": "guest-cpu-icount-shift0",
      "work": {"instructions": 2500}
    },
    {
      "name": "nic-tx",
      "component": "cnuasnic",
      "work": {"bytes": 4096, "packets": 4}
    },
    {
      "name": "gpu-kernel",
      "component": "cnuasgpu-compute",
      "work": {"operations": 1048576}
    }
  ]
}

Stages execute in listed order for each job. Different jobs overlap whenever their required component lanes are available.

Reference profile assumptions

cnuas-analytic-v0.json includes both protocol-derived values and illustrative values:

Component	Basis
guest-cpu-icount-shift0	QEMU shift 0, one ns per instruction
pcie-gen5-x16	32 GT/s by 16 lanes after 128b/130b encoding, before packet overhead
bmc-rs485	19,200 baud with ten serial bits per eight-bit byte
Other bandwidths and latencies	Explicit analytic assumptions in notes

Copy the profile before changing it. Give the new profile a new name and version, preserve the source of each value in notes, and do not change evidence to calibrated without a named target and held-out error report.