Skip to content

libtopo: add typed property getters mirroring topo_prop_get_* - #18

Merged
smklein merged 1 commit into
mainfrom
libtopo-typed-property-getters
Sep 16, 2026
Merged

smklein merged 1 commit into
mainfrom
libtopo-typed-property-getters

Conversation

@smklein

@smklein smklein commented Sep 15, 2026 •

Copy link
Copy Markdown
Collaborator

Node::property returns a PropValue for callers to pattern-match, which
suits properties of unknown type, but callers that know the type ended up
writing a three-arm match around every read.

  • Node::property_i32 / property_u32 / property_i64 / property_u64 /
    property_f64 / property_string / property_fmri, one per scalar
    topo_prop_get_* function, each returning Result<T, Error>.
  • A missing property surfaces as Error::PropertyNotFound { group, name }
    and a type mismatch as Error::PropertyType { group, name, expected },
    mapped from libtopo's ETOPO_PROP_NOENT / ETOPO_PROP_TYPE. Callers
    typically log the two differently, and the old Error::Topo(String)
    only let them tell the cases apart by message text. Node::property
    reports a missing property the same way; other codes stay Error::Topo.
  • The fixed-size getters share one generic helper whose function-pointer
    parameter ties the Rust out-type to the C getter that writes it.
  • Two private unsafe helpers, adopt_topo_string and adopt_topo_nvlist,
    own the copy-then-topo_hdl_strfree and cast-then-OwnedNvList sequences.
    The new getters and the existing label, resource, asru, fru,
    fmri_parse, fmri_to_string, snapshot uuid, property, and
    property_groups paths all go through them.
  • Array getters are not wrapped; PropValue already covers them.
  • libtopo bumps to 0.2.0, since Error is not non_exhaustive and the new
    variants can break exhaustive matches.

Tested on a Helios 3 host: fmt, clippy -D warnings, and the full test
suite under pfexec all pass.

Fixes #16

@smklein
smklein force-pushed the libtopo-typed-property-getters branch 4 times, most recently from 0a453d5 to c1a9125 Compare September 16, 2026 13:44
Node::property returns a PropValue for callers to pattern-match, which
suits properties of unknown type, but most callers know exactly what
they expect and ended up writing a three-arm match (expected variant,
other variant, error) around every read.

Add Node::property_i32, property_u32, property_i64, property_u64,
property_f64, property_string, and property_fmri, one per scalar
topo_prop_get_* function. Each returns Result<T, Error>. The fixed-size
getters share one generic helper whose function-pointer parameter ties
the out-type to the C getter that writes it. Two private unsafe
helpers, adopt_topo_string and adopt_topo_nvlist, take ownership of a
libtopo-allocated string or nvlist; the new getters and the existing
label, resource, asru, fru, fmri_parse, fmri_to_string, snapshot uuid,
property, and property_groups paths all go through them, so the
copy-then-strfree and cast-then-wrap sequences each live in one place.

Callers of these getters usually treat "property absent" and "property
has the wrong type" differently (debug log vs. warning), so libtopo's
ETOPO_PROP_NOENT and ETOPO_PROP_TYPE map to two new variants,
Error::PropertyNotFound and Error::PropertyType, each carrying the
group and name (and, for the type error, the type that was asked for).
Node::property reports a missing property the same way. All other
codes still surface as Error::Topo.

Array getters are not wrapped; PropValue already covers them.

libtopo bumps to 0.2.0: Error is not non_exhaustive, so the new
variants can break exhaustive matches.

Fixes #16
@smklein
smklein force-pushed the libtopo-typed-property-getters branch from c1a9125 to 5096cf2 Compare September 16, 2026 13:48
@smklein
smklein merged commit 24107d4 into main Sep 16, 2026
2 checks passed
smklein added a commit that referenced this pull request Sep 16, 2026
Node::name and Node::property work in `&str`, but the names from
`<fm/topo_hc.h>` were only available as the NUL-terminated byte arrays
libtopo-sys binds, so consumers hand-copied `"nvme"`, `"io"`,
`"instance"`.

- libtopo-sys allowlists all of topo_hc.h (was `BAY|NVME|SLOT`);
regenerated
with bindgen 0.72.1 on a Helios 3 host. This adds the remaining hc node
  names (CHASSIS, MOTHERBOARD, PCIEX_DEVICE, ...) and
  TOPO_PROP_NVME_NVM_CAPACITY from the current header.
- New `libtopo::hc`: every topo_hc.h string constant as `&'static str`,
derived at compile time from the sys byte arrays so the values stay tied
to the header. Names match the C macros. The conversion is built on the
const `CStr` APIs, which keeps the crate's MSRV at the edition-2024
floor
and rejects interior NULs; `Scheme::as_cstr` shares the same const
helper.
- `generate.sh` records the header's string-macro names in
  `libtopo/src/topo_hc_names.txt`, and a unit test asserts `libtopo::hc`
lists exactly those names, so regenerating against a newer header fails
  the test until `hc.rs` is updated.
- Examples use the constants instead of a libtopo-sys shim.
- The `/usr/lib/fm/amd64` RPATH for libtopo's tests, examples, and
doctests
now comes from a `libtopo/build.rs` that consumes the `DEP_TOPO_LIBDIRS`
hint libtopo-sys already exports, so they load libtopo.so.1 without the
  repo-local `.cargo/config.toml`, which is removed. This only affects
  libtopo's own targets; dependents still set their own RPATH.
- CI runs `cargo test --doc`, since neither `--all-targets` nor nextest
  builds doctests.
- libtopo-sys bumps to 0.1.1. libtopo stays at the 0.2.0 set by #18;
this
  change is purely additive.

Fixes #15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add typed property getters mirroring topo_prop_get_*

1 participant