.NET (C#)

.NET (C#) API Reference

Namespace: Sparsr.Host

This document provides the complete API reference for the managed .NET (C#) host library (Sparsr.Host), which wraps the native libsparsr_host C library via P/Invoke. It enables .NET applications to interact with Sparsr hardware accelerators and software emulators.

Enumerations

SparsrExecutionStatus

Represents the execution status of the Sparsr backend engine or hardware accelerator.

namespace Sparsr.Host;

public enum SparsrExecutionStatus : uint
{
    NotDone = 0,
    Done = 1
}

Members:

• NotDone (0): Execution is in progress or incomplete.
• Done (1): Execution has finished successfully.

Classes

Sparsr

Sealed partial class providing managed host API methods for initializing the runtime kernel, loading and executing instruction batches, querying execution status, and performing CMEM (Co-processor Memory) reads and writes.

namespace Sparsr.Host;

public sealed partial class Sparsr

Constants

CmemUncompressedSize

public const int CmemUncompressedSize = 512;

The fixed size (in bytes) of an uncompressed CMEM data block payload (512 bytes).

Methods

InitializeKernel

Initializes the Sparsr execution environment and backend engine.

public void InitializeKernel()

Parameters:

• None.

Return Value:

• void

LoadBatchFromBinary

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

public void LoadBatchFromBinary(string binaryFilePath, uint startAddress)

Parameters:

• binaryFilePath (string): Path to the instruction binary file on disk.
• startAddress (uint): Target starting instruction memory address.

Exceptions:

• ArgumentException: Thrown if binaryFilePath is null, empty, or consists only of whitespace.
• FileNotFoundException: Thrown if no binary file exists at the specified path.

Return Value:

• void

ExecuteBatch

Triggers instruction batch execution starting from the specified address.

public void ExecuteBatch(uint startAddress)

Parameters:

• startAddress (uint): Starting instruction memory address to execute.

Return Value:

• void

ReadStatus

Reads and returns the current execution status from the native backend.

public SparsrExecutionStatus ReadStatus()

Parameters:

• None.

Return Value:

• SparsrExecutionStatus: Current backend execution status (SparsrExecutionStatus.NotDone or SparsrExecutionStatus.Done).

WriteDataCmem

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

public void WriteDataCmem(byte[] uncompressedData, uint address)

Parameters:

• uncompressedData (byte[]): Data payload buffer to write. Must be exactly CmemUncompressedSize (512) bytes.
• address (uint): Target CMEM block address.

Exceptions:

• ArgumentNullException: Thrown if uncompressedData is null.
• ArgumentException: Thrown if uncompressedData.Length is not equal to CmemUncompressedSize (512 bytes).

Return Value:

• void

ReadDataCmem

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

public byte[] ReadDataCmem(uint address)

Parameters:

• address (uint): Target CMEM block address to read.

Exceptions:

• InvalidOperationException: Thrown if the native backend returns a null pointer (nint.Zero).

Return Value:

• byte[]: A newly allocated 512-byte array containing the retrieved CMEM block.

Native Library Resolution

The static constructor of Sparsr configures a custom NativeLibrary DllImport resolver for the assembly. When P/Invoke methods in NativeMethods call into libsparsr_host, the resolver automatically searches for libsparsr_host.so across:

1. The directory containing the loaded assembly.
2. The application base directory (AppContext.BaseDirectory).
3. System default library search paths.