Group SDS_IO_Interface

Modules > SDS_IO_Interface

sdsio.h : SDS I/O Interface for data streamsMore...

Modules

Type	Name
module	Function Return Codes SDS I/O Function Return Codes.

Public Types

Type	Name
typedef void *	sdsioId_t Handle to SDS I/O data stream.
enum	sdsioMode_t

Public Functions

Type	Name
int32_t	sdsioClose (sdsioId_t id) Close I/O stream.
int32_t	sdsioInit (void) Initialize SDS I/O.
sdsioId_t	sdsioOpen (const char * name, sdsioMode_t mode) Open I/O stream.
int32_t	sdsioRead (sdsioId_t id, void * buf, uint32_t buf_size) Read data from I/O stream.
int32_t	sdsioUninit (void) Un-initialize SDS I/O.
int32_t	sdsioWrite (sdsioId_t id, const void * buf, uint32_t buf_size) Write data to I/O stream.

Detailed Description

The SDS I/O interface provides a generic mechanism for reading from and writing to SDS files using several I/O backends.

Interface can operate over:

• A local file system, such as an SD card or semihosting, where files are accessed directly.
• A communication channel such as Ethernet, USB, or UART, where access to files is performed remotely via an SDS I/O Server.

When using a communication channel, the embedded device runs an SDS I/O Client, which communicates with the SDS I/O Server running on the Host machine. This interaction is command-based (e.g., SDSIO_CMD_OPEN, SDSIO_CMD_READ, SDSIO_CMD_WRITE) and enables the embedded system to remotely open, read, write, and close files located on the Host. For more details, refer to SDSIO Server Protocol.

The interface is lightweight and backend-agnostic, making it suitable for embedded data logging, host-interactive tools, or as a transport layer for higher-level components such as the SDS Recorder and Player.

Public Types Documentation

typedef sdsioId_t

Handle to SDS I/O data stream.

typedef void* sdsioId_t;

This pointer defines the handle to SDS I/O data stream. It is used to identify a data stream across the different functions.

---

enum sdsioMode_t

enum sdsioMode_t {
    sdsioModeRead = 0,
    sdsioModeWrite = 1
};

This enum identifies the read or write mode to SDS I/O data streams. It is a parameter of the sdsioOpen function.

---

Public Functions Documentation

function sdsioClose

Close I/O stream.

int32_t sdsioClose (
    sdsioId_t id
) 

Closes an SDS I/O stream. If the interface is a local file system or semihosting, the file is closed directly. For communication channels such as Ethernet, USB or USART, the SDS I/O Client sends a close command (SDSIO_CMD_CLOSE) to the SDS I/O Server to close the file on the Host system.

Parameters:

• id sdsioId_t handle to SDS I/O stream

Returns:

SDSIO_OK on success or a negative value on error (see Function Return Codes)

---

function sdsioInit

Initialize SDS I/O.

int32_t sdsioInit (
    void
) 

Initializes the SDS I/O interface. The interface may be a local file system (e.g., an SD card) or semihosting, or a communication channel such as Ethernet, USB or UART. In the case of a communication channel, the SDS I/O Client is used to interact with the SDS I/O Server running on a Host machine. The initialization process includes setting up the communication interface and verifying that the I/O Server is active on the Host.

Returns:

SDSIO_OK on success or a negative value on error (see Function Return Codes)

---

function sdsioOpen

Open I/O stream.

sdsioId_t sdsioOpen (
    const char * name,
    sdsioMode_t mode
) 

Opens an SDS I/O stream for reading or writing. If the interface is a local file system or semihosting, the file is opened directly. For communication channels such as Ethernet, USB or USART, the SDS I/O Client sends an open command (SDSIO_CMD_OPEN) to the SDS I/O Server to open the file on the Host system. The function returns the handle to the SDS I/O stream; if the I/O stream could not be opened, it returns NULL.

Parameters:

• name stream name (pointer to NULL terminated string)
• mode sdsioMode_t open mode

Returns:

sdsioId_t Handle to SDS I/O stream, or NULL if operation failed

---

function sdsioRead

Read data from I/O stream.

int32_t sdsioRead (
    sdsioId_t id,
    void * buf,
    uint32_t buf_size
) 

Attempts to read up to buf_size bytes of data from the SDS I/O stream identified by id into the memory pointed to buf. If the interface is a local file system or semihosting, data is read directly from the file. For communication channels such as Ethernet, USB or USART, the SDS I/O Client sends a read command (SDSIO_CMD_READ) to the SDS I/O Server, which reads the file on the Host system and returns the data to the Client.

The function attempts to read data and may block based on the behavior of the underlying interface and data availability. It returns under the following conditions:

• If data is available, the function reads up to buf_size bytes and returns the number of bytes actually read. This value may be less than buf_size.
• If no data becomes available before the timeout expires, the function returns SDSIO_ERROR_TIMEOUT.
• If data is partially read but the timeout occurs before the full request is satisfied, the function returns the number of bytes read up to that point.
• If the end of the stream is reached and no more data remains, the function returns SDSIO_EOS to indicate that the end of file has been reached and no additional data is available.
• If an I/O interface or protocol error occurs, the function returns SDSIO_ERROR or SDSIO_ERROR_INTERFACE.

Parameters:

• id sdsioId_t handle to SDS I/O stream
• buf pointer to buffer for data to read
• buf_size buffer size in bytes

Returns:

number of bytes successfully read, or a negative value on error or EOS (see Function Return Codes)

---

function sdsioUninit

Un-initialize SDS I/O.

int32_t sdsioUninit (
    void
) 

De-initializes the SDS I/O interface. If a communication channel such as Ethernet, USB or USART is used, the corresponding communication interface is also de-initialized.

Returns:

SDSIO_OK on success or a negative value on error (see Function Return Codes)

---

function sdsioWrite

Write data to I/O stream.

int32_t sdsioWrite (
    sdsioId_t id,
    const void * buf,
    uint32_t buf_size
) 

Attempts to write up to buf_size bytes from the memory pointed to buf to the SDS I/O stream identified by id. If the interface is a local file system or semihosting, data is written directly to the file. For communication channels such as Ethernet, USB or USART, the SDS I/O Client sends a write command (SDSIO_CMD_WRITE) along with the data to the SDS I/O Server, which then writes the data to a file on the Host system.

The function may return before all data has been written, depending on the available interface bandwidth, buffer capacity, or timeout behavior:

• If the write operation is successful, the function returns the number of bytes actually written. This value may be less than buf_size in case of partial write.
• If no data could be written before the operation times out, the function returns SDSIO_ERROR_TIMEOUT.
• If an I/O interface or protocol error occurs, the function returns SDSIO_ERROR or SDSIO_ERROR_INTERFACE.

Parameters:

• id sdsioId_t handle to SDS I/O stream
• buf pointer to buffer with data to write
• buf_size buffer size in bytes

Returns:

number of bytes successfully written or a negative value on error (see Function Return Codes)

---

---