C (Native ABI)

API Reference: Sparsr Host Library - C/Native Library Header

Header File: sparsr.h

This document provides the full function signature reference for the Sparsr Host Library (libsparsr_host), which enables host applications to interact with Sparsr hardware accelerators and simulators, which are interfaced via "backends".

Environment Variables & Constants

SPARSR_BACKEND_ENV_VAR

Macro defining the environment variable name used to select the active execution backend.

#define SPARSR_BACKEND_ENV_VAR "SPARSR_BACKEND"

Supported Backend Values

  • softemu: Software Emulator (default when SPARSR_BACKEND is unset or empty).
  • fpgasim: FPGA simulation backend.
  • fpgaf2: Physical AWS EC2 F2 FPGA hardware accelerator backend.

Function Signatures

sparsr_kernel_init

Initializes the Sparsr runtime execution environment and selects the backend based on the SPARSR_BACKEND environment variable.

void sparsr_kernel_init(void);

Parameters

  • None.

Return Value

  • None (void).

sparsr_load_batch_from_bin

Loads a binary instruction batch file into instruction memory starting at the specified target address.

void sparsr_load_batch_from_bin(char inst_bin_file[30], uint32_t start_address);

Parameters

  • inst_bin_file (char[30]): Path string (up to 30 characters) specifying the instruction binary (.spex) file.
  • start_address (uint32_t): Starting instruction memory address.

Return Value

  • None (void).

sparsr_execute_batch

Triggers execution of the loaded instruction batch starting from the specified address.

void sparsr_execute_batch(uint32_t start_address);

Parameters

  • start_address (uint32_t): Starting instruction memory address to execute.

Return Value

  • None (void).

sparsr_read_status

Reads and returns the execution status register from the active backend.

uint32_t sparsr_read_status(void);

Parameters

  • None.

Return Value

  • uint32_t: Execution status value (0 = not completed / FPGA_not_done, 1 = completed / FPGA_done).

sparsr_write_data_cmem

Transfers a data buffer from host RAM into Co-processor Memory (CMEM) at the specified block address.

void sparsr_write_data_cmem(uint8_t *data, uint32_t address);

Parameters

  • data (uint8_t *): Pointer to the source data buffer in host CPU RAM.
  • address (uint32_t): Target CMEM block address / index.

Return Value

  • None (void).

sparsr_read_data_cmem

Reads data from Co-processor Memory (CMEM) at the specified block address into host RAM.

uint8_t *sparsr_read_data_cmem(uint32_t address);

Parameters

  • address (uint32_t): Source CMEM block address / index.

Return Value

  • uint8_t *: Pointer to the retrieved CMEM data buffer.