code wiki / _hdl_build / nx_cost_oracle.nx
`nx_cost_oracle.nx` source

1// nx_cost_oracle.nx -- compare declared counted costs, not elapsed-time performance.
2// Retired instructions, switching events and bytes can be reproducible under a matched
3// workload and measurement model. Their metric IDs alone do not establish reproducibility,
4// workload equivalence, hardware portability, energy consumption or lower observed latency.
5// This API has no timing/sampling contract and therefore continues to reject wall-clock
6// inputs. A measured timing comparison belongs in an explicitly sampled contract.
7// license_tier: ORIGINAL
8import "nx_syscalls.nx"
9
10const CO_WALLCLOCK: i64 = 0
11const CO_INSN: i64 = 1
12const CO_TOGGLES: i64 = 2
13const CO_BYTES: i64 = 3
14const CO_REJECT: i64 = 0 - 1
15const CO_TIE: i64 = 0
16// Legacy result IDs retained. FASTER means lower counted cost in THIS API, not latency proof.
17const CO_A_FASTER: i64 = 1
18const CO_B_FASTER: i64 = 2
19const CO_I64_MAX: i64 = 9223372036854775807
20
21// Compatibility name: reports whether the kind is admitted by this counted-cost contract.
22// Actual reproducibility must be measured; an unknown kind never inherits admission.
23func co_metric_deterministic(kind: i64) -> i64 {
24    if kind == CO_INSN { return 1 }
25    if kind == CO_TOGGLES { return 1 }
26    if kind == CO_BYTES { return 1 }
27    return 0
28}
29
30// Equality of supplied samples. A singleton is trivially equal, not repeated-run evidence.
31// An empty/invalid sample set cannot establish equality of observed measurements.
32func co_reproducible(samples: *i64, n: i64) -> i64 {
33    if n <= 0 { return 0 }
34    if (samples as i64) == 0 { return 0 }
35    var i: i64 = 1
36    while i < n { if samples[i] != samples[0] { return 0 } i = i + 1 }
37    return 1
38}
39
40// Preserve this public helper; signed minimum has no positive i64 representation.
41func co_abs(x: i64) -> i64 {
42    if x == 0 - CO_I64_MAX - 1 { return CO_REJECT }
43    if x < 0 { return 0 - x }
44    return x
45}
46
47// Lower cost wins only when a NONZERO difference meets the caller-supplied margin.
48// Subtract smaller from larger after validating nonnegative inputs: the difference is
49// representable without an overflowing subtraction or an unrepresentable absolute value.
50func co_fair_verdict(kind: i64, cost_a: i64, cost_b: i64, margin: i64) -> i64 {
51    if co_metric_deterministic(kind) == 0 { return CO_REJECT }
52    if cost_a < 0 { return CO_REJECT }
53    if cost_b < 0 { return CO_REJECT }
54    if margin < 0 { return CO_REJECT }
55    if cost_a == cost_b { return CO_TIE }
56    if cost_a < cost_b {
57        if cost_b - cost_a < margin { return CO_TIE }
58        return CO_A_FASTER
59    }
60    if cost_a - cost_b < margin { return CO_TIE }
61    return CO_B_FASTER
62}
63
64// Reports observed rank reversals only. Reversal alone does not establish bias,
65// statistical significance, emulator fault or that a timed comparison is invalid.
66func co_wallclock_flips(a_samples: *i64, b_samples: *i64, n: i64) -> i64 {
67    if n <= 1 { return 0 }
68    if (a_samples as i64) == 0 { return 0 }
69    if (b_samples as i64) == 0 { return 0 }
70    var a_ahead: i64 = 0
71    var b_ahead: i64 = 0
72    var i: i64 = 0
73    while i < n {
74        if a_samples[i] < b_samples[i] { a_ahead = 1 }
75        if b_samples[i] < a_samples[i] { b_ahead = 1 }
76        i = i + 1
77    }
78    if a_ahead == 1 { if b_ahead == 1 { return 1 } }
79    return 0
80}
nx_cost_oracle.nx source

`nx_cost_oracle.nx` source
