Difference between revisions of "OCEOSmp/blank"

From wiki
Jump to navigation Jump to search
 
(30 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Next Section ==
== Next Section ==


===<span style="color:#0000ff">oceos_dataq_create()</span>===
===<span style="color:#0000ff">blank_function()</span>===
<blockquote style="border-left-style: none;">
<blockquote style="border-left-style: none;">


<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''dataq.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function creates a data queue with the specified characteristics.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! 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
|}
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| 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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
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));
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_dataq_write()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''dataq.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function puts a non-null pointer on the specified data queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! Parameter !! Description
|-
| dataq_id || dataq_t with value of Data queue ID
|-
| ptr || void* pointer to application data (non-null pointer)
|}
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| 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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_dataq_read_continue()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''dataq.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function returns a pointer from the specified data queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! 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
|}
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| 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)
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status;
char *data_ptr;
...
// Read pointer from data queue s_2
status = oceos_dataq_read_continue(s_2, (void *)data_ptr);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_dataq_read_restart()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''dataq.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
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.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* 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
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
! 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
|}
<span style="color:#1b7ac2">'''Returns'''</span><br>
This function returns an S32_t with a value of OCEOS_SUCCESS (zero) or return code bits set as defined in the table below.
{| class="wikitable"
|-
| 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
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
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);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">blank_function()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''header.h'''''<br>
'''''header.h'''''<br>
Line 351: Line 20:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Parameter !! Description
! Parameter || Description
|-
|-
| param || parameter to function
| param || parameter to function
Line 359: Line 28:
{| class="wikitable"
{| class="wikitable"
|-
|-
| Error bit  !! Description
! Error bit  !! Description
|-
| Error_name|| description
|-
|}
|}


Latest revision as of 16:56, 3 May 2024

Next Section

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
Error_name description

Example Usage

S32_t status, param;
...
// Do xyz
status = oceosmp_blank(param));
Retrieved from ‘https://wiki.ocetechnology.com/mediawiki/index.php?title=OCEOSmp/blank&oldid=1702’