Difference between revisions of "OCEOSmp/blank"

Revision as of 13:31, 2 May 2024

Next Section

oceos_timed_output_add()

Header File
timed_action.h

Description
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.

Prototype

/**
 * 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
);

Parameters

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

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

Example Usage

#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));

oceos_timed_jobs_number()

Header File
timed_action.h

Description
This function returns the number of jobs on the timed actions queue.
Prototype
/**
 * 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);
Parameters

Parameter !! Description

total_jobs s32_t pointer to store total jobs number waiting on timed action Q

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

Example Usage
S32_t status, no_of_jobs;
...
// Get the number of jobs on the timed actions queue
status = oceos_timed_jobs_number(&no_of_jobs);

oceos_timed_jobs_remove()

Header File
timed_action.h

Description
This function removes the specified timed action from the queue.
Prototype
/**
 * 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
);
Parameters

Parameter !! Description

job_id U32_t Job ID to be removed from the timed actions 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.

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

Example Usage
S32_t status, job_id;
...
// Remove job_id from the timed actions queue
status = oceos_timed_jobs_remove(job_id);

oceos_timed_jobs_reset()

Header File
timed_action.h

Description
This function removes all jobs from timed actions queue.
Prototype
/**
 * 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);
Parameters
There are no input parameters to this 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 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

Example Usage
S32_t status;
...
// Remove all jobs from the timed actions queue
status = oceos_timed_jobs_reset(job_id);

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));