Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
1 changed files with 798 additions and 681 deletions
68
docs/native-api.md
Normal file
68
docs/native-api.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# 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.
|
||||
|
||||
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](../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).
|
||||
Loading…
Reference in a new issue