Difference between revisions of "OCEOSmp/blank"

From wiki
Jump to navigation Jump to search
(Replaced content with "== Next Section == ===<span style="color:#0000ff">blank_function()</span>=== <blockquote style="border-left-style: none;"> <span style="color:#1b7ac2">'''Header File'''...")
Tag: Replaced
Line 1: Line 1:
== Next Section ==
== Next Section ==


===<span style="color:#0000ff">oceos_timed_output_add()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''timed_action.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function adds a timed action to the timed action queue. It writes a value to an address at a specified system time. An optional mask can be applied so that only those bits are changed.
The action types are WRITE_ACTION, RMW_ACTION. WRITE_ACTION writes the value to the address. RMW_ACTION reads the values at the address and modifies the bits specified by the mask and value.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Add output action to timed actions queue :
*  1. Create timed output action
*  2. Stop timer
*  3. Add action to action_array
*  4. Start timer or execute if time is right
*
* Returns timed action ID that can be used later to remove
* if need by oceos_timed_output_remove
*
* @param enum ACTION_TYPE action_type  Action type
* @param U64_t act_time                System time at which action should be done
* @param U32_t before_time            Forward tolerance for time
* @param U32_t after_time              Backward tolerance for time
* @param adrs_t address                Output address
* @param U32_t value                  Output value
* @param U32_t mask                    Output mask
* @param U32_ *ta_index                Pointer to store timed action index
*
* @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 inialisation is not done and tried to be used
*          ERR_TA_PTR_BAD              Timed action pointer is null
*          ERR_TA_TYPE_WRONG          Timed action type is wrong
*          ERR_TOO_LATE                Timed action time is too late
*          ERR_SYS_BUSY                Timed action guard failed to acquire
*          ERR_TA_Q_FULL              Timed action queue is full
*          ERR_TA_START_FAILED        Timed action execute failed; See log
*/
S32_t oceos_timed_output_add(
    const enum ACTION_TYPE action_type,// Action type
    U64_t act_time,                    // system time at which action should be done
    U32_t before_time,                // forward tolerance for time
    U32_t after_time,                  // backward tolerance for time
    const adrs_t address,              // output address
    const U32_t value,                // output value
    const U32_t mask,                  // output mask
    U32_t *ta_index                    // Pointer to store timed action index
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
| enum ACTION_TYPE action_type  || Action type
|-
| U64_t act_time                || System time at which action should be done
|-
| U32_t before_time            || Forward tolerance for time
|-
| U32_t after_time              || Backward tolerance for time
|-
| adrs_t address                || Output address
|-
| U32_t value                  || Output value
|-
| U32_t mask                    || Output mask
|-
| U32_ *ta_index                || Pointer to store timed action index
|-
| param || parameter to function
|}
<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"
|-
| Error bit  !! Description
|-
| 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 inialisation is not done and tried to be used
|-
| ERR_TA_PTR_BAD              || Timed action pointer is null
|-
| ERR_TA_TYPE_WRONG          || Timed action type is wrong
|-
| ERR_TOO_LATE                || Timed action time is too late
|-
| ERR_SYS_BUSY                || Timed action guard failed to acquire
|-
| ERR_TA_Q_FULL              || Timed action queue is full
|-
| ERR_TA_START_FAILED        || Timed action execute failed; See log
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
#define OUTPUT_TIMED_VAL    0xDEADBEEF
#define OUTPUT_TIMED_MASK  0x1000001
#define OUTPUT_TIME        0xfffff
#define OUTPUT_TIME_FW      0x1000
#define OUTPUT_TIME_BW      0x1000
static U32_t test_data[16] = { 0 };
S32_t status;
...
// Write OUTPUT_TIMED_VAL to test_data[0] at 0xfffff time units from now with a tolerance of 0x1000 before and after the specified time 
status = oceos_timed_output_add(
                                      WRITE_ACTION,
                                      OUTPUT_TIME,
                                      OUTPUT_TIME_FW,
                                      OUTPUT_TIME_BW,
                                      (adrs_t) &test_data[0],
                                      OUTPUT_TIMED_VAL,
                                      0,
                                      &timed_action_index));
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_timed_jobs_number()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''timed_action.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function returns the number of jobs on the timed actions queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Get number of Jobs (request to start the task) waiting on timed action queue.
* These jobs are added by oceos_task_timed_start() or
* oceos_dataq_read_restart_timeout when data is not available (NULL) or
* oceos_sem_wait_restart_timeout when counting semaphore is 0
*
* @param total_jobs    Pointer to store total jobs number waiting on timed action Q
* @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 inialisation is not done and tried to be used
*          ERR_TA_PTR_BAD              Timed action pointer is null
*/
S32_t oceos_timed_jobs_number(U32_t *total_jobs);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
| Parameter !! Description
|-
| total_jobs || s32_t pointer to store total jobs number waiting on timed action Q
|}
<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"
|-
| Error bit  !! Description
|
| 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 inialisation is not done and tried to be used
|-
| ERR_TA_PTR_BAD              || Timed action pointer is null
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_timed_jobs_remove()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''timed_action.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function removes the specified timed action from the queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Remove job from timed action queue
* When task started using oceos_task_timed_start(),
* this directive requires pointer to store ID
* of job that put on the timed action queue.
* This job can be removed later using this directive and stored job ID.
*
* @param U32_t job_id  Job 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_TA_NOT_INIT            Timed action intialisation is not done and tried to be used
*          ERR_TA_PTR_BAD              Timed action pointer corrupt
*          ERR_ID_WRONG                Job ID is wrong
*          ERR_TA_NOT_FOUND            Timed action ID not found for action with job_id or removed already
*          ERR_SYS_BUSY                Failed to acquire timed action guard
*          WARN_TA_Q_EMPTY            Timed action queue is empty
*          ERR_TA_START_FAILED        Timed action execute failed; See log
*/
S32_t  oceos_timed_jobs_remove(
    U32_t job_id                            // Job ID
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
| Parameter !! Description
|-
| job_id || U32_t Job ID to be removed from the timed actions 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"
|-
| Error bit  !! Description
|
| 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
|-
| ERR_TA_PTR_BAD              || Timed action pointer corrupt
|-
| ERR_ID_WRONG                || Job ID is wrong
|-
| ERR_TA_NOT_FOUND            || Timed action ID not found for action with job_id or removed already
|-
| ERR_SYS_BUSY                || Failed to acquire timed action guard
|-
| WARN_TA_Q_EMPTY            || Timed action queue is empty
|-
| ERR_TA_START_FAILED        || Timed action execute failed; See log
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_timed_jobs_reset()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''timed_action.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function removes all jobs from timed actions queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Remove all jobs (requests to start a task) from timed actions queue
* These jobs were added by oceos_task_timed_start() or
* oceos_dataq_read_restart_timeout when data is not available (NULL) or
* oceos_sem_wait_restart_timeout when counting semaphore is 0
*
* @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
*          ERR_TA_PTR_BAD              Timed action pointer is null
*          ERR_SYS_BUSY                Failed to acquire timed action guard
*          WARN_TA_Q_EMPTY            Timed action queue is empty
*          ERR_TA_NOT_FOUND            Timed action index not found
*          ERR_TA_START_FAILED        Timed action execute failed; See log
*/
S32_t  oceos_timed_jobs_reset(void);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
There are no input parameters to this function
<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"
|-
| Error bit  !! Description
|
| 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
|-
| ERR_TA_PTR_BAD              || Timed action pointer is null
|-
| ERR_SYS_BUSY                || Failed to acquire timed action guard
|-
| WARN_TA_Q_EMPTY            || Timed action queue is empty
|-
| ERR_TA_NOT_FOUND            || Timed action index not found
|-
| ERR_TA_START_FAILED        || Timed action execute failed; See log
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_timed_output_remove()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''timed_action.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function removes the specified timed output action from timed actions queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Remove timed output action from timed actions queue.
* When action is created, action index should be stored
* to remove if need
*
* @param action_index
* @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
*          ERR_TA_PTR_BAD              Timed action pointer is null
*          ERR_ID_WRONG                Timed action id is wrong
*          ERR_SYS_BUSY                Failed to acquire timed action guard
*          ERR_TA_NOT_FOUND            Timed action index not found
*          ERR_TA_START_FAILED        Timed action execute failed
*/
S32_t oceos_timed_output_remove(
    const U8_t  action_index    // Index in action array, returned when action was created
);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
{| class="wikitable"
|-
| Parameter !! Description
|-
| action_index|| S32_t specifying the timed output action index returned when the timed output was added.
|}
<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"
|-
| Error bit  || Description
|
| 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
|-
| ERR_TA_PTR_BAD              || Timed action pointer is null
|-
| ERR_ID_WRONG                || Timed action id is wrong
|-
| ERR_SYS_BUSY                || Failed to acquire timed action guard
|-
| ERR_TA_NOT_FOUND            || Timed action index not found
|-
| ERR_TA_START_FAILED        || Timed action execute failed
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status;
U8_t action_index;
...
// Remove timed output with specified action_index
status = oceos_timed_output_remove(action_index);
</syntaxhighlight>
</blockquote>
===<span style="color:#0000ff">oceos_timed_output_reset()</span>===
<blockquote style="border-left-style: none;">
<span style="color:#1b7ac2">'''Header File'''</span><br>
'''''timed_action.h'''''<br>
<span style="color:#1b7ac2">'''Description'''</span><br>
This function removes all timed output actions from timed actions queue.
<span style="color:#1b7ac2">'''Prototype'''</span><br>
<syntaxhighlight lang="C">
/**
* Remove all timed output actions from timed actions queue
* These timed output actions were created by oceos_timed_output_add
*
* @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
*          ERR_TA_PTR_BAD              Timed action pointer is null
*          ERR_SYS_BUSY                Failed to acquire timed action guard
*          WARN_TA_Q_EMPTY            Timed action queue is empty
*          ERR_TA_NOT_FOUND            Timed action index not found
*          ERR_TA_START_FAILED        Timed action execute failed; See log
*/
S32_t oceos_timed_output_reset(void);
</syntaxhighlight>
<span style="color:#1b7ac2">'''Parameters'''</span><br>
There are no input parameters to this function.
<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"
|-
| Error bit  || Description
|
| 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
|-
| ERR_TA_PTR_BAD              || Timed action pointer is null
|-
| ERR_SYS_BUSY                || Failed to acquire timed action guard
|-
| WARN_TA_Q_EMPTY            || Timed action queue is empty
|-
| ERR_TA_NOT_FOUND            || Timed action index not found
|-
| ERR_TA_START_FAILED        || Timed action execute failed; See log
|}
<span style="color:#1b7ac2">'''Example Usage'''</span><br>
<syntaxhighlight lang="C">
S32_t status;
...
// Remove all timed outputs from the timed actions queue
status = oceos_timed_output_reset();
</syntaxhighlight>
</blockquote>




Revision as of 14:49, 2 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

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=1659’