OCEOSmp/blank

Next Section

oceos_dataq_create()

Header File
dataq.h

Description
This function creates a data queue with the specified characteristics.

Prototype

/**
 * Create data queue
 * If use_timeout = TRUE, timed actions must be initialised
 *
 * @param dataq_id      data queue ID
 * @param dataq_size    data queue size
 * @param pen_q_size    pending jobs queue size
 * @param roll_over     whether to roll over when full
 * @param use_timeout   if TRUE, directive oceos_dataq_read_restart_timeout can be used
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_WRONG_CPU_CORE          Executing directive on wrong CPU
 *          ERR_WRONG_PHASE             Called before oceos_init() is done
 *          ERR_TOO_MANY                MAX number of DATAQs already created
 *          ERR_ID_INVALID              DATAQ ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                DATAQ ID >= number of DATAQs
 *          ERR_DQ_ALREADY_ALLOCATED    DATAQ ID already used
 *          ERR_DQ_SIZE_WRONG           DATAQ size outside allowed range 1 to 255
 *          ERR_DQ_PENQ_SIZE_WRONG      DATAQ pending queue size outside allowed range 1 to 253
 *          ERR_DQ_TA_MAX_NUM_REACHED   Number of timed actions exceeds MAX allowed 255,
 *                                      each task on DATAQ pending queue is timed action
 */
S32_t 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	dataq_t data queue ID (number between 0 and 62)
dataq_size	data queue size (max number of pointers than can be added to the queue)
pen_q_size	pending jobs queue size
roll_over	whether to roll over when full (0 => disabled, 1 => enabled)
use_timeout	if TRUE, directive oceos_dataq_read_restart_timeout can be used

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_WRONG_CPU_CORE	Executing directive on wrong CPU
ERR_WRONG_PHASE	Called before oceos_init() is done
ERR_TOO_MANY	MAX number of DATAQs already created
ERR_ID_INVALID	DATAQ ID outside allowed range 0 to 62
ERR_ID_WRONG	DATAQ ID >= number of DATAQs
ERR_DQ_ALREADY_ALLOCATED	DATAQ ID already used
ERR_DQ_SIZE_WRONG	DATAQ size outside allowed range 1 to 255
ERR_DQ_PENQ_SIZE_WRONG	DATAQ pending queue size outside allowed range 1 to 253
ERR_DQ_TA_MAX_NUM_REACHED	Number of timed actions exceeds MAX allowed 255, each task on DATAQ pending queue is timed action

Example Usage

S32_t status;
...
// Create data queue d_3 with size 20, max pending jobs of 10, rollover enabled, timeouts disabled 
status = oceos_dataq_create(d_3, 20, 10, 1, 0));

oceos_dataq_write()

Header File
dataq.h

Description
This function puts a non-null pointer on the specified data queue.

Prototype

/**
 * Puts pointer to the data on data queue.
 * Pointer to the data must not be NULL
 *
 * @param dataq_t dataq_id Data queue ID
 * @param void* data       Non-null pointer to data
 *
 * @return  OCEOS_SUCCESS
 *          WARN_DQ_NOW_FULL            Warning, DATAQ is full now
 *          WARN_JOB_NOT_GUARDED
 *
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              DATAQ ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                DATAQ ID >= number of DATAQs
 *          ERR_DQ_DATA_BAD             Data pointer is null
 *          ERR_SYS_BUSY                Failed to acquire guard
 *          ERR_TOO_MANY                DATAQ is full
 *          ERR_DQ_JOB_ID_WRONG         Job ID of the task on pending queue is wrong
 *          ERR_TA_NOT_FOUND            Timed action index to be removed for job not found
 *          ERR_TA_START_FAILED         Timed action re-start failed after job remove from timed action queue
 */
S32_t oceos_dataq_write(
    dataq_t dataq_id, // data queue ID
    void *data        // non-null pointer to data
);

Parameters

Parameter	Description
dataq_id	dataq_t with value of Data queue ID
ptr	void* pointer to application data (non-null pointer)

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

WARN_DQ_NOW_FULL	Warning, DATAQ is full now
WARN_JOB_NOT_GUARDED
ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	DATAQ ID outside allowed range 0 to 62
ERR_ID_WRONG	DATAQ ID >= number of DATAQs
ERR_DQ_DATA_BAD	Data pointer is null
ERR_SYS_BUSY	Failed to acquire guard
ERR_TOO_MANY	DATAQ is full
ERR_DQ_JOB_ID_WRONG	Job ID of the task on pending queue is wrong
ERR_TA_NOT_FOUND	Timed action index to be removed for job not found
ERR_TA_START_FAILED	Timed action re-start failed after job remove from timed action queue

Example Usage

S32_t status;
char[100] message_in;
...
// Put pointer to message_in on data queue s_2 
status = oceos_dataq_write(s_2, (void *)message_in);

oceos_dataq_read_continue()

Header File
dataq.h

Description
This function returns a pointer from the specified data queue.

Prototype

/**
 * Read data queue
 *
 * @param dataq_t dataq_id  Data queue ID
 * @param void*   data      Pointer to data
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              DATAQ ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                DATAQ ID >= number of DATAQs
 *          ERR_SYS_BUSY                Failed to acquire guard
 *          ERR_DQ_EMPTY                DATAQ empty(count zero)
 */
S32_t oceos_dataq_read_continue(
    dataq_t dataq_id, // data queue ID
    void* *data        // return data
);

Parameters

Parameter	Description
dataq_id	dataq_t with value of Data queue ID
ptr	void* pointer to store returned data queue pointer removed from the queue

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	DATAQ ID outside allowed range 0 to 62
ERR_ID_WRONG	DATAQ ID >= number of DATAQs
ERR_SYS_BUSY	Failed to acquire guard
ERR_DQ_EMPTY	DATAQ empty(count zero)

Example Usage

S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2 
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);

oceos_dataq_read_restart()

Header File
dataq.h

Description
This function returns a pointer from the specified data queue. If the queue is empty, the job is added top the dataq pending queue. The job will be restarted when data is available.

Prototype

/**
 * Read data queue next item.
 * If dataq is empty, task is put on pending Q for dataq and
 * restarted by oceos_dataq_write
 *
 * @param dataq_id Data queue ID
 * @param data     Pointer to return data
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              DATAQ ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                DATAQ ID >= number of DATAQs
 *          ERR_SYS_BUSY                Failed to acquire guard
 *          ERR_DQ_J_START_FROM_TIMOUT  Job started from timeout already, DATAQ empty second time
 *          ERR_FAILED                  Should never return this
 */
S32_t oceos_dataq_read_restart(
    dataq_t dataq_id,    // data queue ID
    void* *data           // pointer to return data
);

Parameters

Parameter	Description
dataq_id	dataq_t with value of Data queue ID
ptr	void* pointer to store returned data queue pointer removed from the queue

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	DATAQ ID outside allowed range 0 to 62
ERR_ID_WRONG	DATAQ ID >= number of DATAQs
ERR_SYS_BUSY	Failed to acquire guard
ERR_DQ_J_START_FROM_TIMOUT	Job started from timeout already, DATAQ empty second time
ERR_FAILED	Should never return this

Example Usage

S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2 with restart when data is available
status = oceos_dataq_read_restart(s_2, (void *)data_ptr);

oceos_dataq_read_restart_timeout()

Header File
dataq.h

Description
This function returns a pointer from the specified data queue. If the queue is empty, the job is added top the dataq pending queue. The job will be restarted either when data is available or the timeout has expired.

Prototype

/**
 * Read data queue next item.
 * If dataq is empty, task is put on pending Q for dataq and
 * restarted by oceos_dataq_write or by timeout if timeout != 0
 * In order to use this feature timed actions must be configured and
 * dataq created with use timeout set to true
 *
 * @param dataq_id          Data queue ID
 * @param data              Pointer to return data
 * @param timeout           Timeout, restart time if no entry, 0 => ignore
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_TA_NOT_INIT             Timed action intialisation is not done and tried to be used; or DATAQ created without timeouts
 *          ERR_ID_INVALID              DATAQ ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                DATAQ ID >= number of DATAQs
 *          ERR_SYS_BUSY                Failed to acquire guard
 *          ERR_DQ_EMPTY                DATAQ empty(count zero)
 *          ERR_DQ_J_START_FROM_TIMOUT  Job started from timeout already, DATAQ empty second time
 *          ERR_TOO_MANY                DATAQ pending queue is full
 *          ERR_FAILED                  Should never return this
 */
S32_t oceos_dataq_read_restart_timeout(
    dataq_t dataq_id,   // data queue ID
    void* *data,         // Pointer to return data
    U64_t timeout       // timeout, restart time if no entry, 0 => ignore
);

Parameters

Parameter	Description
dataq_id	dataq_t with value of Data queue ID
ptr	void* pointer to store returned data queue pointer removed from the queue
timeout	U64_t containing timeout value, restart time if no entry, 0 => ignore

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_TA_NOT_INIT	Timed action intialisation is not done and tried to be used; or DATAQ created without timeouts
ERR_ID_INVALID	DATAQ ID outside allowed range 0 to 62
ERR_ID_WRONG	DATAQ ID >= number of DATAQs
ERR_SYS_BUSY	Failed to acquire guard
ERR_DQ_EMPTY	DATAQ empty(count zero)
ERR_DQ_J_START_FROM_TIMOUT	Job started from timeout already, DATAQ empty second time
ERR_TOO_MANY	DATAQ pending queue is full
ERR_FAILED	Should never return this

Example Usage

S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2 with timeout after 10,000 time units if no data is available
status = oceos_dataq_read_restart_timeout(s_2, (void *)data_ptr, 10000ull);

oceos_dataq_get_size()

Header File
dataq.h

Description
This function returns the number of items on the specified data queue.

Prototype

/**
 * Returns number of items on the data queue with ID
 *
 * @param dataq_id   DATAQ Id
 * @param d_size     Pointer to size holder
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              DATAQ ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                DATAQ ID >= number of DATAQs
 *          ERR_DQ_DATA_BAD             DATAQ size holder pointer is null
 */
S32_t oceos_dataq_get_size(
    dataq_t dataq_id,   // data queue ID
    U32_t *d_size
);

Parameters

Parameter	Description
dataq_id	dataq_t with the ID of the data queue (value between 0 and 62)
d_size	U32_t *d_size pointer to the variable to store the size

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	DATAQ ID outside allowed range 0 to 62
ERR_ID_WRONG	DATAQ ID >= number of DATAQs
ERR_DQ_DATA_BAD	DATAQ size holder pointer is null

Example Usage

S32_t status, d_size;
...
// Get the number of entries on data queue d_0
status = oceos_dataq_get_size(d_0, &d_size);

oceos_dataq_penq_get_size()

Header File
dataq.h

Description
This function returns number of jobs on the specified data queue pending job's queue.

Prototype

/**
 * Returns number of jobs on the dataq pending job's queue
 *
 * @param dataq_id  DATAQ Id
 * @param d_size    Pointer to pending queue size holder
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              DATAQ ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                DATAQ ID >= number of DATAQs
 *          ERR_DQ_DATA_BAD             DATAQ pending size holder pointer is null
 */
S32_t oceos_dataq_penq_get_size(
    dataq_t dataq_id,
    U32_t *d_size
);

Parameters

Parameter	Description
dataq_id	dataq_t with the ID of the data queue (value between 0 and 62)
d_jobs	U32_t *d_jobs pointer to the variable to store the number of jobs on the pending queue

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	DATAQ ID outside allowed range 0 to 62
ERR_ID_WRONG	DATAQ ID >= number of DATAQs
ERR_DQ_DATA_BAD	DATAQ pending size holder pointer is null

Example Usage

S32_t status, d_jobs;
...
// Get the number of jobs the the pending jubs queue for data queue d_1
status = oceos_dataq_penq_get_size(d_1, &d_jobs);

oceos_dataq_clear()

Header File
dataq.h

Description
This function clears the specified data queue including pending jobs for that queue.

Prototype

/**
 * Clears data queue and
 * frees tasks on pending queue
 *
 * @param dataq_t dataq_id Data queue ID
 *
 * @return  OCEOS_SUCCESS
 *          ERR_SYS_FIXED_CORRUPT       System Fixed area corrupt
 *          ERR_SYS_DYN_CORRUPT         System Dynamic area corrupt
 *          ERR_WRONG_PHASE             Directive was called before OCEOS initialisation is finished
 *          ERR_ID_INVALID              DATAQ ID outside allowed range 0 to 62
 *          ERR_ID_WRONG                DATAQ ID >= number of DATAQs
 *          ERR_SYS_BUSY                Failed to acquire guard
 *          ERR_DQ_JOB_ID_WRONG         Job ID of the task on DATAQ pending queue is wrong
 *          ERR_TA_NOT_FOUND            Timed action index to be removed for job not found
 *          ERR_TA_START_FAILED         Timed action re-start failed after job remove from timed action queue
 */
S32_t  oceos_dataq_clear(
    dataq_t dataq_id    // data queue ID
);

Parameters

Parameter	Description
dataq_id	dataq_t with the ID of the data queue to be cleared (value between 0 and 62)

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

ERR_SYS_FIXED_CORRUPT	System Fixed area corrupt
ERR_SYS_DYN_CORRUPT	System Dynamic area corrupt
ERR_WRONG_PHASE	Directive was called before OCEOS initialisation is finished
ERR_ID_INVALID	DATAQ ID outside allowed range 0 to 62
ERR_ID_WRONG	DATAQ ID >= number of DATAQs
ERR_SYS_BUSY	Failed to acquire guard
ERR_DQ_JOB_ID_WRONG	Job ID of the task on DATAQ pending queue is wrong
ERR_TA_NOT_FOUND	Timed action index to be removed for job not found
ERR_TA_START_FAILED	Timed action re-start failed after job remove from timed action queue

Example Usage

S32_t status;
...
// Clear data queue d_1
status = oceos_dataq_penq_get_size(d_1);

blank_function()

Header File
header.h

Description
This function does xyz...

Prototype

S32_t oceosmp_blank(
    U32_t param
);

Parameters

Parameter	Description
param	parameter to function

Returns
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.

Error bit  !! Description

Example Usage

S32_t status, param;
...
// Do xyz
status = oceosmp_blank(param));