# dsp.h

Mobilint SP500 DSP offload - status codes, lifecycle and shared memory.

This is the foundation header. sp500/letterbox.h, sp500/log\_mel.h and sp500/yolo.h all include it; include the module headers you need.

The only dependencies are \<stdint.h\> and \<stddef.h\>. No C++ standard library, no OpenCV, no vendor SDK header, no `using` directive, and no macro that is not prefixed SP500\_.

**The binary interface**

Everything inside the `extern "C"` block is the ABI of the shared library:

- Every function returns [sp500\_status](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-status>) (an int32\_t) or a fixed-width scalar. Enumerations name constants only; what crosses the boundary is int32\_t or uint32\_t, never an enum type whose width is implementation defined.
- No struct is passed or returned by value across the boundary. Pointers only.
- Every struct ends with a `reserved` array. It must be zero. A later library version may give those words a meaning whose zero value is today's behaviour.
- Always fill a parameter struct with its `*_params_init()` function before setting fields. The defaults are not all zero, and a struct you only zeroed carries none of them. An all-zero struct is always rejected, because the fields documented as required are invalid at zero - but if you zero a struct and then set exactly those required fields, the call runs with every remaining option at zero rather than at its default. Initialise first.
- Nothing throws. Every entry point is an exception firewall.

**Threading**

Every entry point may be called concurrently from several threads and several processes. A DSP call serialises itself against every other DSP call and every shared-memory allocation, system wide, for the duration of the round trip. Use [sp500\_dsp\_lock()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-lock>) only when a multi-call sequence must be atomic as a whole.

**Buffers**

Every tensor is a [sp500\_buffer](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_buffer/index.md>). A buffer from [sp500\_buffer\_alloc()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-buffer-alloc>) lives in the shared-memory window the DSP reads directly, so it costs no copy. A buffer from [sp500\_buffer\_wrap()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-buffer-wrap>) points at memory you already own and is staged through shared memory, which costs one copy in each direction. Prefer the former for anything large, and for anything you also hand to the NPU.

## Data structures

| Name | Description |
| --- | --- |
| [`sp500_buffer`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_buffer/index.md>) | A tensor handed to or received from the DSP. |

## Macros

### SP500\_VERSION\_MAJOR

```cpp
#define SP500_VERSION_MAJOR 1
```

### SP500\_VERSION\_MINOR

```cpp
#define SP500_VERSION_MINOR 0
```

### SP500\_VERSION\_PATCH

```cpp
#define SP500_VERSION_PATCH 0
```

### SP500\_VERSION\_INT

```cpp
#define SP500_VERSION_INT (((SP500_VERSION_MAJOR) * 10000) + \ ((SP500_VERSION_MINOR) * 100) + (SP500_VERSION_PATCH))
```

Header version as one integer: major*10000 + minor*100 + patch.

### SP500\_API

```cpp
#define SP500_API
```

### SP500\_INLINE

```cpp
#define SP500_INLINE static inline
```

### SP500\_DEFAULT\_OPEN\_TIMEOUT\_MS

```cpp
#define SP500_DEFAULT_OPEN_TIMEOUT_MS 10000u
```

Default deadline for [sp500\_dsp\_open()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-open>), in milliseconds.

### SP500\_DEFAULT\_DSP\_TIMEOUT\_MS

```cpp
#define SP500_DEFAULT_DSP_TIMEOUT_MS 3000u
```

Default deadline for a single DSP call, in milliseconds.

### SP500\_ALIGN\_DSP

```cpp
#define SP500_ALIGN_DSP 32u
```

Smallest alignment the DSP accepts.

### SP500\_ALIGN\_NPU

```cpp
#define SP500_ALIGN_NPU 4096u
```

Alignment to use for a buffer that the NPU also reads or writes.

## Enumerations

### (anonymous enum)

```cpp
enum
```

| Value | Description |
| --- | --- |
| `SP500_OK = 0` | completed; output buffers are valid |
| `SP500_ERR_INVALID_ARG = -1` | a parameter is missing, out of range, or inconsistent with another |
| `SP500_ERR_UNSUPPORTED = -2` | this module cannot run that combination |
| `SP500_ERR_BUFFER_TOO_SMALL = -3` | a supplied buffer cannot hold the result |
| `SP500_ERR_NOT_READY = -4` | [sp500\_dsp\_open()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-open>) has not succeeded |
| `SP500_ERR_NO_MEMORY = -5` | host or shared-memory allocation failed |
| `SP500_ERR_TIMEOUT = -6` | the DSP did not answer within the deadline |
| `SP500_ERR_DSP = -7` | the DSP reported a failure |
| `SP500_ERR_INTERNAL = -8` | unexpected internal condition |

### (anonymous enum)

```cpp
enum
```

[sp500\_buffer::flags](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_buffer/#flags>) bits.

| Value | Description |
| --- | --- |
| `SP500_BUFFER_SHARED = 1u << 0` | Set by [sp500\_buffer\_alloc()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-buffer-alloc>): the memory is inside the shared-memory window, so the DSP reads and writes it in place with no copy. |

## Type aliases

### sp500\_status

```cpp
typedef int32_t sp500_status
```

Result of every sp500 call.

A typedef over int32\_t rather than an enum type, so a code introduced by a later library version is never an out-of-range enum value in your build. Zero is success and every error is negative, so both `rc != SP500_OK` and `rc < 0` are correct tests. Treat an unrecognised negative value as a generic failure.

## Functions

### sp500\_status\_string

```cpp
const char * sp500_status_string(sp500_status status)
```

Human-readable name of a status code. Never NULL, never allocates.

### sp500\_version

```cpp
uint32_t sp500_version(void)
```

Version of the loaded library, encoded like [SP500\_VERSION\_INT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-version-int>).

Compare against [SP500\_VERSION\_INT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-version-int>) at start-up to catch a header/library mismatch before it becomes a silent misinterpretation of a struct.

### sp500\_version\_string

```cpp
const char * sp500_version_string(void)
```

Version of the loaded library as "major.minor.patch". Never NULL.

### sp500\_dsp\_open

```cpp
sp500_status sp500_dsp_open(uint32_t timeout_ms)
```

Attach to the DSP. Must succeed before any other DSP call.

Attaching waits for the DSP-side firmware to register itself, so it blocks until the DSP is up. `timeout_ms` bounds that wait; pass 0 for [SP500\_DEFAULT\_OPEN\_TIMEOUT\_MS](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-default-open-timeout-ms>). Calling it again after success is a cheap no-op, so it is safe to call from every module of an application.

On success the shared-memory window is also mapped, which is what makes [sp500\_shmem\_contains()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-shmem-contains>) and [sp500\_shmem\_phys\_addr()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-shmem-phys-addr>) usable from an NPU setup path that runs before the first DSP call.

**Parameters**

- `timeout_ms` — Deadline in milliseconds, or 0 for the default.

**Returns**

[SP500\_OK](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>), [SP500\_ERR\_TIMEOUT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) if the DSP did not register in time, or [SP500\_ERR\_NOT\_READY](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) if the link could not be established.

> [!NOTE]
>
> A timeout leaves one worker thread parked inside the vendor link layer until the DSP appears. Load the DSP firmware before calling, and treat a timeout as a fatal start-up error rather than something to retry in a loop.

### sp500\_dsp\_is\_open

```cpp
int sp500_dsp_is_open(void)
```

Non-blocking: 1 once [sp500\_dsp\_open()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-open>) has succeeded, 0 otherwise.

### sp500\_set\_dsp\_timeout\_ms

```cpp
void sp500_set_dsp_timeout_ms(uint32_t timeout_ms)
```

Raise the deadline applied to every subsequent DSP call.

This is a dead-DSP guard, not a latency budget. It must sit comfortably ABOVE the longest operation you submit; the case to check is a long log-mel clip.

A deadline that expires does not cancel anything: the DSP keeps working on buffers the call has already given up on and released, the late completion desynchronises the single-slot channel, and the next call can return the previous call's result. Recovering from that needs a DSP reload. Because of that, the deadline can only be raised - a value below [SP500\_DEFAULT\_DSP\_TIMEOUT\_MS](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-default-dsp-timeout-ms>) is clamped up to it, and [sp500\_get\_dsp\_timeout\_ms()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-get-dsp-timeout-ms>) reports what actually took effect.

**Parameters**

- `timeout_ms` — Deadline in milliseconds; 0 restores [SP500\_DEFAULT\_DSP\_TIMEOUT\_MS](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-default-dsp-timeout-ms>), and anything below it is clamped up to it.

### sp500\_get\_dsp\_timeout\_ms

```cpp
uint32_t sp500_get_dsp_timeout_ms(void)
```

Deadline currently in force, in milliseconds, after clamping.

### sp500\_dsp\_lock

```cpp
void sp500_dsp_lock(void)
```

Take the one reentrant DSP lock, across threads and across processes.

Individual calls already lock themselves, so this is only needed to make a multi-step sequence atomic against other threads and other processes - for example allocate, letterbox, read, free. The lock is reentrant, so the per-call lock simply nests inside it.

Every [sp500\_dsp\_lock()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-lock>) must be paired with exactly one [sp500\_dsp\_unlock()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-unlock>). An unbalanced lock stalls the DSP and the shared-memory allocator for every process on the system.

### sp500\_dsp\_unlock

```cpp
void sp500_dsp_unlock(void)
```

Release one level of the lock taken by [sp500\_dsp\_lock()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-lock>).

### sp500\_shmem\_alloc

```cpp
void * sp500_shmem_alloc(uint32_t size, uint32_t alignment)
```

Allocate inside the DSP shared-memory window.

**Parameters**

- `size` — Bytes to allocate.
- `alignment` — Byte alignment; must be at least [SP500\_ALIGN\_DSP](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-align-dsp>). Use [SP500\_ALIGN\_NPU](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-align-npu>) for buffers the NPU also touches.

**Returns**

Pointer to the buffer, or NULL if the window is exhausted or the DSP is not open. Release it with [sp500\_shmem\_free()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-shmem-free>).

> [!NOTE]
>
> The window is served by a first-fit allocator with no compaction. Freeing does reclaim, in any order, and the freed span rejoins its neighbors - but allocating and freeing buffers of mixed lifetimes every frame fragments the pool. It then carries roughly a quarter more than your live bytes, and a large request can be refused while smaller gaps go unused. Allocate your working set once and reuse it.

> [!NOTE]
>
> Never hold a shared-memory buffer in a global or static object. It would be released after the link has already been torn down.

### sp500\_shmem\_free

```cpp
void sp500_shmem_free(void *ptr)
```

Release a buffer from [sp500\_shmem\_alloc()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-shmem-alloc>). NULL is ignored.

### sp500\_shmem\_contains

```cpp
int sp500_shmem_contains(const void *ptr)
```

1 when `ptr` lies inside the shared-memory window, 0 otherwise.

Interior pointers count, so this also answers "is this row of my image in shared memory". Never blocks; returns 0 until [sp500\_dsp\_open()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-open>) has succeeded.

### sp500\_shmem\_phys\_addr

```cpp
uint64_t sp500_shmem_phys_addr(const void *ptr)
```

Physical address of a shared-memory pointer, for NPU DMA.

The window is physically contiguous, so any pointer inside it maps to a fixed physical base plus its offset. Hand the result to the NPU runtime to let it read and write the same buffer the DSP uses, with no copy in between.

**Returns**

The physical address, or 0 if `ptr` is not inside the window (including before [sp500\_dsp\_open()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-open>) has succeeded).

### sp500\_buffer\_none

```cpp
sp500_buffer sp500_buffer_none(void)
```

An unused buffer, for an optional tensor.

### sp500\_buffer\_alloc

```cpp
sp500_buffer sp500_buffer_alloc(uint32_t size, uint32_t alignment)
```

Allocate a zero-copy buffer in shared memory.

**Parameters**

- `size` — Bytes to allocate.
- `alignment` — Byte alignment; at least [SP500\_ALIGN\_DSP](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-align-dsp>).

**Returns**

The buffer, or an unused buffer (data == NULL) if the window is exhausted. Release it with [sp500\_buffer\_release()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-buffer-release>).

### sp500\_buffer\_wrap

```cpp
sp500_buffer sp500_buffer_wrap(void *data, uint32_t size)
```

Wrap memory you already own. The call stages one copy in each direction; nothing is taken over and nothing needs freeing.

### sp500\_buffer\_release

```cpp
void sp500_buffer_release(sp500_buffer *buffer)
```

Release a buffer and reset it to unused.

Frees the shared-memory allocation of a buffer from [sp500\_buffer\_alloc()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-buffer-alloc>); does nothing to a wrapped buffer beyond clearing the handle.
