vStream

Driver API for Virtual Streaming interface using fixed-size data blocks (cmsis_vstream.h) More...

Content
	Return Codes
	Return codes for driver functions. Negative values indicate errors.
	Streaming Modes
	Streaming modes used by the vStreamStart function.
	Driver Event Flags
	Events signaled by the driver via the vStreamEvent function.
	Streaming Status
	Structure indicating the status of the virtual stream.

Data Structures
struct	vStreamDriver_t
	Access structure of the Virtual Streaming interface Driver. More...

Typedefs
typedef void(*	vStreamEvent_t) (uint32_t event_flags)
	Pointer to vStreamEvent : Handling of Virtual Streaming Events.

Functions
int32_t	vStreamInitialize (vStreamEvent_t event_cb)
	Initialize Virtual Streaming interface.
int32_t	vStreamUninitialize (void)
	De-initialize Virtual Streaming interface.
int32_t	vStreamSetBuf (void *buf, uint32_t buf_size, uint32_t block_size)
	Set Virtual Streaming data buffer.
int32_t	vStreamStart (uint32_t mode)
	Start streaming.
int32_t	vStreamStop (void)
	Stop streaming.
void *	vStreamGetBlock (void)
	Get pointer to Virtual Streaming data block.
int32_t	vStreamReleaseBlock (void)
	Release Virtual Streaming data block.
vStreamStatus_t	vStreamGetStatus (void)
	Get Virtual Streaming status.
void	vStreamEvent (uint32_t event_flags)
	Callback function for handling Virtual Streaming events.

Description

Driver API for Virtual Streaming interface using fixed-size data blocks (cmsis_vstream.h)

The vStream software component provides an abstraction layer for streaming data using fixed-size blocks. It offers a standardized interface to interact with various streaming devices such as sensors, cameras, microphones, speakers, or simulated devices. It allows seamless development on one platform and deployment on another.

vStream API

The following header file defines the Application Programming Interface (API) for Virtual Streaming interface:

• cmsis_vstream.h: Driver API for Virtual Streaming interface

The driver implementation is typically a part of the Board Support Pack (BSP) for a specific board with streaming devices.

Driver Functions

All driver functions are grouped within the vStreamDriver_t access structure.

User Code Template

The CMSIS Driver:vStream (API):Custom component provides a stub implementation of all vStream driver functions.
This template can be used to implement the vStream driver for your target hardware.

The default driver access structure is named Driver_vStreamDevice, but Device should be replaced with a specific device name, such as Driver_vStreamAccelerometer. See vStreamDriver_t for more details.

Code Example

The following example demonstrates how to use the vStream driver for an accelerometer:

#include "cmsis_vstream.h"
#include "cmsis_os2.h"
#include "cmsis_compiler.h"
 
#include <stdio.h>
#include <string.h>
 
// Sensor characteristics
#define SENSOR_DATA_BYTES_PER_SAMPLE    (6U)
 
// Sensor data usage configuration
#define SENSOR_DATA_SAMPLES_PER_SLICE   (100U)
 
// Thread flag for signaling sensor data available
#define SENSOR_DATA_READY_FLAG          (1U)
 
// Raw sensor data sample structure
typedef struct {
  int16_t x;
  int16_t y;
  int16_t z;
} accelerometer_sample_t;
 
static uint8_t vstream_buf[(SENSOR_DATA_SAMPLES_PER_SLICE * SENSOR_DATA_BYTES_PER_SAMPLE) * 2] __ALIGNED(4);
 
// vStream driver
extern vStreamDriver_t     Driver_vStreamAccelerometer;
static vStreamDriver_t *ptrDriver_vStreamAccelerometer = &Driver_vStreamAccelerometer;
 
// Thread identifier
osThreadId_t threadId_threadDataProcess = NULL;
 
// Local function declaration
__NO_RETURN void threadDataProcess (void *argument);
 
 
// Function that signals thread event when data is available with vStream
static void vStreamEvent (uint32_t event_flags) {
 
  if ((event_flags & VSTREAM_EVENT_DATA) != 0U) {
    // Inform data processing thread that sensor data is available
    osThreadFlagsSet(threadId_threadDataProcess, SENSOR_DATA_READY_FLAG);
  }
}
 
// Function that initializes vStream for accelerometer
void vStreamInit (void) {
 
  ptrDriver_vStreamAccelerometer->Initialize(vStreamEvent);
  ptrDriver_vStreamAccelerometer->SetBuf(vstream_buf, sizeof(vstream_buf), SENSOR_DATA_SAMPLES_PER_SLICE * SENSOR_DATA_BYTES_PER_SAMPLE);
  ptrDriver_vStreamAccelerometer->Start(VSTREAM_MODE_CONTINUOUS);
 
  threadId_threadDataProcess = osThreadNew(threadDataProcess, NULL, NULL);
}
 
// Thread function that processes the sensor data
__NO_RETURN void threadDataProcess (void *argument) {
  accelerometer_sample_t *ptr_acc_sample;
  (void) argument;
 
  for (;;) {
    uint32_t flags = osThreadFlagsWait(SENSOR_DATA_READY_FLAG, osFlagsWaitAny, osWaitForever);
 
    if (((flags & osFlagsError)           == 0U) &&         // If not an error and
        ((flags & SENSOR_DATA_READY_FLAG) != 0U)) {         // if flag is sensor data ready
 
      // Get pointer to acquired sensor data
      ptr_acc_sample = (accelerometer_sample_t *)ptrDriver_vStreamAccelerometer->GetBlock();
 
      // Do something with sensor data, convert, copy for ML, ...
      // In this example we just print it to STDIO
      for (uint32_t i = 0U; i < SENSOR_DATA_SAMPLES_PER_SLICE; i++) {
        printf("Acc x=%i, y=%i, z=%i\r\n", ptr_acc_sample->x, ptr_acc_sample->y, ptr_acc_sample->z);
        ptr_acc_sample++;
      }
    }
 
    // Release current block for further data acquisition
    ptrDriver_vStreamAccelerometer->ReleaseBlock();
  }
}

---

Data Structure Documentation

vStreamDriver_t

struct vStreamDriver_t

Access structure of the Virtual Streaming interface Driver.

This structure provides function pointers to access the vStream driver.

Recommended naming convention for access structures:

• Driver_vStream<Device>
• Examples:
  • Driver_vStreamAccelerometer
  • Driver_vStreamGyroscope
  • Driver_vStreamHumidity
  • Driver_vStreamTemperature
  • Driver_vStreamIMU
  • Driver_vStreamAudioIn
  • Driver_vStreamAudioOut
  • Driver_vStreamVideoIn
  • Driver_vStreamVideoOut

Data Fields
int32_t(*	Initialize )(vStreamEvent_t event_cb)
	Pointer to vStreamInitialize : Initialize Virtual Streaming interface.
int32_t(*	Uninitialize )(void)
	Pointer to vStreamUninitialize : De-initialize Virtual Streaming interface.
int32_t(*	SetBuf )(void *buf, uint32_t buf_size, uint32_t block_size)
	Pointer to vStreamSetBuf : Set Virtual Streaming data buffer.
int32_t(*	Start )(uint32_t mode)
	Pointer to vStreamStart : Start streaming.
int32_t(*	Stop )(void)
	Pointer to vStreamStop : Stop streaming.
void *(*	GetBlock )(void)
	Pointer to vStreamGetBlock : Get pointer to data block.
int32_t(*	ReleaseBlock )(void)
	Pointer to vStreamReleaseBlock : Release data block.
vStreamStatus_t(*	GetStatus )(void)
	Pointer to vStreamGetStatus : Get Virtual Streaming status.

Field Documentation

Initialize

int32_t(* Initialize) (vStreamEvent_t event_cb)

Pointer to vStreamInitialize : Initialize Virtual Streaming interface.

Uninitialize

int32_t(* Uninitialize) (void)

Pointer to vStreamUninitialize : De-initialize Virtual Streaming interface.

SetBuf

int32_t(* SetBuf) (void *buf, uint32_t buf_size, uint32_t block_size)

Pointer to vStreamSetBuf : Set Virtual Streaming data buffer.

Start

int32_t(* Start) (uint32_t mode)

Pointer to vStreamStart : Start streaming.

Stop

int32_t(* Stop) (void)

Pointer to vStreamStop : Stop streaming.

GetBlock

void *(* GetBlock) (void)

Pointer to vStreamGetBlock : Get pointer to data block.

ReleaseBlock

int32_t(* ReleaseBlock) (void)

Pointer to vStreamReleaseBlock : Release data block.

GetStatus

vStreamStatus_t(* GetStatus) (void)

Pointer to vStreamGetStatus : Get Virtual Streaming status.

Typedef Documentation

vStreamEvent_t

vStreamEvent_t

Pointer to vStreamEvent : Handling of Virtual Streaming Events.

Provides the typedef for the callback function vStreamEvent.

Parameter for:

• vStreamInitialize

Function Documentation

vStreamInitialize()

int32_t vStreamInitialize

(

vStreamEvent_t

event_cb

)

Initialize Virtual Streaming interface.

Returns

VSTREAM_OK on success; otherwise, an appropriate error code (see Return Codes)

This function prepares the Virtual Streaming interface for operation.

It performs the following tasks:

• Initializes internal driver resources and streaming device interface.
• Registers the vStreamEvent event signaling callback function.

The event callback function must conform to the vStreamEvent_t type.
If event signaling is not required, pass a NULL pointer for event_cb.

This function must be called before any other vStream operations.

Code Example:

#include "cmsis_vstream.h"
 
// vStream driver
extern vStreamDriver_t     Driver_vStreamAccelerometer;
static vStreamDriver_t *ptrDriver_vStreamAccelerometer = &Driver_vStreamAccelerometer;
 
int main (void) {
 
  SystemCoreClockUpdate();              // System Initialization
 
  ptrDriver_vStreamAccelerometer->Initialize(NULL);
  // ...
}

vStreamUninitialize()

int32_t vStreamUninitialize

(

void

)

De-initialize Virtual Streaming interface.

Returns

VSTREAM_OK on success; otherwise, an VSTREAM_ERROR error code (see Return Codes)

This function disables the Virtual Streaming interface and releases all associated resources that were allocated during vStreamInitialize.

Use this function to properly shut down the interface when streaming is no longer required.
After calling vStreamUninitialize, the interface is considered inactive, and re-initialization is required to resume streaming operations.

Code Example:

#include "cmsis_vstream.h"
 
// vStream driver
extern vStreamDriver_t     Driver_vStreamAccelerometer;
static vStreamDriver_t *ptrDriver_vStreamAccelerometer = &Driver_vStreamAccelerometer;
 
int main (void) {
 
  SystemCoreClockUpdate();              // System Initialization
 
  ptrDriver_vStreamAccelerometer->Initialize(NULL);
  // ...
  ptrDriver_vStreamAccelerometer->Uninitialize();
}

vStreamSetBuf()

int32_t vStreamSetBuf	(	void *	buf,
		uint32_t	buf_size,
		uint32_t	block_size
	)

Set Virtual Streaming data buffer.

Parameters

[in]	buf	pointer to memory buffer used for streaming data
[in]	buf_size	total size of the streaming data buffer (in bytes)
[in]	block_size	streaming data block size (in bytes)

Returns

VSTREAM_OK on success; otherwise, an appropriate error code (see Return Codes)

This function registers a memory buffer for use by the Virtual Streaming driver.
The buffer is used for reading or writing fixed-size data blocks, depending on the streaming direction.

Memory buffer recommendations:

• the buffer should be aligned to a 4-byte boundary, to facilitate DMA usage.
• buf_size should be an integer multiple of block_size, otherwise the largest multiple that fits will be used.
• a minimum of two blocks is recommended to ensure proper buffering and streaming continuity.

If block_size is larger than buf_size, the function returns VSTREAM_ERROR_PARAMETER.

This function must be called after initialization and before starting the stream.

Code Example:

#include "cmsis_vstream.h"
 
// vStream driver
extern vStreamDriver_t     Driver_vStreamAccelerometer;
static vStreamDriver_t *ptrDriver_vStreamAccelerometer = &Driver_vStreamAccelerometer;
 
static uint32_t vstream_buf[256];
 
int main (void) {
 
  SystemCoreClockUpdate();              // System Initialization
 
  ptrDriver_vStreamAccelerometer->Initialize(NULL);
  ptrDriver_vStreamAccelerometer->SetBuf(vstream_buf, sizeof(vstream_buf), sizeof(vstream_buf)/2);
  // ...
  ptrDriver_vStreamAccelerometer->Uninitialize();
}

vStreamStart()

int32_t vStreamStart

(

uint32_t

mode

)

Start streaming.

Parameters

[in]

mode

streaming mode (see Streaming Modes)

Returns

VSTREAM_OK on success; otherwise, an appropriate error code (see Return Codes)

This function initiates the streaming operation based on the specified mode.

Before calling vStreamStart:

• The interface must be initialized using vStreamInitialize.
• A valid buffer must be configured using vStreamSetBuf.

The mode parameter defines the streaming behavior:

• VSTREAM_MODE_CONTINUOUS : Streaming continues until explicitly stopped.
• VSTREAM_MODE_SINGLE : Streaming stops automatically after transferring a single data block.

Code Example:

#include "cmsis_vstream.h"
 
// vStream driver
extern vStreamDriver_t     Driver_vStreamAccelerometer;
static vStreamDriver_t *ptrDriver_vStreamAccelerometer = &Driver_vStreamAccelerometer;
 
static uint32_t vstream_buf[256];
 
int main (void) {
 
  SystemCoreClockUpdate();              // System Initialization
 
  ptrDriver_vStreamAccelerometer->Initialize(NULL);
  ptrDriver_vStreamAccelerometer->SetBuf(vstream_buf, sizeof(vstream_buf), sizeof(vstream_buf)/2);
  ptrDriver_vStreamAccelerometer->Start(VSTREAM_MODE_CONTINUOUS);
  // ...
  ptrDriver_vStreamAccelerometer->Uninitialize();
}

vStreamStop()

int32_t vStreamStop

(

void

)

Stop streaming.

Returns

VSTREAM_OK on success; otherwise, an VSTREAM_ERROR error code (see Return Codes)

This function stops the ongoing streaming process initiated by vStreamStart and resets the stream, by discarding any remaining or incomplete data blocks.

Calling this function halts data transfers and prepares the stream for either shutdown or restart. After stopping, the stream can be restarted using vStreamStart without requiring re-initialization or reconfiguration, provided the buffer settings remain valid.

Code Example:

#include "cmsis_vstream.h"
 
// vStream driver
extern vStreamDriver_t     Driver_vStreamAccelerometer;
static vStreamDriver_t *ptrDriver_vStreamAccelerometer = &Driver_vStreamAccelerometer;
 
static uint32_t vstream_buf[256];
 
int main (void) {
 
  SystemCoreClockUpdate();              // System Initialization
 
  ptrDriver_vStreamAccelerometer->Initialize(NULL);
  ptrDriver_vStreamAccelerometer->SetBuf(vstream_buf, sizeof(vstream_buf), sizeof(vstream_buf)/2);
  ptrDriver_vStreamAccelerometer->Start(VSTREAM_MODE_CONTINUOUS);
  // ...
  ptrDriver_vStreamAccelerometer->Stop();
  ptrDriver_vStreamAccelerometer->Uninitialize();
}

vStreamGetBlock()

void * vStreamGetBlock

(

void

)

Get pointer to Virtual Streaming data block.

Returns

pointer to data block, returns NULL if no block is available

This function provides access to the data block used for input or output operations, depending on the streaming direction.

• For input streams (receiving data): returns a pointer to the oldest unread data block.
  If no unread block is available, the function returns NULL.
• For output streams (sending data): returns a pointer to the next available empty block where the application can write data.
  If no empty block is available, the function returns NULL.

The returned block remains valid until it is released using vStreamReleaseBlock.

Code Example:

#include "cmsis_vstream.h"
 
// vStream driver
extern vStreamDriver_t     Driver_vStreamAccelerometer;
static vStreamDriver_t *ptrDriver_vStreamAccelerometer = &Driver_vStreamAccelerometer;
 
static uint32_t vstream_buf[256];
 
int main (void) {
  static volatile uint32_t *ptr_sensor_data_block;
 
  SystemCoreClockUpdate();              // System Initialization
 
  ptrDriver_vStreamAccelerometer->Initialize(NULL);
  ptrDriver_vStreamAccelerometer->SetBuf(vstream_buf, sizeof(vstream_buf), sizeof(vstream_buf)/2);
  ptrDriver_vStreamAccelerometer->Start(VSTREAM_MODE_CONTINUOUS);
  do {
    ptr_sensor_data_block = ptrDriver_vStreamAccelerometer->GetBlock();
  } while (ptr_sensor_data_block == NULL);
  // ...
  ptrDriver_vStreamAccelerometer->Stop();
  ptrDriver_vStreamAccelerometer->Uninitialize();
}

vStreamReleaseBlock()

int32_t vStreamReleaseBlock

(

void

)

Release Virtual Streaming data block.

Returns

VSTREAM_OK on success; otherwise, an VSTREAM_ERROR error code (see Return Codes)

This function finalizes the use of the data block returned by vStreamGetBlock.

• For input streams: marks the block as processed, making it available for reuse by the driver.
• For output streams: commits the block for transmission, indicating that the data is ready to be streamed out.

This function must be called after processing or preparing the data block returned by vStreamGetBlock to maintain proper buffer flow and avoid data loss or stalling.

Code Example:

#include "cmsis_vstream.h"
 
// vStream driver
extern vStreamDriver_t     Driver_vStreamAccelerometer;
static vStreamDriver_t *ptrDriver_vStreamAccelerometer = &Driver_vStreamAccelerometer;
 
static uint32_t vstream_buf[256];
 
int main (void) {
  static volatile uint32_t *ptr_sensor_data_block;
 
  SystemCoreClockUpdate();              // System Initialization
 
  ptrDriver_vStreamAccelerometer->Initialize(NULL);
  ptrDriver_vStreamAccelerometer->SetBuf(vstream_buf, sizeof(vstream_buf), sizeof(vstream_buf)/2);
  ptrDriver_vStreamAccelerometer->Start(VSTREAM_MODE_CONTINUOUS);
  do {
    ptr_sensor_data_block = ptrDriver_vStreamAccelerometer->GetBlock();
  } while (ptr_sensor_data_block == NULL);
  // Do something with sensor data
  // ...
  ptrDriver_vStreamAccelerometer->ReleaseBlock();
  ptrDriver_vStreamAccelerometer->Stop();
  ptrDriver_vStreamAccelerometer->Uninitialize();
}

vStreamGetStatus()

vStreamStatus_t vStreamGetStatus

(

void

)

Get Virtual Streaming status.

Returns

streaming status structure (see Streaming Status)

This function returns the current operational status of the Virtual Streaming interface.

The returned structure includes the following information:

• Streaming activity status.
• Overflow or underflow conditions.
• End-of-stream (EOS) indication.

Use this function to monitor the health and state of the streaming process during runtime.

Code Example:

#include "cmsis_vstream.h"
 
// vStream driver
extern vStreamDriver_t     Driver_vStreamAccelerometer;
static vStreamDriver_t *ptrDriver_vStreamAccelerometer = &Driver_vStreamAccelerometer;
 
static uint32_t vstream_buf[256];
 
int main (void) {
 
  SystemCoreClockUpdate();              // System Initialization
 
  ptrDriver_vStreamAccelerometer->Initialize(NULL);
  ptrDriver_vStreamAccelerometer->SetBuf(vstream_buf, sizeof(vstream_buf), sizeof(vstream_buf)/2);
  ptrDriver_vStreamAccelerometer->Start(VSTREAM_MODE_CONTINUOUS);
  if (ptrDriver_vStreamAccelerometer->GetStatus().active == 0U) {
    // If streaming is not active exit
  }
  // ...
  ptrDriver_vStreamAccelerometer->Stop();
  ptrDriver_vStreamAccelerometer->Uninitialize();
}

vStreamEvent()

void vStreamEvent

(

uint32_t

event_flags

)

Callback function for handling Virtual Streaming events.

Parameters

[in]

event_flags

bitmask indicating one or more streaming events (see Driver Event Flags)

This user-implemented callback function is invoked by the driver to signal runtime events during streaming.
It is registered by the vStreamInitialize function.

The event_flags parameter is a bitmask where each bit represents a specific event condition.

Multiple events may be reported simultaneously via combined bits. Use this function to respond to runtime conditions, such as processing data, handling errors, or updating application state.

The following events can be signaled:

Parameter event_flags	Bit	Description
VSTREAM_EVENT_DATA	0	Occurs when a new block of incoming data is available or when a block of outgoing data was streamed out.
VSTREAM_EVENT_OVERFLOW	1	Occurs when a block of incoming data begins to be overwritten because it was not released in time using the vStreamReleaseBlock function.
VSTREAM_EVENT_UNDERFLOW	2	Occurs when a block of outgoing data was not ready (committed with vStreamReleaseBlock function) before streaming out required it.
VSTREAM_EVENT_EOS	3	Occurs when a streaming interface reached end of stream.