kernbench2/docs/adr/ADR-0010-cli-device-selection.md

ADR-0010: CLI Device Selection and Multi-Device Execution Semantics

Status

Accepted

Context

Benchmarks represent device-agnostic workloads that operate on a single device. Users may want to run a benchmark:

• on a specific device, or
• across all devices in the system.

Device enumeration must not leak into benchmarks or runtime APIs.

---

Decision

D1. Benchmarks are single-device by design

• A benchmark MUST define behavior for a single device only.
• A benchmark MUST accept a device identifier as input.
• Benchmarks MUST NOT enumerate or loop over multiple devices.

---

D2. CLI controls device selection

The kernbench run command supports an optional --device argument:

• If --device <id> is specified:

  • the benchmark executes once for the specified device.

• If --device is omitted:

  • the benchmark executes once using all the SIPs discovered in the topology.

---

D3. Multi-device execution is logically parallel

When running on multiple devices:

• benchmark executions are submitted to a single simulation engine instance,
• executions are logically parallel in simulation time,
• inter-device contention is naturally modeled.

---

D4. Runtime API and simulation engine remain device-scoped

• Runtime API calls operate on one device per invocation.
• The simulation engine schedules all requests deterministically.
• Neither layer enumerates devices.

---

Links

• SPEC R7, R8
• ADR-0007 (Runtime API boundaries)