Expand description
§tpt-uir-ffi
C ABI (opaque-handle) bindings for inspecting TPT-UIR regions.
This crate exposes a read-only, C-callable API over a deserialized TPT-UIR
region. It is built as a cdylib / staticlib / rlib and a C header
(include/tpt_uir_ffi.h) is generated at build time with cbindgen.
§Installation
Not yet on crates.io. From Rust, depend on it via git or a path within this workspace:
[dependencies]
tpt-uir-ffi = { git = "https://github.com/tpt-solutions/tpt-uir", package = "tpt-uir-ffi" }From C/C++, build the cdylib/staticlib and link against the generated
header:
cargo build --release -p tpt-uir-ffi
# -> target/release/{libtpt_uir_ffi.so,tpt_uir_ffi.dll,libtpt_uir_ffi.a}
# -> crates/tpt-uir-ffi/include/tpt_uir_ffi.h (regenerated by build.rs via cbindgen)§API
tpt_uir_load— deserialize a postcard-encoded region into an opaque handletpt_uir_free— release a handletpt_uir_block_count/tpt_uir_op_count— countstpt_uir_op_dialect/tpt_uir_op_op— op-name parts (borrowed pointers)tpt_uir_op_operand(_count)— operand accesstpt_uir_validate_ssa/tpt_uir_validate_dialect— validation
§Example (C)
#include "tpt_uir_ffi.h"
#include <stdio.h>
int main(void) {
// `bytes` holds a postcard-encoded TPT-UIR region.
void *handle = NULL;
if (tpt_uir_load(bytes, bytes_len, &handle) != 0) return 1;
size_t blocks = 0;
tpt_uir_block_count(handle, &blocks);
if (tpt_uir_validate_ssa(handle) != 0) {
tpt_uir_free(handle);
return 1;
}
tpt_uir_free(handle);
return 0;
}See CHANGELOG.md for release notes.
§C example
A complete, compilable C consumer lives at
examples/basic.c. It loads a small postcard-encoded
region, reads its op name and operands, validates SSA, and frees the handle:
cargo build --release -p tpt-uir-ffi
cc -Iinclude examples/basic.c -o basic \
-L../../target/release -ltpt_uir_ffi -Wl,-rpath,../../target/release
./basic§Error codes
All functions return 0 on success. Non-zero codes: 1 — bad pointer,
handle, or index; 2 — decode error (tpt_uir_load); 3 — string contains an
interior NUL byte (tpt_uir_op_dialect / tpt_uir_op_op). Functions never
panic across the FFI boundary.
§License
Licensed under either of MIT or Apache-2.0 at your option. C ABI for read-only inspection of TPT-UIR regions.
The API is opaque-handle based: call tpt_uir_load to deserialize a
postcard-encoded region into a heap-allocated handle, then query it with the
accessor functions. Call tpt_uir_free when done. All functions return
0 on success and a non-zero code on error.
Functions§
- tpt_
uir_ ⚠block_ count - Write the number of blocks in the region to
*out. - tpt_
uir_ ⚠free - Free a handle produced by
tpt_uir_load. - tpt_
uir_ ⚠load - Deserialize a postcard-encoded region from
data[0..len]into a new handle. - tpt_
uir_ ⚠op_ count - Write the number of operations in block
block_indexto*out. - tpt_
uir_ ⚠op_ dialect - Write the dialect portion of operation
(block_index, op_index)to*out. - tpt_
uir_ ⚠op_ op - Write the op portion of operation
(block_index, op_index)to*out. - tpt_
uir_ ⚠op_ operand - Write operand
operand_indexof operation(block_index, op_index)to*out. - tpt_
uir_ ⚠op_ operand_ count - Write the number of operands of operation
(block_index, op_index)to*out. - tpt_
uir_ ⚠validate_ dialect - Validate that every op’s dialect starts with
prefix. Returns0if all match,1otherwise (or on a badprefixpointer). - tpt_
uir_ ⚠validate_ ssa - Validate SSA well-formedness. Returns
0if valid,1if invalid.