2026-11-16 16:51:41 -08:00
|
|
|
# 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.
|
|
|
|
|
|
Make Pheon structural review results self-contained
Capture revision metadata, cell presence and attributes, and structured
diagnostics in owned comparison results. Derive outcomes and render text,
JSON, and hierarchy reports without retaining source documents. Keep derived
descriptions and graph analysis in their renderers.
Use pheon-structural-v1 and PHEON_LAYER_NAMES_V1 consistently, expose helpers
through their defining modules, and remove obsolete re-exports. Update user
guides and report fixtures without changing schema version 1.
Cover dropped inputs, diagnostic ordering, absent and empty cells, offset
independence, and CLI failures. All 92 Rust tests pass in debug and release;
report and hierarchy goldens retain their behavior.
2026-11-16 20:45:06 -08:00
|
|
|
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.
|
|
|
|
|
|
2026-11-16 16:51:41 -08:00
|
|
|
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
|
Make Pheon structural review results self-contained
Capture revision metadata, cell presence and attributes, and structured
diagnostics in owned comparison results. Derive outcomes and render text,
JSON, and hierarchy reports without retaining source documents. Keep derived
descriptions and graph analysis in their renderers.
Use pheon-structural-v1 and PHEON_LAYER_NAMES_V1 consistently, expose helpers
through their defining modules, and remove obsolete re-exports. Update user
guides and report fixtures without changing schema version 1.
Cover dropped inputs, diagnostic ordering, absent and empty cells, offset
independence, and CLI failures. All 92 Rust tests pass in debug and release;
report and hierarchy goldens retain their behavior.
2026-11-16 20:45:06 -08:00
|
|
|
[header](https://mpxd.net/code/jan/pheon/src/branch/master/pheon/_ffi.h) defines the functions and Arrow C Data structures.
|
2026-11-16 16:51:41 -08:00
|
|
|
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).
|