HeteroSTA3D API Reference

Conventions#

Read these once before using the API — every function below assumes them.

1. Die assignment via cell-name suffix. Every cell instance in your Verilog must end with _top or _bottom, e.g. NAND2_X1_top, INV_X1_bottom. That suffix decides which die's library matches the cell. Pass the bare liberty files to heterosta3d_create_liberty_set_batch; the library does the suffixing for you.

2. Pin / net / cell indexing. All pin_id, net_id, cell_id arguments use the order that HeteroSTA3D presents — not necessarily the Verilog declaration order. You may need a reshuffle when bridging back to your own database. Use heterosta3d_get_num_of_pins / heterosta3d_get_num_of_nets for array sizes.

3. Cell-array layout for heterosta3d_batch_update_celltypes. num_cells = (number of leaf cells in your Verilog) + 1, and celltypes[0] must be the top-level module name. If num_cells does not match, the function returns 0 and makes no changes.

4. dc_name="all". heterosta3d_extract_rc_from_placement, heterosta3d_update_delay, and heterosta3d_update_arrivals accept the literal string "all" to apply the operation to every existing delay corner. Other functions that take dc_name require one specific corner.

5. Where data lives (host vs device). For extract_rc_from_placement, the pos_* / hbt_* arrays must live on the same side as the corner's device_id — host memory when the corner is created with HETEROSTA3D_CPU_DEVICE_ID, GPU memory otherwise. Topology queries (heterosta3d_get_pin2net, heterosta3d_get_net2pin_*) take a use_cuda flag so you pick the side that matches your reader.

6. Borrowed pointer lifetime. The topology-query pointers are borrowed and must not be freed. heterosta3d_get_pin2net returns num_pins elements; heterosta3d_get_net2pin_start returns num_nets + 1 elements; and heterosta3d_get_net2pin_items returns start[num_nets] elements. These pointers stay valid until the netlist is replaced or reset. The string returned by heterosta3d_internal_get_celltype_of_pin is also borrowed and must not be freed; store it in caller-owned memory if it must survive a netlist or cell-type change.

7. HBT (Hybrid Bonding Terminal) modeling. A 3D net is one whose pins span both dies. hbt_x / hbt_y provide the vertical-link coordinate for each net and have length num_nets; entries for non-3D nets are unused. hbt_r and hbt_c provide the vertical-link resistance and capacitance.

8. Use one matched release bundle. libheterosta.so, libheterosta3d.so, heterosta.h, and heterosta3d.h are validated as one compatible unit. Do not replace just the HeteroSTA library or header unless that exact combination is explicitly listed as compatible.

heterosta3d_init_license#

bool heterosta3d_init_license(const char *lic_2d, const char *lic_3d);

Description

Initializes and validates both the HeteroSTA and HeteroSTA3D licenses. This is the first function that must be called before any other library operations. If either license is not successfully initialized, subsequent calls to heterosta3d_new will fail and return a NULL pointer.

This function verifies two licenses:

1. HeteroSTA license (for 2D STA functionality)
2. HeteroSTA3D license (for 3D STA functionality)

Both licenses must be valid. If either parameter is NULL, the function will try to read from environment variables HeteroSTA_Lic and HeteroSTA3D_Lic.

Existing valid, unexpired v1.x HeteroSTA3D licenses can continue to be used with v2.0. The HeteroSTA license is checked independently and must also be valid and unexpired.

You can obtain licenses by following the instructions on our getting started page.

Return Value

Returns true if both licenses are valid and successfully initialized. Returns false otherwise.

Arguments

• lic_2d: A null-terminated C string containing the HeteroSTA license, or NULL to read from the HeteroSTA_Lic environment variable.
• lic_3d: A null-terminated C string containing the HeteroSTA3D license, or NULL to read from the HeteroSTA3D_Lic environment variable.

heterosta3d_new#

Heterosta3D *heterosta3d_new(void);

Description

Allocates and initializes a new Heterosta3D environment on the heap. This environment serves as the primary context for all subsequent 3D Static Timing Analysis (STA) operations. Creating an environment is the first step when using the HeteroSTA3D library. The returned pointer must be passed to other heterosta3d_* API functions.

Return Value

A pointer to the newly created Heterosta3D environment. Returns NULL if license initialization failed or if memory allocation failed.

heterosta3d_free#

void heterosta3d_free(Heterosta3D *sta);

Description

Frees all memory resources associated with a Heterosta3D environment previously created by heterosta3d_new. This routine should be called once you are finished with an environment to prevent memory leaks.

Arguments

• sta: A pointer to the Heterosta3D environment to be freed.

Usage Note

In C++, an RAII owner must call heterosta3d_free as its deleter. For example:

#include <memory>
 
using Heterosta3DPtr =
    std::unique_ptr<Heterosta3D, decltype(&heterosta3d_free)>;
Heterosta3DPtr sta{heterosta3d_new(), &heterosta3d_free};

A std::unique_ptr<Heterosta3D> with the default delete operation is not valid.

TimerEarlyOrLate#

#include "heterosta.h"
// TimerEarlyOrLate values: EARLY (0), LATE (1)

The timing-corner type comes from the bundled heterosta.h. Use EARLY (0) for early/min/hold Liberty data and LATE (1) for late/max/setup data.

Heterosta3DDie#

#include "heterosta3d.h"
// Heterosta3DDie values: TOP (0), BOTTOM (1)

The public die identifier has the values TOP (0) and BOTTOM (1). Use the declaration in the bundled heterosta3d.h.

HETEROSTA3D_CPU_DEVICE_ID#

#define HETEROSTA3D_CPU_DEVICE_ID UINT8_MAX

A special device ID constant that indicates CPU-only execution mode. Use this value when creating delay corners that should run on the CPU instead of a GPU.

heterosta3d_create_liberty_set_batch#

bool heterosta3d_create_liberty_set_batch(Heterosta3D *sta,
                                          TimerEarlyOrLate el,
                                          const char *set_name,
                                          const char *const *lib_paths,
                                          uintptr_t num_paths);

Description

Registers Liberty file paths under a named set for one timing context. This call does not parse the files. The files are parsed when heterosta3d_create_delay_corner uses the set for the top or bottom die.

To ensure a complete analysis setup, create Liberty sets for both the early (EARLY) and late (LATE) timing contexts for each die.

Return Value

Returns true when the paths are accepted and stored. Returns false for invalid arguments or if the set cannot be stored. Liberty parsing errors are reported later by heterosta3d_create_delay_corner.

Arguments

• sta: A pointer to the Heterosta3D environment.
• el: The timing context to associate with this Liberty set. Use EARLY (0) for early/min/hold data and LATE (1) for late/max/setup data.
• set_name: A null-terminated string containing the logical name of the Liberty set. This name will be used later when creating delay corners.
• lib_paths: An array of null-terminated strings, where each string is a path to a Liberty library file.
• num_paths: The total number of file paths contained in the lib_paths array.

heterosta3d_create_delay_corner#

bool heterosta3d_create_delay_corner(Heterosta3D *sta,
                                     const char *dc_name,
                                     const char *top_libset_name,
                                     const char *btm_libset_name,
                                     uint8_t device_id);

Description

Creates a delay corner by combining a top die Liberty set with a bottom die Liberty set. A delay corner represents a specific process corner combination (e.g., ss_ss, ff_ff) and is assigned to a specific CPU or GPU device.

The Liberty sets specified by top_libset_name and btm_libset_name must have been created with heterosta3d_create_liberty_set_batch for both EARLY and LATE timing contexts.

Return Value

Returns true if the delay corner and its Liberty data were created successfully. Returns false if a named set is incomplete or missing, a Liberty file cannot be parsed, or the device ID is invalid.

Arguments

• sta: A pointer to the Heterosta3D environment.
• dc_name: A null-terminated string containing the name of the delay corner. This name will be used in subsequent API calls to refer to this corner.
• top_libset_name: A null-terminated string containing the name of the top die Liberty set (must be created via heterosta3d_create_liberty_set_batch).
• btm_libset_name: A null-terminated string containing the name of the bottom die Liberty set (must be created via heterosta3d_create_liberty_set_batch).
• device_id: The device ID to use for this delay corner. Use HETEROSTA3D_CPU_DEVICE_ID for CPU mode, or 0, 1, 2, etc. for GPU devices.

heterosta3d_read_netlist#

bool heterosta3d_read_netlist(Heterosta3D *sta,
                              const char *verilog_path);

Description

Loads a Verilog netlist into the Heterosta3D environment. Call it after the required Liberty sets and delay corners have been created.

Important: Cell Naming Convention

Cell names in the Verilog netlist must carry _top or _bottom suffix to indicate die location. For example:

• NAND2_X1_top - indicates this cell is on the top die
• INV_X1_bottom - indicates this cell is on the bottom die

The library uses these suffixes to automatically determine which die each cell belongs to and apply the correct timing library.

Return Value

Returns true if the netlist file was read and processed successfully. Returns false on failure, which may occur if the file is not found, contains syntax errors, or if cell names do not follow the naming convention.

Arguments

• sta: A pointer to the Heterosta3D environment that the netlist data will be loaded into.
• verilog_path: A null-terminated string containing the file path to the Verilog netlist file.

heterosta3d_flatten_all#

void heterosta3d_flatten_all(Heterosta3D *sta);

Description

Converts the loaded hierarchical design into the flat design required by the timing graph. This one-way operation must be called after heterosta3d_read_netlist or heterosta3d_set_netlistdb and before heterosta3d_build_graph.

Arguments

• sta: A pointer to the Heterosta3D environment.

heterosta3d_build_graph#

void heterosta3d_build_graph(Heterosta3D *sta);

Description

Builds the timing graph from the flattened netlist. Call it after heterosta3d_flatten_all and before timing analysis.

Arguments

• sta: A pointer to the Heterosta3D environment.

heterosta3d_read_sdc#

bool heterosta3d_read_sdc(Heterosta3D *sta,
                          const char *sdc_path,
                          const char *dc_name);

Description

Reads a Synopsys Design Constraints (SDC) file and applies the constraints to the specified delay corner. SDC files contain timing constraints such as clock definitions, input/output delays, and false paths.

You can call this function multiple times with different delay corner names to apply the same or different SDC files to different corners.

Return Value

Returns true if the SDC file was read and applied successfully. Returns false on failure, which may occur if the file is not found or contains syntax errors.

Arguments

• sta: A pointer to the Heterosta3D environment.
• sdc_path: A null-terminated string containing the file path to the SDC constraints file.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_extract_rc_from_placement#

void heterosta3d_extract_rc_from_placement(
    Heterosta3D *sta,
    const float *pos_x, const float *pos_y,
    const float *hbt_x, const float *hbt_y,
    float unit_cap_x_top, float unit_cap_y_top,
    float unit_res_x_top, float unit_res_y_top,
    float unit_cap_x_btm, float unit_cap_y_btm,
    float unit_res_x_btm, float unit_res_y_btm,
    float hbt_r, float hbt_c,
    int flute_accuracy,
    const char *dc_name
);

Description

Extracts RC (resistance and capacitance) parasitics from 3D placement data and models vertical interconnects through HBTs (Hybrid Bonding Terminals).

Die location is automatically inferred by cell name suffix (_top for top die, _bottom for bottom die). Execution mode (CPU/GPU) is automatically determined by the delay corner's device_id.

Array shapes

• pos_x, pos_y: per-pin coordinates, length = heterosta3d_get_num_of_pins(sta).
• hbt_x, hbt_y: per-net HBT (Hybrid Bonding Terminal) coordinates, length = heterosta3d_get_num_of_nets(sta). Entries for non-3D nets are unused.

Memory placement

All four arrays must live on the side matching the corner's device_id — host memory for HETEROSTA3D_CPU_DEVICE_ID corners, GPU memory for GPU corners. See Conventions §5.

Coordinate indexing

Coordinates use the pin ordering described in Conventions §2 — you may need a reshuffle when bridging from your external database.

Arguments

• sta: A pointer to the Heterosta3D environment.
• pos_x: Pointer to an array of X coordinates (float32), one per pin, in host or device memory.
• pos_y: Pointer to an array of Y coordinates (float32), one per pin, in host or device memory.
• hbt_x: Pointer to an array of HBT X coordinates (float32), one per net, in host or device memory. For non-3D nets, this value can be set to any value (not used).
• hbt_y: Pointer to an array of HBT Y coordinates (float32), one per net, in host or device memory. For non-3D nets, this value can be set to any value (not used).
• unit_cap_x_top: Unit capacitance in X direction for top die (fF).
• unit_cap_y_top: Unit capacitance in Y direction for top die (fF).
• unit_res_x_top: Unit resistance in X direction for top die (kΩ).
• unit_res_y_top: Unit resistance in Y direction for top die (kΩ).
• unit_cap_x_btm: Unit capacitance in X direction for bottom die (fF).
• unit_cap_y_btm: Unit capacitance in Y direction for bottom die (fF).
• unit_res_x_btm: Unit resistance in X direction for bottom die (kΩ).
• unit_res_y_btm: Unit resistance in Y direction for bottom die (kΩ).
• hbt_r: Vertical link resistance (kΩ).
• hbt_c: Vertical link capacitance (fF).
• flute_accuracy: Integer accuracy setting for RC extraction.
• dc_name: A null-terminated string containing one target delay corner, or the literal string "all" to apply the operation to every existing delay corner.

heterosta3d_update_delay#

void heterosta3d_update_delay(Heterosta3D *sta, const char *dc_name);

Description

Calculates delays for all cell and net arcs using the extracted parasitics. This function must be called before heterosta3d_update_arrivals. The delay calculation uses the timing libraries and RC parasitics associated with the specified delay corner.

Arguments

• sta: A pointer to the Heterosta3D environment.
• dc_name: A null-terminated string containing one target delay corner, or the literal string "all" to apply the operation to every existing delay corner.

heterosta3d_update_arrivals#

void heterosta3d_update_arrivals(Heterosta3D *sta, const char *dc_name);

Description

Propagates arrival times through the timing graph to determine slack values. This function must be called after heterosta3d_update_delay. The arrival time propagation uses the constraints and delays associated with the specified delay corner.

Arguments

• sta: A pointer to the Heterosta3D environment.
• dc_name: A null-terminated string containing one target delay corner, or the literal string "all" to apply the operation to every existing delay corner.

heterosta3d_report_wns_tns_max#

bool heterosta3d_report_wns_tns_max(Heterosta3D *sta,
                                    float *wns,
                                    float *tns,
                                    const char *dc_name);

Description

Reports the worst negative slack (WNS) and total negative slack (TNS) for max(setup) timing checks. This function must be called after heterosta3d_update_arrivals and heterosta3d_update_delay.

Return Value

Returns true if the report was generated successfully. Returns false otherwise.

Arguments

• sta: A pointer to the Heterosta3D environment.
• wns: A mutable pointer to a float where the Worst Negative Slack will be stored.
• tns: A mutable pointer to a float where the Total Negative Slack will be stored.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_report_wns_tns_min#

bool heterosta3d_report_wns_tns_min(Heterosta3D *sta,
                                    float *wns,
                                    float *tns,
                                    const char *dc_name);

Description

Reports the worst negative slack (WNS) and total negative slack (TNS) for min(hold) timing checks. This function must be called after heterosta3d_update_arrivals and heterosta3d_update_delay.

Return Value

Returns true if the report was generated successfully. Returns false otherwise.

Arguments

• sta: A pointer to the Heterosta3D environment.
• wns: A mutable pointer to a float where the Worst Negative Slack will be stored.
• tns: A mutable pointer to a float where the Total Negative Slack will be stored.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_report_slacks_at_max#

void heterosta3d_report_slacks_at_max(Heterosta3D *sta,
                                       float (*slack)[2],
                                       const char *dc_name);

Description

Reports the pin/risefall slacks that come from max condition. If this slack is negative, the pin's arrival time has to be faster in order to solve it.

For datapath pins, this is equivalent to setup slack. For clock pins, this might come from capturing hold slack as well.

Memory Requirements

• For GPU corners: The slack buffer must be on GPU device memory.
• For CPU corners: The slack buffer must be on host memory.

Slack Buffer Format

The given slack buffer should be exactly num_pins in size, with each pin having two float32 values (rise and fall). That is, the total size should be 2 * num_pins * sizeof(float).

Coordinate Indexing

The pin slacks are indexed by INTERNAL pin orders. The pin orders might need a reversed reshuffle before used in external databases.

Arguments

• sta: A pointer to the Heterosta3D environment.
• slack: Output buffer for pin slacks [num_pins][2] (R/F), in host or device memory.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_report_slacks_at_min#

void heterosta3d_report_slacks_at_min(Heterosta3D *sta,
                                       float (*slack)[2],
                                       const char *dc_name);

Description

Reports pin/risefall slacks that come from min condition. If this slack is negative, the pin's arrival time has to be slower in order to solve it.

For datapath pins, this is equivalent to hold slack. For clock pins, this might come from capturing setup slack as well.

Memory Requirements

• For GPU corners: The slack buffer must be on GPU device memory.
• For CPU corners: The slack buffer must be on host memory.

Slack Buffer Format

The given slack buffer should be exactly num_pins in size, with each pin having two float32 values (rise and fall). That is, the total size should be 2 * num_pins * sizeof(float).

Coordinate Indexing

The pin slacks are indexed by INTERNAL pin orders. The pin orders might need a reversed reshuffle before used in external databases.

Arguments

• sta: A pointer to the Heterosta3D environment.
• slack: Output buffer for pin slacks [num_pins][2] (R/F), in host or device memory.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_get_pin2net#

const uintptr_t *heterosta3d_get_pin2net(Heterosta3D *sta, bool use_cuda);

Description

Gets the pin-to-net mapping array. Length = heterosta3d_get_num_of_pins(sta). Element i is the net index that pin i belongs to.

Ownership and lifetime — this is a borrowed pointer with heterosta3d_get_num_of_pins(sta) elements. Do not free it. It remains valid until the netlist is replaced or reset with heterosta3d_read_netlist, heterosta3d_set_netlistdb, or heterosta3d_reset.

Return Value

Pointer to the pin2net array (length num_pins), or NULL on failure.

Arguments

• sta: A pointer to the Heterosta3D environment.
• use_cuda: Match the side where you will read the array. true for a GPU pointer (read from GPU code), false for a host pointer (read from C/C++). Reading a GPU pointer from host code is undefined.

heterosta3d_lookup_pin#

uintptr_t heterosta3d_lookup_pin(Heterosta3D *sta, const char *pin_name);

Description

Searches for a pin by name and returns its index (see Conventions §2). The pin name can contain hierarchy (separated by /) and bit indices (using brackets []).

This function is only available after the netlist is loaded.

Return Value

Returns the internal pin index if found, or UINTPTR_MAX if not found.

Arguments

• sta: A pointer to the Heterosta3D environment.
• pin_name: A null-terminated string containing the pin name (can contain hierarchy and bit indices).

heterosta3d_dump_paths_max_to_file#

void heterosta3d_dump_paths_max_to_file(Heterosta3D *sta,
                                        uintptr_t num_paths,
                                        uintptr_t nworst,
                                        const char *file_path,
                                        const char *dc_name);

Description

Prints the timing report of the first num_paths setup timing paths to the specified file. This function must be called after heterosta3d_update_arrivals and heterosta3d_update_delay.

Arguments

• sta: A pointer to the Heterosta3D environment.
• num_paths: The total number of paths to dump.
• nworst: The number of worst paths to dump for each endpoint.
• file_path: A null-terminated string containing the path to the output file.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_dump_paths_min_to_file#

void heterosta3d_dump_paths_min_to_file(Heterosta3D *sta,
                                        uintptr_t num_paths,
                                        uintptr_t nworst,
                                        const char *file_path,
                                        const char *dc_name);

Description

Prints the timing report of the first num_paths hold timing paths to the specified file. This function must be called after heterosta3d_update_arrivals and heterosta3d_update_delay.

Arguments

• sta: A pointer to the Heterosta3D environment.
• num_paths: The total number of paths to dump.
• nworst: The number of worst paths to dump for each endpoint.
• file_path: A null-terminated string containing the path to the output file.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_write_spef#

bool heterosta3d_write_spef(Heterosta3D *sta,
                            const char *spef_path,
                            const char *dc_name);

Description

Writes a SPEF (Standard Parasitic Exchange Format) parasitics file for the specified delay corner. Call this function after heterosta3d_extract_rc_from_placement has completed for that corner.

Return Value

Returns true if the SPEF file was written successfully. Returns false otherwise.

Arguments

• sta: A pointer to the Heterosta3D environment.
• spef_path: A null-terminated string containing the path to the output SPEF file.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_report_delay_sdf#

bool heterosta3d_report_delay_sdf(Heterosta3D *sta,
                                  const char *sdf_path,
                                  const char *dc_name);

Description

Dumps a SDF (Standard Delay Format) delay file for the specified delay corner. SDF files contain timing information including cell and net delays, which can be used for gate-level simulation.

Return Value

Returns true if the SDF file was written successfully. Returns false otherwise.

Arguments

• sta: A pointer to the Heterosta3D environment.
• sdf_path: A null-terminated string containing the path to the output SDF file.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_reset#

void heterosta3d_reset(Heterosta3D *sta);

Description

Resets the Heterosta3D instance across all delay corners. The loaded liberty libraries are kept, but the netlist, constraints, and timing data are cleared so the instance can be reused for a fresh design without re-reading liberty.

Arguments

• sta: A pointer to the Heterosta3D environment.

heterosta3d_set_netlistdb#

void heterosta3d_set_netlistdb(Heterosta3D *sta, struct NetlistDB *netlistdb);

Description

Sets the netlist from a pre-built NetlistDB. Use this instead of heterosta3d_read_netlist when you already have the netlist in memory, for example when it was produced by an upstream placement or synthesis tool. The supplied design becomes the netlist used by all existing delay corners. APIs without a dc_name that change design state, including heterosta3d_batch_update_celltypes and heterosta3d_ignore_net, apply the requested change across all corners.

Building a NetlistDB* — use the constructors in netlistdb.h (shipped alongside heterosta.h / heterosta3d.h). Make sure each cell name ends with _top or _bottom per conventions §1.

Required call order

1. heterosta3d_new
2. heterosta3d_create_liberty_set_batch ...
3. heterosta3d_create_delay_corner ...
4. heterosta3d_set_netlistdb          <-- here
5. heterosta3d_flatten_all
6. heterosta3d_build_graph
7. heterosta3d_read_sdc, then extract / update / report

Do not also call heterosta3d_read_netlist afterwards — pick one netlist source per Heterosta3D instance.

Ownership

The library takes ownership of netlistdb. Do not free it yourself and do not pass the same pointer more than once. heterosta3d_free releases it. If the caller must retain a separate database, construct a distinct NetlistDB before this call.

Arguments

• sta: A pointer to the Heterosta3D environment.
• netlistdb: Non-NULL NetlistDB*; ownership is transferred to the library.

heterosta3d_batch_update_celltypes#

uintptr_t heterosta3d_batch_update_celltypes(Heterosta3D *sta,
                                             const char *const *celltypes,
                                             uintptr_t num_cells);

Description

Reassigns the cell type of every cell in one call. The requested assignments apply to every delay corner. A typical use is cell sizing where an optimizer iterates on cell types.

Array shape (see also Conventions §3 above)

• num_cells = (number of leaf cells in your Verilog) + 1.
• celltypes[0] is the top-level module name (e.g. "simple"), unchanged.
• celltypes[1..N] give the new cell type for each leaf cell, in the order HeteroSTA3D uses (typically Verilog declaration order). To discover the mapping for an unfamiliar design, walk pins with heterosta3d_internal_get_celltype_of_pin and read back the existing cell type per pin.

Call order

Requires the netlist and graph to be built first (heterosta3d_read_netlist or heterosta3d_set_netlistdb, then heterosta3d_build_graph). After a successful update, subsequent update_delay / update_arrivals / report_* calls reflect the new cell types directly — no need to rebuild the graph.

Return Value

Number of cells whose type actually changed (new type differs from old and is valid in the loaded Liberty data). If num_cells does not match, the function returns 0 and makes no changes.

Arguments

• sta: A pointer to the Heterosta3D environment.
• celltypes: Array of null-terminated C strings, celltypes[i] is the new type for cell i.
• num_cells: Length of the celltypes array (= leaf-cell count + 1).

heterosta3d_zero_slew#

void heterosta3d_zero_slew(Heterosta3D *sta, const char *dc_name);

Description

Zero-initializes the input port slews of the specified delay corner. Use this optionally before reading SDC for a corner when you do not have explicit slew constraints — having all input port slews start at 0 keeps timing analysis deterministic.

Arguments

• sta: A pointer to the Heterosta3D environment.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_batch_read_sdc#

bool heterosta3d_batch_read_sdc(Heterosta3D *sta,
                                const char *const *paths,
                                uintptr_t num_sdc,
                                const char *dc_name);

Description

Reads multiple SDC files and applies their constraints to the specified delay corner in array order.

Return Value

Returns true if at least one file is successfully parsed. Returns false only when all files fail.

Arguments

• sta: A pointer to the Heterosta3D environment.
• paths: Array of null-terminated C strings, each a path to an SDC file.
• num_sdc: Length of the paths array.
• dc_name: A null-terminated string containing the name of the target delay corner.

heterosta3d_get_num_of_pins#

uintptr_t heterosta3d_get_num_of_pins(Heterosta3D *sta);

Description

Returns the total number of pins in the loaded design. The count is the same for every delay corner in the Heterosta3D instance.

Return Value

The pin count, or 0 if the netlist is not loaded.

Arguments

• sta: A pointer to the Heterosta3D environment.

heterosta3d_get_num_of_nets#

uintptr_t heterosta3d_get_num_of_nets(Heterosta3D *sta);

Description

Returns the total number of nets in the loaded design. The count is the same for every delay corner in the Heterosta3D instance.

Return Value

The net count, or 0 if the netlist is not loaded.

Arguments

• sta: A pointer to the Heterosta3D environment.

heterosta3d_get_net2pin_start#

const uintptr_t *heterosta3d_get_net2pin_start(Heterosta3D *sta, bool use_cuda);

Description

Returns the CSR row-pointer array for the net-to-pin mapping. Length = heterosta3d_get_num_of_nets(sta) + 1. For net i, the pins belonging to it are items[start[i] .. start[i+1] - 1], where items comes from heterosta3d_get_net2pin_items.

Ownership and lifetime — this is a borrowed pointer with heterosta3d_get_num_of_nets(sta) + 1 elements. Do not free it. It remains valid until the netlist is replaced or reset with heterosta3d_read_netlist, heterosta3d_set_netlistdb, or heterosta3d_reset.

Return Value

Pointer to the CSR start array, or NULL if the netlist is not loaded.

Arguments

• sta: A pointer to the Heterosta3D environment.
• use_cuda: Match the side where you will read the array. true for a GPU pointer, false for a host pointer. See Conventions §5.

heterosta3d_get_net2pin_items#

const uintptr_t *heterosta3d_get_net2pin_items(Heterosta3D *sta, bool use_cuda);

Description

Returns the CSR items array (flattened list of pin indices) for the net-to-pin mapping. Pair with heterosta3d_get_net2pin_start for the full CSR. Pass the same use_cuda value to both calls.

Ownership, length, and lifetime — this is a borrowed pointer. Do not free it. Its length is start[num_nets], where start is returned by heterosta3d_get_net2pin_start with the same use_cuda value and num_nets is returned by heterosta3d_get_num_of_nets. It remains valid until the netlist is replaced or reset with heterosta3d_read_netlist, heterosta3d_set_netlistdb, or heterosta3d_reset.

Return Value

Pointer to the CSR items array, or NULL if the netlist is not loaded.

Arguments

• sta: A pointer to the Heterosta3D environment.
• use_cuda: Match the side where you will read the array. true for a GPU pointer, false for a host pointer. See Conventions §5.

heterosta3d_ignore_net#

bool heterosta3d_ignore_net(Heterosta3D *sta, uintptr_t net_id);

Description

Marks a net as ignored for placement RC extraction in every delay corner. This is useful for skipping known-special nets such as clocks, scan, or power-ground stubs that should not participate in RC modeling.

Return Value

Returns true if the net index was valid and the mask was updated; false otherwise.

Arguments

• sta: A pointer to the Heterosta3D environment.
• net_id: Internal net index (use heterosta3d_get_num_of_nets for the valid range).

heterosta3d_query_pin_direction#

NetlistDirection heterosta3d_query_pin_direction(Heterosta3D *sta, uintptr_t pin_id);

Description

Returns the direction (input, output, or unknown) of a pin by its internal pin index.

Return Value

A NetlistDirection enum value (I=0, O=1, Unknown=2). Returns Unknown if the lookup fails (e.g., out-of-range pin_id).

Arguments

• sta: A pointer to the Heterosta3D environment.
• pin_id: Internal pin index.

heterosta3d_internal_get_celltype_of_pin#

const char *heterosta3d_internal_get_celltype_of_pin(Heterosta3D *sta, uintptr_t pin_id);

Description

Returns the cell type currently assigned to the cell that owns pin_id. Useful as a read-back / sanity check after heterosta3d_batch_update_celltypes.

Ownership and lifetime — the returned pointer is borrowed and must not be freed. Treat it as invalidated by any of:

• heterosta3d_read_netlist
• heterosta3d_set_netlistdb
• heterosta3d_reset
• heterosta3d_batch_update_celltypes

Store the string in caller-owned memory if you need it to outlive the next such call.

Return Value

Pointer to a null-terminated cell type string, or NULL if pin_id is out of range.

Arguments

• sta: A pointer to the Heterosta3D environment.
• pin_id: Internal pin index (0 .. heterosta3d_get_num_of_pins(sta) - 1).