# nosv-sys
`nosv-sys` provides raw Rust FFI bindings to the nOS-V C API. It is intended to
be the dependency boundary for a future safe `nosv` crate, not the place where
Rust ownership, task-context, or lifetime guarantees are modeled.
All nOS-V functions exposed by this crate are unsafe to use directly. Callers
must uphold the invariants documented by the nOS-V headers, including runtime
initialization, task-context restrictions, callback validity, pointer validity,
and handle ownership.
## Requirements
- nOS-V 4.1.0 or newer.
- `pkg-config`.
- A C toolchain and `libclang` usable by `bindgen`.
- `PKG_CONFIG_PATH` set to a directory containing `nos-v.pc` when nOS-V is not
installed in a default pkg-config search path.
For a local nOS-V checkout, `PKG_CONFIG_PATH` commonly points at either the
checkout root containing `nos-v.pc` or the installed prefix's `lib/pkgconfig`
directory.
## Scope
This crate deliberately exposes:
- bindgen-generated raw types and functions from `nosv.h`, `nosv/affinity.h`,
`nosv/compat.h`, `nosv/hwinfo.h`, and `nosv/memory.h`;
- C-like aliases for nOS-V enum constants;
- manual translations of nOS-V flag macros that bindgen does not emit.
This crate deliberately does not expose:
- RAII runtime initialization;
- owned task or task-type handles;
- task-context tokens;
- Rust closure trampolines;
- safe synchronization wrappers.
Those belong in the safe `nosv` crate built on top of this one.
## Safe Crate Direction
A safe wrapper crate should start by wrapping low-risk query APIs, then encode
nOS-V ownership and context rules in Rust types:
- `Error` and `Result<T>` around `nosv_err_t`;
- value wrappers for topology, memory, and affinity APIs;
- `Runtime`, `TaskType`, `Task`, and `JoinHandle<T>` ownership wrappers;
- a `TaskContext<'_>` token for APIs that are only valid from nOS-V task
context;
- `extern "C"` callback trampolines that never unwind across the C boundary.