Skip to main content

max / everycycle

7.7 KB · 214 lines History Blame Raw
1 //! Per-device measured capability.
2 //!
3 //! The same struct is the scheduler's routing input and the appraisal
4 //! report's payload. Every field is *measured on this card during this
5 //! probe run*; none is looked up from a SKU table. A card with no
6 //! recognizable identity is appraised on its probes alone.
7
8 /// A numeric regime the device executes matrix or vector ops in.
9 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
10 pub enum Precision {
11 Fp32,
12 Tf32,
13 Fp16,
14 Bf16,
15 Fp8E4M3,
16 Fp8E5M2,
17 Int8,
18 Int4,
19 }
20
21 /// Sustained throughput at one precision, after thermal steady state.
22 /// Peak / burst numbers do not belong here.
23 #[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
24 pub struct PrecisionThroughput {
25 pub precision: Precision,
26 /// Tera-ops per second observed during the probe window.
27 pub tops: f64,
28 /// True if the figure came from the device's matrix engine (tensor
29 /// cores, MFMA, AMX, ANE, Vulkan cooperative-matrix). False means
30 /// vector ALUs only — the honest fallback when no matrix path was
31 /// reachable.
32 pub matrix_engine: bool,
33 }
34
35 /// Memory subsystem capability.
36 #[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
37 pub struct Memory {
38 /// Bytes physically present on the device.
39 pub physical_bytes: u64,
40 /// Bytes the runtime can actually allocate after driver and OS
41 /// reservation and a fragmentation budget. This is the figure the
42 /// scheduler routes on.
43 pub usable_bytes: u64,
44 pub bandwidth_read_bps: f64,
45 pub bandwidth_write_bps: f64,
46 /// Errors observed during the integrity probe — ECC-reported on
47 /// cards that expose ECC, memtest-detected otherwise.
48 pub errors_observed: u64,
49 }
50
51 /// Bandwidth to host and to peer devices.
52 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
53 pub struct Interconnect {
54 /// Measured host bandwidth (PCIe) in bytes/sec.
55 pub host_bps: f64,
56 /// Full pairwise peer measurements, directed. One entry per ordered
57 /// pair (this -> peer). Empty when no peer was reachable. Link kind
58 /// is deliberately not recorded; that would be classification, and
59 /// the report stays purely measured.
60 pub peers: Vec<PeerLink>,
61 }
62
63 /// One directed peer-bandwidth measurement.
64 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
65 pub struct PeerLink {
66 /// Bus address of the peer device. Identity only; not interpreted.
67 pub peer_bus_address: String,
68 /// Sustained bandwidth in bytes/sec from this device to the peer.
69 pub bps: f64,
70 }
71
72 /// Cost of issuing work to the device.
73 #[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
74 pub struct LaunchOverhead {
75 pub null_launch_ns: f64,
76 pub memcpy_1mib_ns: f64,
77 }
78
79 /// Thermal envelope under sustained matrix-engine load.
80 #[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
81 pub struct ThermalEnvelope {
82 /// Seconds from cold start to the first observed clock throttle.
83 /// `None` means the probe ran to completion without throttling at
84 /// its load level.
85 pub time_to_throttle_s: Option<f64>,
86 /// Throttled sustained throughput as a fraction of cold throughput
87 /// at the same precision. `1.0` means no observable thermal derate.
88 pub throttled_ratio: f64,
89 pub sustained_power_w: f64,
90 }
91
92 /// Identity bound into the signed report for anti-fraud only.
93 ///
94 /// These fields anchor "this is the same physical card across time."
95 /// They are never input to scoring or routing. No SKU table is consulted.
96 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
97 pub struct DeviceIdentity {
98 pub bus_address: String,
99 /// Vendor:device:subsystem IDs joined with ':'. Informational.
100 pub pci_ids: String,
101 /// VBIOS / firmware hash where readable.
102 pub vbios_hash: Option<[u8; 32]>,
103 /// Manufacturer serial where exposed. Many consumer cards omit it.
104 pub serial: Option<String>,
105 }
106
107 /// Conditions under which a probe was run.
108 ///
109 /// Two reports are only directly comparable if their environments agree
110 /// — driver version and ambient temperature both move the numbers.
111 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
112 pub struct ProbeEnvironment {
113 pub driver_version: String,
114 pub ambient_c: f32,
115 pub duration_s: f64,
116 pub probe_version: String,
117 }
118
119 /// Per-device measured capability. Scheduler input and report payload.
120 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
121 pub struct CapabilityVector {
122 pub identity: DeviceIdentity,
123 pub environment: ProbeEnvironment,
124 pub throughput: Vec<PrecisionThroughput>,
125 pub memory: Memory,
126 pub interconnect: Interconnect,
127 pub launch: LaunchOverhead,
128 pub thermal: ThermalEnvelope,
129 }
130
131 /// Signed envelope for one card's appraisal report.
132 ///
133 /// The unit of transfer. Each card gets one of these; a fleet is a
134 /// directory of them plus the box report they all reference.
135 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
136 pub struct CardReport {
137 pub payload: CardReportPayload,
138 pub signature: Signature,
139 }
140
141 /// The payload signed inside a `CardReport`.
142 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
143 pub struct CardReportPayload {
144 /// Format version of the envelope itself. Currently "1".
145 pub report_version: String,
146 /// RFC 3339 timestamp at probe start.
147 pub probed_at: String,
148 /// Hex-encoded SHA-256 of the canonical box-report payload bytes.
149 /// Links this card report to the topology context it was measured in.
150 pub box_report: String,
151 pub capability: CapabilityVector,
152 }
153
154 /// Signed envelope for a probe run's box-level context.
155 ///
156 /// The box report carries the topology the cards were measured in.
157 /// Card reports reference it by content hash, so anomalies in peer
158 /// measurements can be traced back to the run that produced them.
159 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
160 pub struct BoxReport {
161 pub payload: BoxReportPayload,
162 pub signature: Signature,
163 }
164
165 /// The payload signed inside a `BoxReport`.
166 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
167 pub struct BoxReportPayload {
168 pub report_version: String,
169 pub probed_at: String,
170 pub host: HostIdentity,
171 /// Bus addresses of every device present at probe time. Lets peer
172 /// references in card reports resolve to something concrete.
173 pub present_devices: Vec<String>,
174 /// Per-device driver version bound at probe time.
175 pub driver_versions: Vec<DriverBinding>,
176 pub ambient_c: f32,
177 pub probe_suite_version: String,
178 }
179
180 /// Identity of the host the probe ran on. Metadata only; never input
181 /// to scoring.
182 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
183 pub struct HostIdentity {
184 pub hostname: String,
185 /// DMI / SMBIOS system identifier where available.
186 pub dmi_string: Option<String>,
187 /// CPU model string. Informational; not looked up.
188 pub cpu_model: String,
189 }
190
191 /// Driver version bound to one device at probe time.
192 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
193 pub struct DriverBinding {
194 pub bus_address: String,
195 pub driver_version: String,
196 }
197
198 /// Per-tenant Ed25519 signature over a canonical payload encoding.
199 ///
200 /// The canonical encoding rule (stable key order, UTF-8, no
201 /// insignificant whitespace) lives with the writer/verifier code, not
202 /// in this schema crate.
203 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
204 pub struct Signature {
205 /// Algorithm identifier. Currently "ed25519".
206 pub alg: String,
207 /// Operator-chosen identity string for the signing key.
208 pub tenant_identity: String,
209 /// Base64-encoded Ed25519 public key.
210 pub tenant_pubkey: String,
211 /// Base64-encoded signature over the canonical payload bytes.
212 pub sig: String,
213 }
214