HeteroSTA3D API Reference

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.

Memory Requirements

• For GPU corners: pos_x, pos_y, hbt_x, hbt_y must point to GPU device memory.
• For CPU corners: pos_x, pos_y, hbt_x, hbt_y must point to host memory.

Coordinate Indexing

The coordinates are indexed by INTERNAL pin orders. The pin orders from external databases might need a reshuffle before being fed to this function.

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, const char *dc_name);

Description

Gets the pin-to-net mapping array using internal pin orders. The returned array is indexed by pin index, and each element is the net index that the pin belongs to.

Return Value

Returns a pointer to the pin2net array, or NULL if failed. The array size is num_pins. The returned pointer is valid until the delay corner is destroyed or the Heterosta3D environment is freed.

Arguments

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

heterosta3d_lookup_pin#

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

Description

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

This function is only available after reading the netlist. 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.