Write for
the fold.
The Hotfloor SDK tells you what the fold engine did to every page in your resident set, fails your build when the set will not fit the target deck, and runs the NITROBENCH 4 harness we publish our own figures with.
01The CLI
Six commands
| Command | What it does |
|---|---|
nitro bench | Runs the NITROBENCH 4 profile set and writes a signed result file. |
nitro budget | Static block-budget check. Fails your build if a warez set cannot fit the target deck. |
nitro fold --explain | Prints why each page folded or did not. Read it before tuning a resident set. |
nitro trace --floor | Measures what your build emits at idle, in counts per minute. |
nitro evict --replay | Replays a captured eviction trace against another generation. Works back to G2. |
nitro sign | Signs a profile for distribution. Keys are yours; we never see them. |
02The budget linter
Put it in your build
nitro budget reads a resident set, folds it statically against a target deck’s fold table, and returns non-zero if the set will not fit. Without it, an overrun shows up mid-run on the customer’s deck, while their trace is climbing.
The static fold is conservative by design: it counts a page as folded only when it can prove the match, so the number it gives you is a floor. Real residency is usually two to five per cent better.
Target every deck you claim to support, including the nx5-s. Sixteen blocks is where sets break, and it is the deck most of your users will be learning on.
$ nitro budget --target nx5-s --set ./sweep.set --strict reading 17 residents … 16 blocks available fold candidates 3,902 pages folded (proven) 2,118 pages (54.3%) resident cost 17.8 blocks of 16 FAIL E-BLK-12 over by 1.8 blocks largest resident sweep/sentry-b 4.1 blocks suggestion --target nx5-t, or split sweeper $ echo $? 12
03The fold explainer
$ nitro fold --explain --set ./ward.set --target nx5-x
ward/barrier-a pages 612
folded 588 shared with barrier-b, barrier-c
refused 18 alignment (pad to 64 B) E-FLD-04
refused 6 unique
ward/wrap-1 pages 344
folded 120 shared with wrap-2
refused 224 unique — constant table is per-instance
set ratio 1.68x (deck ceiling 1.72x)
hint hoist wrap-1/table to a shared segment: +0.09xEvery refusal has a reason
Every refusal comes with its reason. Most of them are one of two things: a segment that is not 64-byte aligned, or a constant table that has been written per-instance when it could have been hoisted into a shared segment. Both are cheap to fix and both are worth blocks.
Tuning a set from the ratio alone takes an afternoon of guessing. Reading the refusals takes about ten minutes.
A set of genuinely unique residents folds to about 1.08× and there is nothing the tool or the deck can do about that. In that case the explainer says so and does not suggest a micro-optimisation.
04The benchmark harness
The same one we publish with
nitro bench is NITROBENCH 4 in full: the harness, all forty-one profiles, and the signed run files behind every figure on our benchmarks page.
Run it against our hardware or anyone else’s. Run files are signed, so if your numbers disagree with ours we can compare them profile by profile.
Results go to a signed file on your machine and nothing is uploaded. There is no telemetry in the SDK, no phone-home in the runtime and no account to create.
$ nitro bench --profile 12 --runs 12 --out ./run.nbr deck NX5/X firmware 4.1.2 profile 12 mixed set, 19 residents ambient 23.8 C enclosure closed warm-up 5 min (excluded) run 01 1,182 MB/s … run 12 1,176 MB/s median 1,180 MB/s spread 1,169–1,188 fold ratio 1.72x signed ./run.nbr
05ABI and deprecation
What we promise
- ABI supported
- current + previous minor
- Deprecation notice
- two minors, min. 9 months
- Profile format stability
- frozen since 3.0
- Replay compatibility
- back to G2
- Changelog
- day of release
- Signing keys
- yours, never ours
We ship a generation roughly every 9 months. That is hard on anyone maintaining a build, so the ABI moves slower than the silicon: five generations have produced two breaking ABI changes, both announced two minors ahead.
Targets and their windows
| Gen | Deck | Blocks | Fold | Build target |
|---|---|---|---|---|
| G1 | NX1 | 12 | 1.12× | replay only |
| G2 | NX2 | 16 | 1.19× | replay, no new builds |
| G3 | NX3 | 20 | 1.33× | replay, no new builds |
| G4 | NX4 | 24 | 1.46× | supported |
| G5 | NX5 | 24 | 1.72× | supported |
06Error codes
Every code we emit
| Code | Meaning | What to do |
|---|---|---|
E-BLK-12 | Block budget exceeded at link time | Run nitro budget --target and cut the largest resident. |
E-FLD-04 | Fold table rejected a page: alignment | Pad the segment to 64 B. The linter warns about this. |
E-FLD-19 | Fold ratio fell below the declared floor | Your set is pathologically unique. Declare a lower floor or accept the blocks. |
E-EVT-07 | Eviction predictor starved of history | Expected on a cold jack. Ignore for the first 90 s. |
E-TRC-02 | Trace floor above the profile ceiling | A resident is chattering. nitro trace --floor --per-resident. |
E-ABI-01 | Profile built against an unsupported ABI | Rebuild. We support the current and previous minor, nothing older. |
The SDK is distributed as a signed archive through your yard’s supply desk alongside firmware, or from any deck’s service bus. It sends nothing back to us. There is no developer account and nowhere to give an email address.