Group SDSIO_Interface

Modules > SDSIO_Interface

sdsio.h : Input/Output Interface for SDS data streams.More...

Public Types

Type	Name
typedef void *	sdsioId_t Handle to SDSIO data stream.
enum	sdsioMode_t SDSIO stream open mode.

Public Functions

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

Detailed Description

The SDSIO interface provides a generic mechanism for reading from and writing to SDS files using different SDSIO implementations.

An SDSIO can operate over:

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

When using a communication channel, the embedded device runs an SDSIO-Client, which communicates with the SDSIO-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 Firmware 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.

Public Types Documentation

typedef sdsioId_t

Handle to SDSIO data stream.

typedef void* sdsioId_t;

This pointer defines the handle to SDSIO data stream. It is used to identify a data stream across the different functions.

---

enum sdsioMode_t

SDSIO stream open mode.

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

This enum identifies the opening mode of an SDSIO stream: read or write. It is a parameter of the sdsioOpen function.

---

Public Functions Documentation

function sdsioClose

Close SDSIO stream.

int32_t sdsioClose (
    sdsioId_t id
) 

Description:

Closes an SDSIO stream. If the interface is a local file system, the file is closed directly. For communication channels such as Ethernet, USB or USART, the SDSIO-Client sends a close command (SDSIO_CMD_CLOSE) to the SDSIO-Server to close the file on the host system.

Parameters:

• id sdsioId_t handle to SDSIO stream

Returns:

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

---

function sdsioInit

Initialize SDSIO interface.

int32_t sdsioInit (
    void
) 

Description:

Initializes the SDSIO interface. The interface may be a local file system, for example an SD card, or a communication channel such as Ethernet, USB or UART. In the case of a communication channel, the SDSIO-Client is used to interact with the SDSIO-Server running on a host machine. The initialization process includes setting up the communication interface and verifying that the SDSIO-Server is active on the host.

Returns:

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

---

function sdsioOpen

Open SDSIO stream.

sdsioId_t sdsioOpen (
    const char * name,
    sdsioMode_t mode
) 

Description:

Opens an SDSIO stream for reading or writing. If the interface is a local file system, the file is opened directly. For communication channels such as Ethernet, USB or USART, the SDSIO-Client sends an open command (SDSIO_CMD_OPEN) to the SDSIO-Server to open the file on the host system. The function returns the handle to the SDSIO stream; if the SDSIO 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 SDSIO stream, or NULL if operation failed

---

function sdsioRead

Read data from SDSIO stream.

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

Description:

Attempts to read up to buf_size bytes of data from the SDSIO stream identified by id into the memory pointed to buf. If the interface is a local file system, data is read directly from the file. For communication channels such as Ethernet, USB or USART, the SDSIO-Client sends a read command (SDSIO_CMD_READ) to the SDSIO-Server, which reads the file on the host system and returns the data to the SDSIO-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 SDS_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 SDS_EOS to indicate that the end of file has been reached and no additional data is available.
• If an SDSIO interface or protocol error occurs, the function returns SDS_ERROR_IO.

Parameters:

• id sdsioId_t handle to SDSIO 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 SDS_EOS (see Function Return Codes)

---

function sdsioUninit

Un-initialize SDSIO interface.

int32_t sdsioUninit (
    void
) 

Description:

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

Returns:

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

---

function sdsioWrite

Write data to SDSIO stream.

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

Description:

Attempts to write up to buf_size bytes from the memory pointed to buf to the SDSIO stream identified by id. If the interface is a local file system, data is written directly to the file. For communication channels such as Ethernet, USB or USART, the SDSIO-Client sends a write command (SDSIO_CMD_WRITE) along with the data to the SDSIO-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 SDS_ERROR_TIMEOUT.
• If an SDIO interface or protocol error occurs, the function returns SDS_ERROR_IO.

Parameters:

• id sdsioId_t handle to SDSIO 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)

---

---