Open
Conversation
Hubris I2C stress testing requires sending looping HIF programs to targets via the hiffy task. Today, each humility subcommand (i2c, pmbus, etc.) manually constructs Op sequences in Rust, making it difficult to script test programs from external tools. This crate introduces a text-based language for HIF programs with syntactic sugar for common operations and an assembler that resolves symbolic names against a Hubris archive. The assembler validates programs against target buffer sizes and embeds the archive's image ID in the output bundle so the runner can reject mismatched uploads. Key pieces: - Text parser with syntactic sugar for i2c_read/write, idol calls, repeat loops, sleep, bus scan, and raw op blocks - Single-pass assembler lowering to hif::Op bytecode - Idol call lowering with scalar argument encoding - TargetConfig: serializable intermediate form capturing buses, devices, muxes, sensors, HIF functions (with typed args and error codes), Idol interfaces, and buffer sizes - Archive loader extracting TargetConfig from DWARF debug info - Result decoder for postcard-encoded HIFFY_RSTACK output - Verify mode reporting program fit and resource estimates - Pre-generated JSON fixtures for gimlet-c and cosmo-b - 9 annotated example programs covering common test patterns - 59 tests (47 unit, 12 fixture-based)
Programs can now be executed on SP devices via `humility hiffy --exec program.hif`. The assembler produces the HIF bytecode; humility's HiffyContext handles execution and result retrieval. Results are fully decoded using DWARF type info — Idol calls show struct-level output identical to `humility hiffy -c`. Tested on grapefruit (probe) and sidecar (network via NetHiffy): I2C temperature reads, fan controller reads, multi-bus operations, SpRot Idol calls, and sensor polling — 230 operations across 5 test programs with zero errors. Key changes: - Generic `call` statement for invoking any HIF function by name, eliminating the need for per-function sugar - Fixed repeat loop counter pattern to match humility cmd/i2c (increment toward limit, not decrement) - Idol reply sizes computed from DWARF during archive extraction - `humility hiffy --exec` with full result decoding, JSON output, and --save-bundle for CI artifacts - Assembly-time program stats (transactions, bytes, mux switches) - ProgramBuilder API for Rust-driven program generation - Archive validation: checks for hiffy task and net feature - Sidecar and grapefruit fixtures; gimlet/cosmo regenerated
The hiffy command now supports offline operations that don't require a target connection. --verify shows program stats and disassembled ops. --assemble produces a .hifb bundle file. Existing online operations (--exec, --call, -L) detect the need for a target and attach on demand. Changed hiffy's CommandKind from Attached to Unattached so offline operations bypass target attachment. Online operations give a clear error if no probe or IP is specified. Added 10 equivalent .hif examples that reproduce humility's hardcoded HIF programs (qspi, i2c, gpio, hash, idol, validate) and 18 tests covering both text and ProgramBuilder assembly. Fixed block comment style to match the project convention.
I2C operations now accept device names from the archive's topology
in place of hex addresses (e.g. `i2c_read mid sbtsi reg=0x01 2`).
Names are resolved case-insensitively against the TargetConfig.
Numeric addresses still work.
The --verify disassembly now emits raw assembler syntax with
postcard byte encoding in comments and resolved function names.
The output is valid `raw {}` block syntax.
Updated existing tests and one example to exercise both named
and numeric address forms.
The --verify disassembly now annotates ops with their role in context: I2C parameters are labeled with bus and device names resolved from the archive. Idol Send calls show the task name and op_code. Loop patterns are identified (loop_start, counter, limit). Updated README and lib.rs docs with annotated examples.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add a HIF assembler crate and extend
humility hiffywith--exec,--verify, and--assemblecommands for writing, assembling, andexecuting HIF programs loaded from text (
*.hif) or pre-assembled(
*.hifb) files.This PR was prompted by a need to do high-frequency I2C stress testing
and the desire to incorporate those tests into HWCI workflows.
Previously, HIF programs were hand-coded within the
humilitysource code. Being able to create HIF programs outside of
humilityenables a faster way to write ad hoc tests and distribute them outside of
a humility release. This is especially useful for HW-based CI testing
where a HIF test can be decoupled from a
humilityrelease.humility-hif-assemblercrate: parses a text language withsyntactic sugar for:
Anything symbolic and reply sizes are resolved against the given Hubris
archive's DWARF information. I2C devices can be referenced by part
name (e.g.
i2c_read mid sbtsi reg=0x01 2) instead of hex address.A
ProgramBuilderAPI exists for Rust-driven program generation andassembly-time stats computation.
humility hiffysubcommand extensions:--exec program.hifassembles and runs a program on a target,with result decoding (Idol results get struct-level decode
via DWARF, same as
humility hiffy -c)--verify program.hifchecks a program offline (no target needed),shows stats and annotated disassembly with hex byte encoding,
resolved function names, and I2C/Idol symbolic context
--assemble program.hif --bundle-output program.hifbproduces abundle file for CI artifacts
--jsonoutput for scriptingRFD 659
In trying to stay out of the way of any work-in-progress for RFD 659,
this crate intentionally overlaps with parts of
humility-hiffy:The overlap exists in part, because
humility-hiffyis coupled to a livetarget connection and cannot be used for offline assembly or scripted
test generation. The assembler uses only public
HubrisArchiveAPIs.When RFD 659 work lands, or as part of that work,
TargetConfigand
HifAssemblerare candidates for replacing the ad-hoc archiveintrospection and per-command Op construction used across humility's
subcommands.
Pre-existing HIF programs are left as is. Many of them are just
one-liners, but all are duplicated in the tests in order to ensure
compatibility.
Testing
Tested on hardware: grapefruit (probe) and sidecar (network via NetHiffy):
There are Fixture tests, unit tests, and duplication of existing HIF
programs.
Fixture tests use checked-in JSON snapshots of the archived-derived
information from gimlet-c, cosmo-b, sidecar-b, and grapefruit archives.
Verified that all existing
humility hiffymodes (-l, -L, -c) still workwith the CommandKind change to Unattached. The affected cargo tests that
match program output are updated.
Future Hubris changes
Several Hubris-side changes would improve what HIF stress tests can do.
Stress tests run many Ops that are successful but where returning
results uses up the
rstackwhich limits the total number of Ops that the HIFprogram can execute. However, failures are very interesting and those results
probably need to be returned along with overall stats.
Suggestions for some helpful HIF engine features:
markandpopfor rstack:thousands of iterations instead of ~250. A result filter callback in
hif::execute()would be ~5 lines.rstack-markandrstack-pop-to-markPseudoOpsthat allow conditional popping of rstack contents.
PushResult,PushResultByte,ResetResult) that let the program inspecta function's return value and decide whether to record it.
This turns hiffy into a programmable instrument.
GetTicksandReadCycleCountHIFfunctions for measuring per-operation timing on-target.
an addressability check (currently rejected with
BadArg).Assuming this PR gets merged, a Hubris issue will be written for the HIF
enhancements.