pheon/docs/native-api.md

78 lines
3.8 KiB
Markdown
Raw Normal View History

# Rust and C integration
Use the Rust library or C API to read GDSII into Arrow without Python. For the
returned data layout, see the [Arrow reference](arrow-schema.md).
## Rust
Add `pheon` as a dependency. The library readers accept GDSII byte slices:
```rust
use pheon::library::read_library;
let bytes = std::fs::read("chip.gds").expect("read layout");
let (_remainder, layout) = read_library(&bytes).expect("parse layout");
println!("{layout:?}");
```
`read_library` reads geometry; `scan_library` returns metadata, references, and
cell ranges. Pass `(start, end)` ranges from a scan to `read_selected_library`
to load only those cells. Each range must span one complete cell. Readers return
`(remainder, StructArray)` on success. The selected reader returns the original
input as its remainder, since selection is random access.
Layout-review APIs live in `pheon::review`, with layer-name helpers in
`pheon::review::names` and scope/display selectors in `pheon::review::selection`.
`Comparison::between(&old, &new)` captures an owned result with revision metadata,
changes, and structured diagnostics. Use `outcome()` for completeness, equality,
and exit status. Its `text`, `json_report`, and `hierarchy` renderers work after
the source documents and byte buffers are dropped. Standalone hierarchy inspection
uses `Document::hierarchy`. Reference counts are captured with the result;
union-graph and ancestor analysis run only when a hierarchy is requested.
The `record`, `records`, and `basic` modules also provide low-level GDSII record
writing. There is no high-level writer for the Arrow layout. REAL8 writing is
exact for representable in-range `f64` values: magnitudes below `2^-260`
underflow to zero; magnitudes at least `2^252` and nonfinite values are rejected.
## C API
Build the shared library with `cargo build --release --locked`. The
[header](https://mpxd.net/code/jan/pheon/src/branch/master/pheon/_ffi.h) defines the functions and Arrow C Data structures.
The library is `libpheon.so`, `libpheon.dylib`, or `pheon.dll` on Linux, macOS,
or Windows respectively.
| Function | Input | Result |
| --- | --- | --- |
| `read_path` | NUL-terminated path | Full layout. |
| `read_bytes` | Byte pointer and size | Full layout. |
| `scan_bytes` | Byte pointer and size | Metadata, references, and cell ranges. |
| `read_cells_bytes` | Bytes and cell ranges | Full layout for selected cells. |
`read_path` accepts UTF-8 paths on Windows and filesystem bytes on Unix. It reads
uncompressed GDSII; Python's `read_path` adds gzip handling.
For `read_cells_bytes`, `ranges` points to alternating uint64 start/end offsets
and `range_count` is the number of cells, not the number of offsets. Ranges are
half-open, from BGNSTR through the end of ENDSTR. Range values must be aligned,
native-endian uint64 values. Input buffers must remain readable for the call.
Null buffer pointers are allowed only when their corresponding length is zero.
### Status and ownership
Each reader returns 0 on success and -1 on failure. Call `last_error_message()`
on the same thread after a failure. It returns a borrowed NUL-terminated message;
copy it before the next parser call or thread exit. It returns null after a
successful parser call.
Supply valid, writable, initialized `ArrowArray` and `ArrowSchema` structures
without live allocations to overwrite. A failed call leaves them unchanged.
Successful outputs own their storage independently of the input buffer. Transfer
ownership to an Arrow importer, or call each non-null release callback exactly
once. Do not release structures again after an importer takes ownership.
`pheon_abi_version()` and `pheon_arrow_schema_version()` both currently return 1.
Check both before using the API. The C calling/ownership contract and Arrow
layout have separate versions; neither is the package version or the
[JSON report schema](diff-reports.md).