Skip to main content

Crate tpt_uir_ffi

Crate tpt_uir_ffi 

Source
Expand description

§tpt-uir-ffi

CI License: MIT OR Apache-2.0

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 handle
  • tpt_uir_free — release a handle
  • tpt_uir_block_count / tpt_uir_op_count — counts
  • tpt_uir_op_dialect / tpt_uir_op_op — op-name parts (borrowed pointers)
  • tpt_uir_op_operand(_count) — operand access
  • tpt_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_index to *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_index of 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. Returns 0 if all match, 1 otherwise (or on a bad prefix pointer).
tpt_uir_validate_ssa⚠
Validate SSA well-formedness. Returns 0 if valid, 1 if invalid.