API Documentation

Shared Memory

The Shared Memory API provides an interface to shared memory IO utilities. In Linux, this is an implementation similar to POSIX message queues.

Standard system resource limits can be checked using $ ipcs -l command.

// Typical usage, omitting error handling:

// enforce 1 byte alignment so we can do linear packing #pragma pack(push) #pragma pack(1)

// message payload type typedef struct { unsigned long id; } payload_s;

// message type // we use a static message instead of the provided packing structure ps_shdmem_message_header // just needs to match the header first field, msg_type typedef struct { long msg_type; payload_s payload; } message_s;

// restore alignment #pragma pack(pop)

// shared memory queue psync_shdmem_queue queue; queue = PSYNC_SHDMEM_QUEUE_INVALID;

// create queue // use an arbitrary key // size for up to 10 messages psync_shdmem_queue_create( 0xABCD, 10 * sizeof(message_s), &queue );

// set message type to user-defined message_s send_msg; memset( &send_msg, 0, sizeof(send_msg) ); send_msg.msg_type = PSYNC_SHDMEM_MSG_TYPE_USER_DEF;

// push send_msg.payload.id = 1; psync_shdmem_queue_push( &queue, (ps_shdmem_message_header*) &send_msg, sizeof(send_msg.payload) );

// push send_msg.payload.id = 2; psync_shdmem_queue_push( &queue, (ps_shdmem_message_header*) &send_msg, sizeof(send_msg.payload) );

// push send_msg.payload.id = 3; psync_shdmem_queue_push( &queue, (ps_shdmem_message_header*) &send_msg, sizeof(send_msg.payload) );

// in another process … { // attach (don’t create) psync_shdmem_queue_attach( 0xABCD, &queue );

// received message
message_s recv_msg;
memset( &recv_msg, 0, sizeof(recv_msg) );

// pop, fills received message
psync_shdmem_queue_pop( &queue, (unsigned char*) &recv_msg, sizeof(recv_msg) );

// access received message ...

// only the creator needs to destroy the queue

}

// destroy queue since we created it psync_shdmem_queue_destroy( &queue );

Functions

psync_shdmem_queue_attach ( … )

This will attach to an existing shared memory queue.

Use psync_shdmem_queue_create to create and attach to a new shared memory queue.

Parameters
in/out type name description
in const unsigned long key The key identifier used by the creator of the queue. Value zero is invalid.
out psync_shdmem_queue * const queue A pointer to psync_shdmem_queue that gets set upon success.
Returns
  • DTC code:
    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_OSERR - If failed to gain access to the queue or the queue does not exist

Diagnostic trouble code reference

psync_shdmem_queue_create ( … )

This will create and attach to a shared memory queue.

Use psync_shdmem_queue_attach to attach to an existing shared memory queue.

Parameters
in/out type name description
in const unsigned long key A unique identifier key value to create the queue with, other references to the queue should use the same key. Value zero is invalid.
in const unsigned long max_queue_size The maximum total size for the queue. [bytes]
out psync_shdmem_queue * const queue A pointer to psync_shdmem_queue that gets set upon success.
Returns
  • DTC code:
    • DTC_NONE - (Zero) if success
    • [DTC_USAGE - If argument is invalid
    • DTC_OSERR - If system limits do not allow the configuration either due to size or permissions

Diagnostic trouble code reference

psync_shdmem_queue_destroy ( … )

This will destroy a shared memory queue.

Parameters
in/out type name description
in psync_shdmem_queue * const queue A pointer to psync_shdmem_queue that gets destroyed.
Returns

Diagnostic trouble code reference

psync_shdmem_queue_pop ( … )

This will pop data from a shared memory queue as a blocking operation.

psync_shdmem_queue_pop blocks until data is available.

It casts a buffer to ps_shdmem_message_header to determine message type, data follows after the ps_shdmem_message_header.msg_type field.

Parameters
in/out type name description
in psync_shdmem_queue * const queue A pointer to psync_shdmem_queue that specifies the configuration.
in unsigned char * const buffer A pointer to an unsigned char that receives the data.
in const unsigned long buffer_len The size of the specified data buffer. [bytes]
Returns

Diagnostic trouble code reference

psync_shdmem_queue_push ( … )

This will push data to a shared memory queue.

Parameters
in/out type name description
in psync_shdmem_queue * const queue A pointer to psync_shdmem_queue that specifies the configuration.
in const ps_shdmem_message_header * const message A pointer to ps_shdmem_message_header that specifies the start of data to be sent.
in const unsigned long data_size The size of the message payload to be sent, not including the ps_shdmem_message_header.msg_type size. Zero is allowed. [bytes]
Returns

Diagnostic trouble code reference

psync_shdmem_queue_try_pop ( … )

This will pop available data from a shared memory queue as a non-blocking operation.

psync_shdmem_queue_try_pop casts the buffer to ps_shdmem_message_header to determine the message type, data follows after the ps_shdmem_message_header.msg_type field.

Parameters
in/out type name description
in psync_shdmem_queue * const queue A pointer to psync_shdmem_queue that specifies the configuration.
in unsigned char * const buffer A pointer to unsigned char that receives the data.
in const unsigned long buffer_len The size of the specified data buffer. [bytes]
Returns
  • DTC code:

Diagnostic trouble code reference

Macros

PSYNC_SHDMEM_QUEUE_INVALID ( -1 )

This represents an invalid reference to a psync_shdmem_queue.

It will initialize all queues to this value before attaching to a queue with psync_shdmem_queue_attach().

PSYNC_SHDMEM_MSG_TYPE_INVALID ( 0 )

This represents an invalid ps_shdmem_message_header.msg_type value.

PolySync defined types include PSYNC_SHDMEM_MSG_TYPE_USER_DEF and PSYNC_SHDMEM_MSG_TYPE_USER_DEF.

PSYNC_SHDMEM_MSG_TYPE_USER_DEF ( 1 )

This represents the shared memory message type.

The function is a user-defined message type.

PSYNC_SHDMEM_MSG_TYPE_USER_DEF ( 2 )

This represent the shared memory message type specifically meant for image data.

Typedefs

psync_shdmem_queue

This integer handle will be used to represent the physical shared memory queue.

ps_shdmem_message_header

This will be used to provide a convenience packing layer for message passing.

The data section starts after the ps_shdmem_message_header.msg_type field.


typedef struct
{
    //
    //
    long            msg_type; // message type identifier.
                              // Value [PSYNC_SHDMEM_MSG_TYPE_INVALID](/api-docs/c/shared-memory/#macros) means invalid.
    //
    // data starts here
} ps_shdmem_message_header;

ps_shdmem_image_data_msg

The container specifically used for the shared memory image data message.

The data section starts after ps_shdmem_image_data_msg.data_size.


typedef struct
{
    //
    //
    ps_timestamp timestamp; // Image received timestamp. The time the image was received by the host.
    //
    //
    unsigned char native_timestamp_format; // Native timestamp format.
    //
    //
    ps_timestamp native_timestamp; // Native timestamp value for the image.
                                   // Provided by some devices.
                                   // Check  [native_timestamp_format](/api-docs/c-data-model/core/structures/#ps-native-timestamp) for meaning.
                                   // Format value [PSYNC_NATIVE_TIMESTAMP_FORMAT_INVALID](/api-docs/c-data-model/core/constants/#psync-native-timestamp-format-invalid) means not available.
    //
    //
    ps_pixel_format_kind pixel_format; // Image data format.
    //
    //
    ps_identifier frame_id; // Image counter. Value [PSYNC_IDENTIFIER_INVALID](/api-docs/c-data-model/core/constants/#psync-identifier-invalid) means not available.
    //
    //
    unsigned short width; Image width in pixels
    //
    //
    unsigned short height; Image height in pixels
    //
    //
    unsigned long data_size; // Image data size in bytes
    //
    //
    // data starts here
} ps_shdmem_image_data_msg;