API System

API reference: System

The System module starts and stops the library, connects modules into a pipeline with bind calls, hands out timestamps and gives access to a few system facilities. Every program calls IMP_System_Init once before it creates FrameSource channels, encoder channels, OSD or IVS groups, and IMP_System_Exit at the end.

Pipeline cells: a cell (IMPCell) names one output of one module: device (DEV_ID_FS, DEV_ID_ENC, DEV_ID_OSD, DEV_ID_IVS, ...), group (or channel) and output index. IMP_System_Bind(src, dst) connects the output of src to the input of dst, for example FrameSource channel 0 to encoder group 0. OpenIMP records the bind; the consumer (the encoder, the IVS group) pulls frames from the source when it starts, so bind before the consumer starts. At most 16 binds exist at a time.

Extensions in this module (OpenIMP only): OpenIMP_* functions that belong to FrameSource, such as the fallback test frame, are described on the FrameSource page and in Beyond the Vendor.

Status columns: T10 T20 T21 T23 T30 T31 T40 T41. As of 2026-10-31. Part of the API reference.

Contents

• Start and stop (2)
• Binding modules (3)
• Time and identification (4)
• Register access (2)
• Memory pools (5)
• Logging (1)
• Decoder (T23) (8)
• System utilities (SU) (1)

Status symbols are those of the feature matrix (API coverage tables):

• ✅ works, device-tested
• ✅+ works, device-tested, better than the vendor
• ✅rt API round trip on device, no visible effect expected
• ✅r works: called by the streamer on fleet cameras of this SoC that passed the fleet soak
• ✅○ vendor no-op, OpenIMP matches that
• 🔧h implemented, host tests only (no camera run yet)
• 🔧a really connected per static audit, no device test tracked
• 🔧+ API round trip in QEMU, no camera
• ⚠c value only stored and read back, nothing applied
• ⚠s returns 0 without any effect
• ❌e exported but fails or has a known defect
• ❌ not exported by OpenIMP
• · function does not exist on this SoC (not in that SoC's vendor API; not a gap)
• ? state not determined
• 📋 no OpenIMP build for this SoC yet (planned)

Start and stop

IMP_System_Init

int IMP_System_Init(void);

Initialises the library, starts the system clock at zero and prepares the FrameSource, IVS, OSD, encoder and framebuffer parts.

Returns: 0 on success and when already initialised; negative when one of the parts fails (those already started are shut down again).

Call it once, before any other module call.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest agg47 2026-10-28 .34

Used by: prudynt, raptor, timps.

IMP_System_Exit

int IMP_System_Exit(void);

Shuts the parts down in the reverse order.

Returns: 0, also when not initialised.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest agg47 2026-10-28 .34

Used by: prudynt, raptor, timps.

Binding modules

IMP_System_Bind

int IMP_System_Bind(IMPCell *srcCell, IMPCell *dstCell);

Connects the output cell src to the input cell dst.

Parameters

• src: Source cell.
• dst: Destination cell.

Returns: 0 on success and when the same bind already exists; -1 for a NULL cell or when all bind slots are used.

Typical binds are FrameSource -> encoder, FrameSource -> IVS, FrameSource -> OSD -> encoder. For an OSD group in the middle use IMP_OSD_AttachToGroup.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor, timps.

See also: IMP_System_UnBind, IMP_System_GetBindbyDest

IMP_System_UnBind

int IMP_System_UnBind(IMPCell *srcCell, IMPCell *dstCell);

Removes a bind.

Returns: 0 on success; -1 for a NULL cell or when no such bind exists.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest agg47 2026-10-26 .31
• T20: apitest agg47 2026-10-26 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest agg47 2026-10-26 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor, timps.

IMP_System_GetBindbyDest

int IMP_System_GetBindbyDest(IMPCell *dstCell, IMPCell *srcCell);

Finds the source cell that feeds a destination cell.

Parameters

• dst: Destination cell.
• src: Receives the source cell.

Returns: 0 on success; -1 for a NULL pointer or when nothing is bound to dst.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest agg47 2026-10-26 .31
• T20: apitest agg47 2026-10-26 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest agg47 2026-10-26 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor.

Time and identification

IMP_System_GetVersion

int IMP_System_GetVersion(IMPVersion *pstVersion);

Writes the version text of the library into a buffer.

Parameters

• version: Buffer of at least 64 bytes; it is zeroed and the text is copied in.

Returns: -1 for NULL.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor, timps.

Difference from the vendor library: The text is OpenIMP's own, for example libimp.so T31 openimp; the vendor library returns its release number.

IMP_System_GetCPUInfo

const char *IMP_System_GetCPUInfo(void);

Returns the name of the SoC variant, for example T31X, T41NQ or T40-XP.

Returns: A pointer to a constant string, never NULL.

The variant is read from the SoC when possible; otherwise a default of the family is returned.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor.

IMP_System_GetTimeStamp

uint64_t IMP_System_GetTimeStamp(void);

Returns the system time in microseconds since System_Init (or since the last RebaseTimeStamp), taken from a monotonic clock.

Returns: The time, or -1 when the clock cannot be read.

FrameSource frame timestamps are on this timeline.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.

IMP_System_RebaseTimeStamp

int IMP_System_RebaseTimeStamp(uint64_t basets);

Moves the system timeline so that the current moment has the given value.

Parameters

• timestamp: New "now" in microseconds.

Returns: 0, or -1 when the clock cannot be read.

Use it to align the timeline with an external clock (for example the first RTP timestamp).

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor.

Register access

Direct access to hardware registers by physical address through /dev/mem. For debugging and bring-up, not for streamers.

IMP_System_ReadReg32

uint32_t IMP_System_ReadReg32(uint32_t addr);

Reads a 32-bit hardware register at a physical address.

Parameters

• addr: Physical address, must be 4-byte aligned.

Returns: The register value; 0 when the address is not aligned or /dev/mem cannot be used (a failure cannot be told from a register that reads 0).

The access maps one page of /dev/mem per call. It was tested by reading and writing a scratch register of the UART.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor.

IMP_System_WriteReg32

void IMP_System_WriteReg32(uint32_t addr, uint32_t val);

Writes a 32-bit hardware register at a physical address.

Parameters

• addr: Physical address, 4-byte aligned.
• value: Value to write.

Returns: no value.

Writing the wrong register can hang the SoC.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor.

Memory pools

A pool reserves a block of media memory under an id; channels bound to it with IMP_FrameSource_SetPool or IMP_Encoder_SetPool take their buffers from it. T41 carves a real contiguous pool out of the rmem arena. On the other SoCs OpenIMP allocates every channel from its single rmem arena anyway, so a requested pool is validated and recorded by name but reserves nothing (reserving memory that nothing draws from would only shrink the arena).

IMP_System_MemPoolRequest

int IMP_System_MemPoolRequest(int poolId, size_t size, const char *name);

Requests a memory pool under an id.

Parameters

• poolId: Pool number, 0 to 31 on T31, T40 and T41.
• size: Bytes, above 0.
• name: Label for diagnostics.

Returns: 0 on success; -1 for an invalid id, a size of 0, a size above 2 GiB (T41), when the id is already requested (T31, T40, T41) or when the memory is not available (T41).

SoC: only in the vendor API of T23, T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest agg59 2026-10-31 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Difference from the vendor library: T41 reserves a real block in rmem, as the vendor library does. T23, T31 and T40 only record the request. See Beyond the Vendor: Behaviour that differs from the vendor (better or deviating on purpose).

IMP_System_MemPoolFree

int IMP_System_MemPoolFree(int poolId);

Releases a pool.

Returns: -1 for an invalid or not requested pool. On T41 also -1 while a buffer of the pool is still allocated; the channels bound to the pool are unbound and may be bound again with IMP_FrameSource_SetPool.

SoC: only in the vendor API of T31

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	·	·

Tested (tool, date, camera, what was checked):

• T31: apitest rc3gaps2 2026-10-27 .26

Difference from the vendor library: Beyond the vendor on T41: the vendor library keeps a pool until the program exits, OpenIMP lets the application release it. See Beyond the Vendor: Behaviour that differs from the vendor (better or deviating on purpose).

IMP_MemPool_InitPool

int IMP_MemPool_InitPool(int pool_id, uint32_t size, int flags);  /* T21, T23, T30, T31 */
int IMP_MemPool_InitPool(int pool_id, uint32_t size, const char *name);  /* T40, T41 */

Low-level pool creation; not in the public header. On T41 it is the call behind System_MemPoolRequest.

Returns: 0 on success; -1 for an invalid id, a size of 0, a pool that is already in use, or when the memory is not available.

T21, T23, T30 and T31: ids 0 to 15, one DMA block of the given size, flags is ignored. T40 and T41: ids 0 to 31, size up to 2 GiB, the block is carved out of rmem as one contiguous range and registered under the id with its name. On T40 the System call only records the request and does not use this function. Use System_MemPoolRequest.

SoC: only in the vendor API of T23, T31

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	?	·	·

Tested (tool, date, camera, what was checked):

• T23: apitest apitest-cov 2026-10-27 .30

IMP_MemPool_GetById

int IMP_MemPool_GetById(int pool_id, void *info_out);  /* T21, T23, T30, T31 */
void *IMP_MemPool_GetById(int pool_id);  /* T40, T41 */

Looks up a pool by id. Not in the public header.

Returns: T21, T23, T30, T31: 0 and an IMPDMABufferInfo (name, physical and virtual address, size, id) in info_out; -1 for an invalid id, a NULL pointer or a pool that is not in use. T40, T41: a non-NULL pointer when the pool exists, otherwise NULL.

On T41 FrameSource checks it before it binds a channel to the pool.

SoC: only in the vendor API of T23, T31

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	?	·	·

Tested (tool, date, camera, what was checked):

• T23: apitest apitest-cov 2026-10-27 .30

IMP_MemPool_Release

int IMP_MemPool_Release(int pool_id);

Low-level release of a pool. Use System_MemPoolFree where it exists.

Returns: 0 on success and for a pool that is not in use; -1 for an invalid id.

Only on T21, T23, T30 and T31 (ids 0 to 15); it frees the DMA block. T40 and T41 release pools through System_MemPoolFree.

SoC: T21, T23, T30 and T31.

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	?	·	·

Logging

IMP_Log_Get/Set_Option

int IMP_Log_Get_Option(void);
void IMP_Log_Set_Option(int option);

Reads or sets which fields (file, line, function, ...) the library prints in front of a log message.

Parameters

• option: Bit mask of the IMP_LOG_OP_* flags; IMP_LOG_OP_NONE gives the terse vendor line.

Returns: Get returns the mask, Set has no return value.

OpenIMP prints warnings and errors to stderr always, informational and debug messages only when OPENIMP_DEBUG_TRACE is set. Syslog output is enabled with OPENIMP_LOG_SYSLOG=1. The default mask is the full one.

SoC: not in the vendor API of T30

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	·	✅	✅	✅

Tested (tool, date, camera, what was checked):

• T10: apitest agg47-cases 2026-10-26 .31
• T20: apitest agg47-cases 2026-10-26 .107
• T21: apitest agg47-cases 2026-10-26 .24
• T23: apitest agg47-cases 2026-10-26 .30
• T31: apitest next+ko/libimp swap 2026-10-27 .26
• T40: apitest agg47-cases 2026-10-26 .184
• T41: apitest next+ko/libimp swap 2026-10-27 .34

Difference from the vendor library: The vendor library starts with no fields and prints everything it has; OpenIMP is quiet by default so a camera is not flooded.

Decoder (T23)

A hardware JPEG decoder on channel 0, implemented by OpenIMP on T23 only (the T40 and T41 vendor libraries export it too; OpenIMP does not). It decodes JPEG pictures into NV12, NV21 or YUV420P and runs in the helper process that also hosts the T23 H.264 encoder. The status row is marked as having a known defect because that helper is off by default since agg-37, so the decoder is not usable in a default T23 build.

IMP_Decoder_CreateChn

/* IMP_Decoder_CreateChn: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Creates the decoder channel 0 and starts the decoding worker.

Parameters

• chn: Channel, only 0.
• attr: Decoder attribute; the type must be JPEG, the maximum size non-zero, the pixel format NV12, NV21 or YUV420P.

Returns: -1 for another channel, another payload type or pixel format, a zero size, an existing channel or when the worker cannot be started.

SoC: Implemented by OpenIMP on T23 only.

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	❌e	❌	·	❌	❌

IMP_Decoder_DestroyChn

/* IMP_Decoder_DestroyChn: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Stops the worker and releases all frames.

Returns: -1 for another channel or a channel that does not exist.

SoC: Implemented by OpenIMP on T23 only.

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	❌e	❌	·	❌	❌

IMP_Decoder_StartRecvPic

/* IMP_Decoder_StartRecvPic: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Marks the channel as receiving.

Returns: -1 for another channel or a channel that does not exist.

SoC: Implemented by OpenIMP on T23 only.

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	❌e	❌	·	❌	❌

IMP_Decoder_StopRecvPic

/* IMP_Decoder_StopRecvPic: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Marks the channel as not receiving and wakes any waiting caller.

Returns: -1 for another channel or a channel that does not exist.

SoC: Implemented by OpenIMP on T23 only.

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	❌e	❌	·	❌	❌

IMP_Decoder_SendStreamTimeout

/* IMP_Decoder_SendStreamTimeout: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Decodes one JPEG picture. It waits up to the timeout for a free picture buffer, decodes in the helper process and queues the picture.

Parameters

• stream: JPEG data (p_payload, i_payload) and a timestamp that is passed on to the picture.
• timeout_ms: Maximum wait in milliseconds for a buffer and for the decode.

Returns: -1 for another channel, an empty or NULL stream, no free buffer within the timeout, or a decode error.

Number of pictures that can be held at once is the nrKeepStream of the channel attribute (at least 1). Give every picture back with ReleaseFrame.

SoC: Implemented by OpenIMP on T23 only.

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	❌e	❌	·	❌	❌

IMP_Decoder_PollingFrame

/* IMP_Decoder_PollingFrame: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Waits until a decoded picture is ready.

Returns: 0 when ready; -1 on timeout, for another channel or when the channel does not exist.

SoC: Implemented by OpenIMP on T23 only.

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	❌e	❌	·	❌	❌

IMP_Decoder_GetFrame

/* IMP_Decoder_GetFrame: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Hands out the oldest decoded picture (a pointer to its frame info with address and size).

Returns: -1 when none is ready, for another channel, NULL or when the channel does not exist.

SoC: Implemented by OpenIMP on T23 only.

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	❌e	❌	·	❌	❌

IMP_Decoder_ReleaseFrame

/* IMP_Decoder_ReleaseFrame: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Gives a picture back so the buffer can be reused.

Returns: -1 for another channel, NULL, or a frame that was not handed out.

SoC: Implemented by OpenIMP on T23 only.

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	❌e	❌	·	❌	❌

System utilities (SU)

SU_Base_Shutdown

int SU_Base_Shutdown(void);

Syncs the file systems and tells the init process to reboot (or power off).

Returns: 0 when the signal reached init, -1 (with errno) when it could not be sent.

The call returns before the shutdown has finished. The environment variable OPENIMP_SU_SHUTDOWN selects what init is asked to do: unset or reboot sends SIGTERM (reboot on busybox init), poweroff sends SIGUSR2 (power off), vendor sends SIGCHLD like the vendor library.

T10	T20	T21	T23	T30	T31	T40	T41
🔧h	🔧h	🔧h	🔧h	🔧h	🔧h	🔧h	🔧h

Difference from the vendor library: The vendor library only sends SIGCHLD, which busybox init ignores, so on such a system the camera keeps running. OpenIMP's default sends the signal busybox acts on.