Storage Backed Queue

This is the Storage Backed Queue implementation with fixed size of user initialization.
The main buffer structure variable and the internal data buffer both should be declared on the application side and the pointers of the variables are used in the module.

Usage

All API functions have the first argument as the buffer instance.

Internal data buffer size and pointer are initialized with module init function.

Module read and module write functions are used to read/write data bytes.

Other API functions to return the status of buffer whether empty or full.

Return codes of API functions are defined in header file.

Storage backed Queue calls
Function	Description
rs_sb_queue_init	Function to initialize the storage backed queue
rs_sb_queue_push_data	Function to push the data into the storage backed queue
rs_sb_queue_pull_data	Function to pull the data from the storage backed queue
rs_sb_queue_peek_data	Function to get top of the data from the storage backed queue
rs_sb_queue_get_available_messages	Function to get remaining messages
rs_remove_invalid_file_from_sb_queue	Function to remove invalid file from the storage backed queue
sb_queue_is_file_exist	Function to find the file exist or not
sb_queue_backup_to_file	Function to store the data to the file
rs_sb_queue_flush	Function to reset the elements of the storage backed queue structure

Error Code

Every API’s for the message queue module returns some success or failure values. Please refer below section,

RAPIDSEA ERROR CODES

Example Demo

Please refer below section,

Storage Backed Queue Demo

Message Queue Header Details

Documentation from the relevant header as follows:

Storage Backed Queue Specific APIs.

Defines macros and functions specific to Storage Backed Queue functionality

Author: Embien RAPIDSEA Team
Copyright: Embien Technologies India Pvt. Ltd.

Defines

RS_SB_QUEUE_FILE_DATA_BLOCK_SIZE: SBQ Data block size

RS_SB_QUEUE_SD_CARD_INTERFACE

RS_SB_QUEUE_FLASH_INTERFACE

RS_SB_QUEUE_USB_DIR

RS_SB_QUEUE_MAX_PATH_SIZE: sb_queue max file name

RS_SB_QUEUE_MAX_FILE_NAME: sb_queue max file name

RS_SB_QUEUE_FILE_SIZE

RS_SB_QUEUE_FILE_APPEND_MODE

RS_SB_QUEUE_FILE_INDEX_OFFSET

Typedefs

typedef struct tag_rs_sb_queue_config rs_sb_queue_config_t

typedef rs_ret_val_t *sbq_backup_data(struct tag_rs_sb_queue_instance *ptr_sb_queue)

typedef rs_ret_val_t *sbq_restore_data(struct tag_rs_sb_queue_instance *ptr_sb_queue)

typedef rs_ret_val_t *ptr_fn_read_seq(struct tag_rs_sb_queue_instance *ptr_sb_queue, uint32_t u32_file_index, uint32_t *ptr_seq_num)

typedef rs_ret_val_t *ptr_fn_write_seq(struct tag_rs_sb_queue_instance *ptr_sb_queue, uint32_t u32_file_index, uint32_t u32_seq_num, uint32_t u32_num_block_skip)

typedef struct tag_rs_sb_queue_instance rs_sb_queue_instance_t

Functions

rs_ret_val_t rs_sb_queue_set_sector_config(rs_sb_queue_config_t *ptr_sb_queue_config, uint16_t u16_physical_sector_size, uint16_t u16_logical_sector_size, uint32_t u32_total_sector_count, uint32_t u32_sector_start_count)

rs_ret_val_t rs_sb_queue_open(rs_sb_queue_instance_t *ptr_sb_queue_instance, rs_sb_queue_config_t *ptr_sb_queue_config)

Opens an SB queue instance and initializes its configuration.

This function initializes the provided SB queue instance with settings from the configuration structure. It sets the initial file indices, offsets, and buffers, and attempts to obtain a handle for the SB queue. If the handle retrieval fails, it attempts to create the necessary directory if using FATFS.

Parameters:

ptr_sb_queue_instance – [inout] Pointer to the SB queue instance to be opened.
ptr_sb_queue_config – [in] Pointer to the configuration structure for the SB queue.

Returns:

Returns a handle to the SB queue on success, or an error code if initialization fails.

rs_ret_val_t rs_sb_queue_close(rs_handle_t handle)

Closes an SB queue instance and performs necessary cleanup.

This function retrieves the SB queue instance associated with the given handle, checks if there is any data that needs to be backed up, and then marks the queue as uninitialized. Finally, it releases the handle associated with the SB queue.

Parameters:: handle – [in] The handle of the SB queue instance to be closed.
Returns:: Possible return values include RS_ERR_OK for success, or error codes

rs_ret_val_t rs_sb_queue_push_data(rs_handle_t handle, void *ptr_data, uint32_t u32_data_size)

Pushes data into the SB queue associated with the given handle.

This function adds data to the write buffer of the SB queue. It manages the write offsets and ensures that the data conforms to the expected format with headers and footers. If the write buffer reaches its maximum size, the data is backed up to a file. It also handles cases where the buffer needs to be shifted to accommodate new data.

Parameters:

handle – [in] The handle of the SB queue instance where the data will be pushed.
ptr_data – [in] Pointer to the data to be pushed into the queue.
u32_data_size – [in] The size of the data to be pushed.

Returns:

Returns the status of the push operation, or RS_ERR

rs_ret_val_t rs_sb_queue_pull_data(rs_handle_t handle, void *ptr_data, uint32_t *ptr_max_data_size)

rs_ret_val_t rs_sb_queue_peek_data(rs_handle_t handle, void *ptr_data, uint32_t *ptr_max_data_size)

Retrieves data from the SB queue without removing it.

This function attempts to pull data from the SB queue associated with the given handle. It first checks if there is data available to read. If the queue is empty, it returns an error. If data is available, it validates the data and copies it into the provided buffer.

Parameters:

handle – [in] The handle of the SB queue instance from which to peek data.
ptr_data – [out] Pointer to the buffer where the peeked data will be stored.
ptr_max_data_size – [inout] Pointer to a variable that indicates the maximum size of the buffer.

Returns:

Returns the status of the peek operation, or RS_ERR

rs_ret_val_t rs_sb_queue_get_available_messages(rs_handle_t handle, void *ptr_data, uint32_t u32_read_size)

rs_ret_val_t rs_remove_invalid_file_from_sb_queue(rs_handle_t handle)

rs_ret_val_t rs_sb_queue_is_available(rs_handle_t handle)

Check if the queue is available.

Checks if there is available data in the SB queue.

This function checks if the queue available for the given handle.

It checks the initialized state of the queue and the indices to ascertain the availability of data.

Parameters:

handle – [in] - Handle to the queue.
handle – [in] The handle of the SB queue instance to check for availability.

Returns:

RS_ERR_NULL_POINTER if the queue handle is invalid. 1 if the queue is available. 0 if the queue is not available.

Returns:

- 1 if data is available in the queue,

0 if no data is available,
RS_ERR_NULL_POINTER if the provided handle is invalid or NULL,
RS_ERR if the queue has not been initialized.

rs_ret_val_t rs_sb_queue_flush(rs_handle_t handle)

void rs_sb_queue_load_from_sdcard_storage(rs_handle_t handle)

rs_ret_val_t rs_sb_update_file_index(rs_handle_t handle)

rs_ret_val_t rs_sb_queue_get_interface(rs_handle_t handle)

uint32_t rs_queue_get_available_record_count(rs_handle_t handle)

uint32_t rs_queue_get_available_data_size(rs_handle_t handle)

rs_ret_val_t rcb_sb_queue_write_push_data(rs_handle_t handle, void *ptr_data, uint32_t u32_data_size)

struct tag_rs_sb_queue_config

Public Members

uint8_t u8_sb_interface_type: indicate the interface type

uint32_t u32_file_count: File count

uint32_t u32_file_max_size: File maximum size

uint32_t u32_file_block_size: File block size

uint8_t u8_allow_overflow

uint16_t u16_physical_sector_size: Physical sector size

uint16_t u16_logical_sector_size: Logical sector size

uint32_t u32_total_sector_count: Totla number of logical sectors

uint32_t u32_sector_start_count: Logical sector offset

rs_sd_card_info_t *ptr_sd_card_info

struct tag_rs_sb_queue_instance

Public Members

rs_sb_queue_config_t *ptr_sb_queue_config: pointer to the sb queue

int32_t push_write_offset: Push write offset

int32_t pull_write_offset: Pull write offset

int32_t push_read_offset: Push read offset

int32_t pull_read_offset: Push read offset

uint8_t write_data_buf[RS_SB_QUEUE_FILE_SIZE]: Write data buffer

uint8_t read_data_buf[RS_SB_QUEUE_FILE_SIZE]: Read data buffer

int32_t s32_file_index_first: File index to read data from next

int32_t s32_bkp_file_index_first: File index to read data from next

int32_t s32_file_index_last: File index that should be written next

uint32_t u32_sub_write_data_len: write data length

uint8_t *ptr_sub_read_data_len: read data length

uint32_t u32_read_file_size

rs_ret_val_t ext_flash_handle: NOR flash handle

uint32_t u32_performance_hit

sbq_backup_data *ptr_fn_backup_data

sbq_restore_data *ptr_fn_restore_data

sbq_backup_data *ptr_fn_read_seq

sbq_backup_data *ptr_fn_write_seq

uint16_t u16_num_sectors_per_block

uint32_t u32_seq_counter