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 (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
reservedarray. 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() only when a multi-call sequence must be atomic as a whole.
Buffers
Every tensor is a sp500_buffer. A buffer from sp500_buffer_alloc() lives in the shared-memory window the DSP reads directly, so it costs no copy. A buffer from 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 |
A tensor handed to or received from the DSP. |
Macros¶
SP500_VERSION_MAJOR¶
SP500_VERSION_MINOR¶
SP500_VERSION_PATCH¶
SP500_VERSION_INT¶
#define SP500_VERSION_INT (((SP500_VERSION_MAJOR) * 10000) + \ ((SP500_VERSION_MINOR) * 100) + (SP500_VERSION_PATCH))
Header version as one integer: major10000 + minor100 + patch.
SP500_API¶
SP500_INLINE¶
SP500_DEFAULT_OPEN_TIMEOUT_MS¶
Default deadline for sp500_dsp_open(), in milliseconds.
SP500_DEFAULT_DSP_TIMEOUT_MS¶
Default deadline for a single DSP call, in milliseconds.
SP500_ALIGN_DSP¶
Smallest alignment the DSP accepts.
SP500_ALIGN_NPU¶
Alignment to use for a buffer that the NPU also reads or writes.
Enumerations¶
(anonymous 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() 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)¶
sp500_buffer::flags bits.
| Value | Description |
|---|---|
SP500_BUFFER_SHARED = 1u << 0 |
Set by 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¶
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¶
Human-readable name of a status code. Never NULL, never allocates.
sp500_version¶
Version of the loaded library, encoded like SP500_VERSION_INT.
Compare against SP500_VERSION_INT at start-up to catch a header/library mismatch before it becomes a silent misinterpretation of a struct.
sp500_version_string¶
Version of the loaded library as "major.minor.patch". Never NULL.
sp500_dsp_open¶
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. 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() and 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, SP500_ERR_TIMEOUT if the DSP did not register in time, or SP500_ERR_NOT_READY 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¶
Non-blocking: 1 once sp500_dsp_open() has succeeded, 0 otherwise.
sp500_set_dsp_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 is clamped up to it, and sp500_get_dsp_timeout_ms() reports what actually took effect.
Parameters
timeout_ms— Deadline in milliseconds; 0 restores SP500_DEFAULT_DSP_TIMEOUT_MS, and anything below it is clamped up to it.
sp500_get_dsp_timeout_ms¶
Deadline currently in force, in milliseconds, after clamping.
sp500_dsp_lock¶
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() must be paired with exactly one sp500_dsp_unlock(). An unbalanced lock stalls the DSP and the shared-memory allocator for every process on the system.
sp500_dsp_unlock¶
Release one level of the lock taken by sp500_dsp_lock().
sp500_shmem_alloc¶
Allocate inside the DSP shared-memory window.
Parameters
size— Bytes to allocate.alignment— Byte alignment; must be at least SP500_ALIGN_DSP. Use 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().
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¶
Release a buffer from sp500_shmem_alloc(). NULL is ignored.
sp500_shmem_contains¶
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() has succeeded.
sp500_shmem_phys_addr¶
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() has succeeded).
sp500_buffer_none¶
An unused buffer, for an optional tensor.
sp500_buffer_alloc¶
Allocate a zero-copy buffer in shared memory.
Parameters
size— Bytes to allocate.alignment— Byte alignment; at least SP500_ALIGN_DSP.
Returns
The buffer, or an unused buffer (data == NULL) if the window is exhausted. Release it with sp500_buffer_release().
sp500_buffer_wrap¶
Wrap memory you already own. The call stages one copy in each direction; nothing is taken over and nothing needs freeing.
sp500_buffer_release¶
Release a buffer and reset it to unused.
Frees the shared-memory allocation of a buffer from sp500_buffer_alloc(); does nothing to a wrapped buffer beyond clearing the handle.