OCEOS/oceos timed actions

Timed Actions (Software Timers)

Timed Actions Introduction

Timed actions (Software timers) provide directives to perform actions at a precise time in the future. The currently supported action types are:

• Timed output to memory address or register oceos_timed_output_add()
• Start task at a future time oceos_task_timed_start()
• Timeout for data queue pending job oceos_dataq_read_restart_timeout()
• Timeout for semaphore queue pending job oceos_sem_wait_restart_timeout()

The action types implemented in OCEOS are listed in the enumerated type below. The action types required by the user for oceos_timed_output_add() are WRITE_ACTION and RMW_ACTION. Other action types are provided for information only and are not available to the user.

 enum ACTION_TYPE {
  INVALID_ACION,
  START_JOB_ACTION,         // The job was created with start in future. Put job on ready Q
  DATA_Q_WAIT_ACTION,       // The job is on data_Q pending Q with timeout
  SEM_Q_WAIT_ACTION,        // The job is on semaphore_Q pending Q with timeout
  WRITE_ACTION,             // Write value to address
  RMW_ACTION,               // Read-modify-write Action
 };

OCEOS uses the timed actions system to allow output of a value to an address be scheduled to occur independently of scheduling at a precise system time in microseconds.
Each output action involves (output address, value, type, mask, forward tolerance, backward tolerance, time).
When the timed action interrupt occurs this output and any other actions whose forward timing tolerances include the current time are performed. The backward tolerance allows the output be performed if the current time is later than the requested time by no more than this amount. If set to zero late outputs are not performed. Provision is made for error reporting if the current time is greater than the requested time by more than the allowed tolerance.

The output type and mask allow read-modify-write operations and single bit modifications.

Note

Timed outputs use the timed action subsystem which requires the user to provide some hardware specific timer initialization and handling.

All timed actions are put on timed action queue. This is a priority queue of pending actions and their associated times, with queue priority based on these times. It is linked to a high priority hardware timer which is set to interrupt at the time of the first action on the priority queue. When this interrupt occurs, actions on the queue within a timing tolerance of the current time are carried out and the timer is reset to interrupt at the start time of the earliest remaining action.

If the action is a task start request then at the set time the associated job is transferred to the ready queue, its origin set to timeout, and it is also removed from the pending list of any counting semaphore or data queue on which it is present. If the job is now the highest priority job on the ready queue it is started immediately, otherwise it must wait until that is the case.

If the action is a data output then at the set time it is performed immediately.

Timed Actions Configuration

User must define NUMBER_OF_ACTION_ENTRIES. If NUMBER_OF_ACTION_ENTRIES is zero, timed actions are not used, unless data queues and semaphores are not used with timeout. The example can be found in OCEOS demo projects.
NUMBER_OF_ACTION_ENTRIES defines how many timed outputs and jobs waiting to be started can be on timed actions queue at the same time. Timed outputs can be created by oceos_timed_output_add() and timed jobs start with oceos_task_timed_start().
The MAX value of NUMBER_OF_ACTION_ENTRIES can be 255. It means that timed action queue is limited to 255 entries.

Note

Timed action queue is shared between all timed actions (timed outputs, timed jobs, data queue and semaphore with timeouts).

If user is using data queues and counting semaphores with timeouts, OCEOS updates the number of entries in timed action queue by number of allowed pending jobs for that data queue or counting semaphore.

As described above, timed action queue can accommodate only 255 entries. User by defining NUMBER_OF_ACTION_ENTRIES should take in consideration how many pending jobs for data queue or counting semaphore that is using timeouts.
If application requires to use 10 timed outputs and to start 12 tasks in future NUMBER_OF_ACTION_ENTRIES must be defined to 22 and size of timed action queue is 22 entries. But if it needs to use one data queue oceos_read_restart_timeout() and one counting semaphore oceos_sem_wait_restart_timeout() with timeouts and when data queue is created with oceos_dataq_create() with pen_q_size = 5, and when counting semaphore is created with oceos_sem_create() with pending_q_size = 6, timed action queue is 22+5+6=33 =< 255.

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

SPARC

SPARC Timed Actions Configuration

As described above, timed action functionality requires dedicated timer unit, that user has to provide. User must fill configuration struct, pointer to which is used by OCEOS. The example can be found in OCEOS demo projects.
User must provide start address of timer unit OCEOS_TA_TIMER_ADDRESS.
User must provide index of a timer in timer unit OCEOS_TA_TIMER_INDEX. OCEOS checks if this index is not used by system time already, if the same timer unit is selected SPARC System Time Configurations.
User must provide timer interrupt number OCEOS_TA_INTERRUPT_NUMBER for selected timer.
OCEOS sets __oceos_timed_action_do to handle timer interrupt. This is internal OCEOS function which defined in header file timed_action.h and must be present as shown below.
OCEOS initializes the timer and starts when it is required.

    #define NUMBER_OF_SEMAPHORES 2
    OCEOS_TA_TIMER_CONF oceos_ta_timer_config = {
  .oceos_ta_timer_device_address    = OCEOS_TA_TIMER_ADDRESS,    // Timer Module Start address SPARC
  .oceos_ta_timer_index             = OCEOS_TA_TIMER_INDEX,      // Timer Index within timer module [1...n] 
  .oceos_ta_timer_interrupt_number  = OCEOS_TA_INTERRUPT_NUMBER, // Timer Interrupt number used to enable interrupt in Interrupt Controller 
  .oceos_ta_isr_handler             = &__oceos_timed_action_do,  // DO NOT CHANGE. Must be __oceos_timed_action_do;
};
OCEOS_TA_TIMER_CONF *oceos_ta_timer_configurations = &oceos_ta_timer_config;

API Functions

API Functions

Directive	Description	main	task	IRQ handler
oceos_timed_jobs_number()	Get number of Jobs waiting on timed action queue		*	*
oceos_timed_jobs_remove()	Remove job from timed action queue		*	*
oceos_timed_jobs_reset()	Remove all jobs		*	*
oceos_timed_output_add()	Add output action to timed actions queue		*	*
oceos_timed_output_number()	Get number of timed output actions		*	*
oceos_timed_output_remove()	Remove timed output action from timed actions queue		*	*
oceos_timed_output_reset()	Remove all timed output actions		*	*