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. The function returns 0 silently if num_cells mismatches — always check the return value.

4. dc_name="all". Functions whose doc says "or all to run all corners in parallel" — extract_rc_from_placement, update_delay, update_arrivals — accept the literal string "all" to fan work out across all delay corners concurrently. Reporting and path-dump calls always target a single 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. Pin + rise/fall encoding. Where an API takes a single pin_rf argument, encode it as (pin_id << 1) | rf, with rf = 0 for rise and rf = 1 for fall.

7. Pointer / string lifetime. Pointers returned by the topology queries (heterosta3d_get_pin2net / heterosta3d_get_net2pin_*) stay valid until you replace the netlist (heterosta3d_read_netlist, heterosta3d_set_netlistdb, heterosta3d_reset). Strings from heterosta3d_internal_get_celltype_of_pin are valid only until the next call that changes the netlist or cell types (heterosta3d_batch_update_celltypes, heterosta3d_read_netlist, heterosta3d_set_netlistdb, heterosta3d_reset). Copy if you need them to outlive those operations.

8. HBT (Hybrid Bonding Terminal) modeling. A 3D net is one whose pins span both dies. For each 3D net the extractor adds a vertical link at (hbt_x[net_i], hbt_y[net_i]) with unit RC (hbt_r, hbt_c). hbt_x / hbt_y are per-net arrays of length num_nets; entries for non-3D nets are unused.

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.

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

Return Value

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

Arguments

• lic_2d: A null-terminated C string containing the HeteroSTA license key, or NULL to read from HeteroSTA_Lic environment variable.
• lic_3d: A null-terminated C string containing the HeteroSTA3D license key, or NULL to read from 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

For robust resource management, particularly in C++, it is recommended to manage the Heterosta3D pointer using an automatic mechanism, such as std::unique_ptr, to ensure the environment is freed correctly.

early_late_t#

typedef enum {
  EL_EARLY = 0,
  EL_LATE = 1,
} early_late_t;

An enumeration type used to specify timing corners. Use EL_EARLY (0) for early/min/hold corners and EL_LATE (1) for late/max/setup corners.

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,
                                          early_late_t el,
                                          const char *set_name,
                                          const char *const *lib_paths,
                                          uintptr_t num_paths);

Description

Creates a Liberty set and loads multiple Liberty library files in parallel for a specific timing corner. This function processes the specified library files concurrently to improve performance. Successfully parsed libraries are merged into the Liberty set for the specified corner.

To ensure a complete analysis setup, you must create Liberty sets for both the early (EL_EARLY) and late (EL_LATE) corners for each die (top and bottom).

Return Value

Returns true if at least one of the specified Liberty library files is loaded successfully. Returns false only if parsing fails for all provided paths.

Arguments

• sta: A pointer to the Heterosta3D environment where the library data will be stored.
• el: The timing corner to associate with this Liberty set. Use EL_EARLY (0) for the early corner and EL_LATE (1) for the late corner.
• 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 can be assigned to a specific CPU or GPU device for parallel analysis.

The Liberty sets specified by top_libset_name and btm_libset_name must have been previously created using heterosta3d_create_liberty_set_batch for both EL_EARLY and EL_LATE corners.

Return Value

Returns true if the delay corner was created successfully. Returns false if the specified Liberty sets do not exist or if 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

Reads a Verilog netlist from the specified file path and populates the internal design database within the Heterosta3D environment. This function must be called after all necessary Liberty sets 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

Flattens all hierarchical instances in the design into a flat representation. This is a one-way operation that finalizes the loaded netlist data into a performance-optimized format. This function must be called after heterosta3d_read_netlist and before heterosta3d_build_graph.

Arguments

• sta: A pointer to the Heterosta3D environment.

heterosta3d_build_graph#

void heterosta3d_build_graph(Heterosta3D *sta);

Description

Constructs the internal timing graph from the flattened netlist. This is a mandatory step before any timing analysis can proceed. This function must be called after heterosta3d_flatten_all.

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. This function estimates parasitics from pin coordinates using internal Steiner tree algorithms (FLUTE) 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: Accuracy parameter for the FLUTE algorithm (unsigned integer, typically 1-8).
• dc_name: A null-terminated string containing the name of the target 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 the name of the target 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 the name of the target 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.

Pointer lifetime — valid until the netlist is replaced (heterosta3d_read_netlist, heterosta3d_set_netlistdb, 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. Different lookups can be parallelized.

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).
• dc_name: Target delay corner name.

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. This function should be called after heterosta3d_extract_rc_from_placement is finished to ensure that FlattenedParasitics has been constructed.

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 — e.g. it was produced by an upstream placement / synthesis tool. Each delay corner gets its own independent netlist copy, so per-corner mutations (heterosta3d_batch_update_celltypes, heterosta3d_ignore_net) don't affect other 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; do not pass the same pointer in twice. heterosta3d_free releases it. If you need to keep your own copy, clone via the netlistdb C API before calling.

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. Applied uniformly to every delay corner so they stay in sync — 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). On num_cells mismatch the function reports an error and returns 0 without doing anything — always check the return value.

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. The files are parsed sequentially in the order given.

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 netlist. The netlist is shared across delay corners, so the answer is identical regardless of which corner you query from.

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 netlist. Like heterosta3d_get_num_of_pins, the netlist is shared across corners.

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.

Pointer lifetime — valid until the netlist is replaced (heterosta3d_read_netlist, heterosta3d_set_netlistdb, 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.

Pointer lifetime — valid until the netlist is replaced (heterosta3d_read_netlist, heterosta3d_set_netlistdb, 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. Useful for skipping known-special nets such as clocks, scan, or power-ground stubs that should not participate in RC modeling. The mask applies to all delay corners (netlist is shared).

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.

Pointer lifetime — the pointer references internal storage. Treat it as invalidated by any of:

• heterosta3d_read_netlist
• heterosta3d_set_netlistdb
• heterosta3d_reset
• heterosta3d_batch_update_celltypes

Copy the string with strdup (or similar) 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).