OCEOS/oceos inter-task communication/dataq

From wiki
Jump to navigation Jump to search

Data Queue

Data Queue Introduction

These are FIFO queues of non-null void pointers ordered by arrival time. Each queue has an associated pending jobs queue, and two associated atomic operations, read and write. A size operation gives the number of pointers on the queue, and the data queue create operation sets the maximum size of the queue.

The read operation returns the first pointer on the queue unless the queue is empty. Unlike many other OS, the job that performs the read operation does not block if the queue is empty. Instead OCEOS provides three options for the read operation to determine what should happen in that case:

A pointer is added to the queue by write. All jobs on the pending list are moved to the ready queue and also removed from the timed actions queue if present.

The pending queue order of jobs with the same priority is preserved in the transfer. The scheduler is then activated and may pre-empt the current executing job.

In case the queue is full, the new entry can be dropped or the oldest entry overwritten, depending on an option chosen when the data queue is created. An appropriate status is returned and a log entry is made if the new entry is dropped.

Note

If timeouts are used with data queues the hardware specific timer initialization and handling must be set up by the developer please see here.

Data Queue Configuration

User must define NUMBER_OF_DATAQS. If NUMBER_OF_DATAQS is zero, data queues are not used. The example can be found in OCEOS demo projects.
User must create defined number of data queues before calling oceos_init_finish()

    #define NUMBER_OF_DATAQS 2
    /*
     * Create the application configuration structure
     */
    struct application_configuration           app_config = {0};
    app_config.number_of_data_queues         = NUMBER_OF_DATAQS;

API Functions

API Functions
Directive Description main task IRQ handler
oceos_dataq_create() Create data queue *
oceos_dataq_write() Puts pointer to the data on data queue. * *
oceos_dataq_read_continue() Read data queue next item. *
oceos_dataq_read_restart() Read data queue next item. *
oceos_dataq_read_restart_timeout() Read data queue next item. *
oceos_dataq_get_size() Returns number of items on the data queue * *
oceos_dataq_penq_get_size() Returns number of jobs on the dataq pending job's queue * *
oceos_dataq_clear() Clears data queue and frees tasks on pending queue * *

oceos_dataq_create()

Header File
dataq.h

Description
Create data queue.
This directive creates the specified data queue with specified queue size and pending jobs queue size. Roll-over on the queue can also be enabled/disabled. Roll-over means that if the queue is full new entries will overwrite the oldest ones on the queue. If use_timeout = TRUE, timed actions must be initialized, please see here

Prototype

enum DIRECTIVE_STATUS   oceos_dataq_create(
    dataq_t dataq_id,            // data queue ID
    U16_t dataq_size,            // data queue size
    U16_t pen_q_size,            // pending jobs queue size
    BOOLE_t roll_over,           // whether to roll over when full
    BOOLE_t use_timeout          // whether timeout is used oceos_dataq_read_restart_timeout
);

Parameters

Parameter Description
dataq_id Data queue ID
dataq_size Data queue size
pen_q_size Pending jobs queue size
roll_over Whether to roll over when full
use_timeout Whether timeout is used in oceos_dataq_read_restart_timeout()

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS Description
NOT_CONFIGURED System meta pointer is NULL
INCORRECT_STATE Init meta pointer is NULL
INVALID_ID Dataq ID is out of range
TOO_MANY Dataq ID exceeds dataq number in configuration file
INVALID_NAME Dataq ID is not available (already in use)
INVALID_NUMBER Dataq_size or pen_q_size is out of range
INVALID_SIZE Dataq pen_q_size <= 0
SUCCESSFUL All is OK

Example Usage

enum DATAQ_NAME{
    d_apple,
    d_orange,
};
 enum DIRECTIVE_STATUS status;
 status = oceos_dataq_create(d_apple, 13, 4, 0, TRUE);
 if(SUCCESSFUL != status){
    // Handle ERROR
  }   // if

oceos_dataq_write()

Header File
dataq.h

Description
Puts pointer to the data on data queue. Pointer to the data must not be NULL.

Prototype

enum DIRECTIVE_STATUS   oceos_dataq_write(
    dataq_t dataq_id,       // data queue ID
    void* data              // non-null pointer to data
);

Parameters

Parameter Description
dataq_id Data queue ID
data Non-null pointer to data

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS Description
NOT_CONFIGURED System meta pointer is NULL
INCORRECT_STATE Init meta pointer is NULL
INVALID_ID Dataq ID is out of range
INVALID_ADDRESS Data pointer is NULL
TOO_MANY Dataq is full or

Ready Q is full (check system log)

INTERNAL_ERROR Wrong task index on pending Q or

Failed to remove task from timed action Q if timeout is used

SUCCESSFUL All is OK

Example Usage

enum DATAQ_NAME{
    d_apple,
    d_orange,
};
char *mes = "OCEOS";
enum DIRECTIVE_STATUS status;
status = oceos_dataq_write(d_apple, mes);
if(SUCCESSFUL != status){
    // Handle ERROR
}

oceos_dataq_read_continue()

Header File
dataq.h

Description
Read data queue, if empty it returns NULL.

Prototype

void*                   oceos_dataq_read_continue(
    dataq_t dataq_id            // data queue ID
);

Parameters

Parameter Description
dataq_id Data queue ID

Returns
This function returns void*.

void* Description
NULL System check ERROR (check system log)
data Pointer to the data

Example Usage

enum DATAQ_NAME{
    d_apple,
    d_orange,
};
void* data;
data = oceos_dataq_read_continue(d_apple);
if(NULL == data){
    // Handle ERROR
}

oceos_dataq_read_restart()

Header File
dataq.h

Description
Read data queue next item. If data queue is empty, task is put on pending queue for this data queue and restarted by oceos_dataq_write(). Restarted task will lose any data stored in variables on the stack so it may be necessary for the application to store such data elsewhere so that it is available when the task restarts.

Prototype

void*                   oceos_dataq_read_restart(
    dataq_t dataq_id            // data queue ID
);

Parameters

Parameter Description
dataq_id Data queue ID

Returns
This function returns void*.

void* Description
NULL System check ERROR or

Task was originally started from data queue pending queue or data queue pending queue is full (check system log)

data Pointer to the data

Example Usage

enum DATAQ_NAME{
    d_apple,
    d_orange,
};
void* data;
data = oceos_dataq_read_restart(d_apple);
if(NULL == data){
    // Handle ERROR
}

oceos_dataq_read_restart_timeout()

Header File
dataq.h

Description
Read data queue next item. This directive returns the oldest pointer from the data queue. If the queue is empty the task is put on the pending queue to be restarted when new data is available on the queue by oceos_dataq_write() or by timeout if timeout parameter is != 0. A 64-bit timeout in microseconds can be set, after which the task will be removed from the pending queue and NULL will be returned. If a timeout value of zero is passed then the job will remain on the pending queue until a data queue pointer is available.

Note

In order to use timeouts, timed actions must be configured, please see here and data queue is created with timeout parameter set to TRUE.

Restarted task will lose any data stored in variables on the stack so it may be necessary for the application to store such data elsewhere so that it is available when the task restarts.

Prototype

void*                   oceos_dataq_read_restart_timeout(
    dataq_t dataq_id,            // data queue ID
    U64_t timeout                // timeout, restart time if no entry, 0 => ignore
);

Parameters

Parameter Description
dataq_id Data queue ID
timeout Timeout, restart time if no entry, 0 => ignore

Returns
This function returns void*.

void* Description
NULL System check ERROR or

Task was originally started from data queue pending queue or timeout data queue pending queue is full (check system log)

Data Pointer to the data

Example Usage

enum DATAQ_NAME{
    d_apple,
    d_orange,
};
void* data;
data = oceos_dataq_read_restart_timeout(d_apple, 10000);
if(NULL == data){
    // Handle ERROR
}

oceos_dataq_get_size()

Header File
dataq.h

Description
Returns number of items on the data queue with ID.

Prototype

int                     oceos_dataq_get_size(
    dataq_t dataq_id            // data queue ID
);

Parameters

Parameter Description
dataq_id data queue ID

Returns
This function returns int.

int Description
-1 ERROR
>= 0 Number of Items on data queue with ID

Example Usage

enum DATAQ_NAME{
    d_apple,
    d_orange,
};
int count;
count = oceos_dataq_get_size(d_apple);
if(-1 == count){
    // Handle ERROR
}

oceos_dataq_penq_get_size()

Header File
dataq.h

Description
Returns number of jobs on the data queue pending job's queue.

Prototype

int                     oceos_dataq_penq_get_size(
    dataq_t dataq_id            // data queue ID
);

Parameters

Parameter Description
dataq_id Data queue ID

Returns
This function returns int.

int Description
-1 ERROR
>= 0 Number of Items on data queue with ID

Example Usage

enum DATAQ_NAME{
    d_apple,
    d_orange,
};
int count;
count = oceos_dataq_penq_get_size(d_apple);
if(-1 == count){
    // Handle ERROR
}

oceos_dataq_clear()

Header File
dataq.h

Description
Clears data queue and frees tasks on pending queue.

Prototype

enum DIRECTIVE_STATUS  oceos_dataq_clear(
    dataq_t dataq_id            // data queue ID
);

Parameters

Parameter Description
dataq_id Data queue ID

Returns
This function returns enum DIRECTIVE_STATUS.

enum DIRECTIVE_STATUS Description
NOT_CONFIGURED System meta pointer is NULL
INCORRECT_STATE Init meta pointer is NULL
INVALID_ID Data queue ID is out of range
INTERNAL_ERROR Wrong task index on pending queue or

Failed to remove task from timed action queue if timeout is used

SUCCESSFUL All is OK

Example Usage

enum DATAQ_NAME{
    d_apple,
    d_orange,
};
enum DIRECTIVE_STATUS status;
status = oceos_dataq_clear(d_apple);
if(SUCCESSFUL != status ){
    // Handle ERROR
}