CHAPTER 10 TIME MANAGEMENT FUNCTIONS
The RI600PX's time management function provides methods to implement time-related processing (Timer Operations: Delay Task, Time-out, Cyclic Handlers, Alarm Handlers and System Time) by using base clock timer interrupts that occur at constant intervals, as well as a function to manipulate and reference the system time.
After initialization to 0 by the Kernel Initialization Module (vsta_knl, ivsta_knl), the system time is updated based on the base clock interval defined by Denominator of base clock interval time (tic_deno) and Denominator of base clock interval time (tic_deno) in System Information (system) when creating a system configuration file.
To realize the time management function, the RI600PX uses interrupts that occur at constant intervals (base clock timer interrupts).
When a base clock timer interrupt occurs, processing related to the RI600PX time (system time update, task time-out/delay, cyclic handler activation, alarm handler activation, etc.) is executed.
Basically, either of channel 0-3 of the compare match timer (CMT) implemented in the MCU is used for base clock time. The channel number is specified by Selection of timer channel for base clock (timer)in Base Clock Interrupt Information (clock). in the system configuration file.
The hardware initialization to generate base clock timer interrupt is separated as user-own coding module. For details, refer to "10.9 Base Clock Timer Initialization Routine (_RI_init_cmt_knl( ))"
It is desirable to set 1 msec for the occurrence interval of base clock timer interrupts, but it may be difficult depending on the target system performance (processing capability, required time resolution, or the like).
In such a case, the occurrence interval of base clock timer interrupt can be specified by Denominator of base clock interval time (tic_deno) and Denominator of base clock interval time (tic_deno) in System Information (system) when creating a system configuration file.
By specifying the base clock interval, processing regards that the time equivalent to the base clock interval elapses during a base clock timer interrupt.
The RI600PX's timer operation function provides Delay Task, Time-out, Cyclic Handlers, Alarm Handlers and System Time,as the method for realizing time-dependent processing.
Delayed task that makes the invoking task transit from the RUNNING state to the WAITING state during the interval until a given length of time has elapsed, and makes that task move from the WAITING state to the READY state once the given length of time has elapsed.
Time-out is the operation that makes the target task move from the RUNNING state to the WAITING state during the interval until a given length of time has elapsed if the required condition issued from a task is not immediately satisfied, and makes that task move from the WAITING state to the READY state regardless of whether the required condition is satisfied once the given length of time has elapsed.
tslp_tsk, twai_sem, twai_flg, tsnd_dtq, trcv_dtq, trcv_mbx, tloc_mtx, tsnd_mbf, trcv_mbf, tget_mpf, tget_mpl
The cyclic handler is a routine dedicated to cycle processing that is activated periodically at a constant interval (activation cycle).
The RI600PX handles the cyclic handler as a "non-task (module independent from tasks)". Therefore, even if a task with the highest priority in the system is being executed, the processing is suspended when a specified activation cycle has come, and the control is passed to the cyclic handler.
The following shows the basic form of cyclic handlers. The extended information defined at creating the cyclic handler is passed to the exinf.
Note These statements are unnecessary for the cyclic handler which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
- Service call
The RI600PX handles the cyclic handler as a "non-task".
The cyclic handler can issue service calls whose "Useful range" is "Non-task".
The RI600PX handles the cyclic handler as a "non-task".
The cyclic handler can issue service calls whose "Useful range" is "Non-task".
Note If a service call (isig_sem, iset_flg, etc.) which causes dispatch processing (task scheduling processing) is issued in order to quickly complete the processing in the cyclic handler during the interval until the processing in the cyclic handler ends, the RI600PX executes only processing such as queue manipulation, counter manipulation, etc., and the actual dispatch processing is delayed until a return instruction is issued by the cyclic handler, upon which the actual dispatch processing is performed in batch.
1 ) Creation by the system configuration file
The static API cyclic_hand[] described in the system configuration file creates a cyclic handler.
Refer to 20.19 Cyclic Handler Information (cyclic_hand[]) for the details of cyclic_hand[].
The static API cyclic_hand[] described in the system configuration file creates a cyclic handler.
Refer to 20.19 Cyclic Handler Information (cyclic_hand[]) for the details of cyclic_hand[].
2 ) Creation by cre_cyc or acre_cyc
The cre_cyc creates a cyclic handler with cyclic handler ID indicated by parameter cycid according to the content of parameter pk_ccyc.
The acre_cyc creates a cyclic handler according to the content of parameter pk_ccyc, and returns the created cyclic handler ID.
The information specified is shown below.
The cre_cyc creates a cyclic handler with cyclic handler ID indicated by parameter cycid according to the content of parameter pk_ccyc.
The acre_cyc creates a cyclic handler according to the content of parameter pk_ccyc, and returns the created cyclic handler ID.
The information specified is shown below.
These service calls can be called from tasks that belong to Trusted Domain.
The following describes an example for coding acre_cyc as a representative.
The following describes an example for coding acre_cyc as a representative.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ extern void Cychdr1(VP_INT exinf); #pragma task Task1 /*Refer to note*/ void Task1 (VP_INT exinf); /*Refer to note*/ void Task1 (VP_INT exinf) { ER cycid; /*Declares variable*/ T_CCYC pk_ccyc = { /*Declares and initializes variable*/ TA_STA, /*Cyclic handler attribute (cycatr)*/ 0, /*Extended information (exinf)*/ (FP)Cychdr1, /*Start address (cychdr)*/ 10, /*Activation cycle (cyctim)*/ 2 /*Activation phase (cycphs)*/ }; /* ......... */ cycid = acre_cyc ( &pk_ccyc ); /*Create cyclic handler/ /* ......... */ } |
Note These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
- del_cyc
This service call deletes the cyclic handler specified by parameter cycid.
This service call can be called from tasks that belong to Trusted Domain.
The following describes an example for coding this service call.
This service call deletes the cyclic handler specified by parameter cycid.
This service call can be called from tasks that belong to Trusted Domain.
The following describes an example for coding this service call.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note*/ void Task1 (VP_INT exinf); /*Refer to note*/ void Task1 (VP_INT exinf) { ID cycid = 8; /*Declares and initializes variable*/ /* ......... */ ercd = del_cyc ( cycid ); /*Delete cyclic handler*/ /* ......... */ } |
Note These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
Moving to the operational state (STA state) is implemented by issuing the following service call from the processing program.
- sta_cyc, ista_cyc
This service call moves the cyclic handler specified by parameter cycid from the non-operational state (STP state) to operational state (STA state).
As a result, the target cyclic handler is handled as an activation target of the RI600PX.
The relative interval from when either of this service call is issued until the first activation request is issued varies depending on whether the TA_PHS attribute (phsatr) is specified for the target cyclic handler during configuration.
This service call moves the cyclic handler specified by parameter cycid from the non-operational state (STP state) to operational state (STA state).
As a result, the target cyclic handler is handled as an activation target of the RI600PX.
The relative interval from when either of this service call is issued until the first activation request is issued varies depending on whether the TA_PHS attribute (phsatr) is specified for the target cyclic handler during configuration.
- If the TA_PHS attribute is specified
The target cyclic handler activation timing is set up based on the activation phases and activation cycle.
If the target cyclic handler has already been in operational state, however, no processing is performed even if this service call is issued, but it is not handled as an error.
The following shows a cyclic handler activation timing image.
The target cyclic handler activation timing is set up based on the activation phases and activation cycle.
If the target cyclic handler has already been in operational state, however, no processing is performed even if this service call is issued, but it is not handled as an error.
The following shows a cyclic handler activation timing image.
- If the TA_PHS attribute is not specified
The target cyclic handler activation timing is set up according to the activation cycle on the basis of the call time of this service call.
This setting is performed regardless of the operating status of the target cyclic handler.
The following shows a cyclic handler activation timing image.
The target cyclic handler activation timing is set up according to the activation cycle on the basis of the call time of this service call.
This setting is performed regardless of the operating status of the target cyclic handler.
The following shows a cyclic handler activation timing image.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note*/ void Task1 (VP_INT exinf); /*Refer to note*/ void Task1 (VP_INT exinf) { ID cycid = 1; /*Declares and initializes variable*/ /* ......... */ sta_cyc (cycid); /*Start cyclic handler operation*/ /* ......... */ } |
Note These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
Moving to the non-operational state (STP state) is implemented by issuing the following service call from the processing program.
- stp_cyc, istp_cyc
This service call moves the cyclic handler specified by parameter cycid from the operational state (STA state) to non-operational state (STP state).
As a result, the target cyclic handler is excluded from activation targets of the RI600PX until issuance of sta_cyc or ista_cyc.
The following describes an example for coding these service calls.
This service call moves the cyclic handler specified by parameter cycid from the operational state (STA state) to non-operational state (STP state).
As a result, the target cyclic handler is excluded from activation targets of the RI600PX until issuance of sta_cyc or ista_cyc.
The following describes an example for coding these service calls.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note 2*/ void Task1 (VP_INT exinf); /*Refer to note 2*/ void Task1 (VP_INT exinf) { ID cycid = 1; /*Declares and initializes variable*/ /* ......... */ stp_cyc (cycid); /*Stop cyclic handler operation*/ /* ......... */ } |
Note 1 This service call does not perform queuing of stop requests. If the target cyclic handler has been moved to the non-operational state (STP state), therefore, no processing is performed but it is not handled as an error.
Note 2 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
- ref_cyc, iref_cyc
Stores cyclic handler state packet (current state, time until the next activation, etc.) of the cyclic handler specified by parameter cycid in the area specified by parameter pk_rcyc.
The following describes an example for coding these service calls.
Stores cyclic handler state packet (current state, time until the next activation, etc.) of the cyclic handler specified by parameter cycid in the area specified by parameter pk_rcyc.
The following describes an example for coding these service calls.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note 2*/ void Task1 (VP_INT exinf); /*Refer to note 2*/ void Task1 (VP_INT exinf) { ID cycid = 1; /*Declares and initializes variable*/ T_RCYC pk_rcyc; /*Declares data structure*/ STAT cycstat; /*Declares variable*/ RELTIM lefttim; /*Declares variable*/ /* ......... */ ref_cyc (cycid, &pk_rcyc); /*Reference cyclic handler state*/ cycstat = pk_rcyc.cycstat; /*Reference current state*/ lefttim = pk_rcyc.lefttim; /*Reference time left before the next */ /*activation*/ /* ......... */ } |
Note 1 For details about the cyclic handler state packet, refer to "[Cyclic handler state packet: T_RCYC]".
Note 2 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
The RI600PX handles the alarm handler as a "non-task (module independent from tasks)". Therefore, even if a task with the highest priority in the system is being executed, the processing is suspended when a specified time has elapsed, and the control is passed to the alarm handler.
The following shows the basic form of alarm handlers. The extended information defined at creating the alarm handler is passed to the exinf.
Note These statements are unnecessary for the alarm handler which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
- Service call
The RI600PX handles the alarm handler as a "non-task".
The alarm handler can issue service calls whose "Useful range" is "Non-task".
The RI600PX handles the alarm handler as a "non-task".
The alarm handler can issue service calls whose "Useful range" is "Non-task".
Note If a service call (isig_sem, iset_flg, etc.) which causes dispatch processing (task scheduling processing) is issued in order to quickly complete the processing in the alarm handler during the interval until the processing in the alarm handler ends, the RI600PX executes only processing such as queue manipulation, counter manipulation, etc., and the actual dispatch processing is delayed until a return instruction is issued by the alarm handler, upon which the actual dispatch processing is performed in batch.
1 ) Creation by the system configuration file
The static API alarm_hand[] described in the system configuration file creates a cyclic handler.
Refer to 20.20 Alarm Handler Information (alarm_handl[]) for the details of alarm_hand[].
The static API alarm_hand[] described in the system configuration file creates a cyclic handler.
Refer to 20.20 Alarm Handler Information (alarm_handl[]) for the details of alarm_hand[].
2 ) Creation by cre_alm or acre_alm
The cre_alm creates a cyclic handler with alarm handler ID indicated by parameter almid according to the content of parameter pk_calm.
The acre_cyc creates a alarm handler according to the content of parameter pk_calm, and returns the created alarm handler ID.
The information specified is shown below.
The cre_alm creates a cyclic handler with alarm handler ID indicated by parameter almid according to the content of parameter pk_calm.
The acre_cyc creates a alarm handler according to the content of parameter pk_calm, and returns the created alarm handler ID.
The information specified is shown below.
These service calls can be called from tasks that belong to Trusted Domain.
The following describes an example for coding acre_alm as a representative.
The following describes an example for coding acre_alm as a representative.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ extern void Almhdr1(VP_INT exinf); #pragma task Task1 /*Refer to note*/ void Task1 (VP_INT exinf); /*Refer to note*/ void Task1 (VP_INT exinf) { ER almid; /*Declares variable*/ T_CALM pk_calm = { /*Declares and initializes variable*/ TA_HLNG, /*Alarm handler attribute (cycatr)*/ 0, /*Extended information (exinf)*/ (FP)Almhdr1 /*Start address (almhdr)*/ }; /* ......... */ almid = acre_alm ( &pk_calm ); /*Create alarm handler/ /* ......... */ } |
Note These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
- del_alm
This service call deletes the alarm handler specified by parameter almid.
This service call can be called from tasks that belong to Trusted Domain.
The following describes an example for coding this service call.
This service call deletes the alarm handler specified by parameter almid.
This service call can be called from tasks that belong to Trusted Domain.
The following describes an example for coding this service call.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note*/ void Task1 (VP_INT exinf); /*Refer to note*/ void Task1 (VP_INT exinf) { ID almid = 8; /*Declares and initializes variable*/ /* ......... */ ercd = del_alm ( almid ); /*Delete alarm handler*/ /* ......... */ } |
Note These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
Moving to the operational state (STA state) is implemented by issuing the following service call from the processing program.
- sta_alm, ista_alm
This service call sets the activation time of the alarm handler specified by almid in almtim (msec), and moves the alarm handler from the non-operational state (STP state) to operational state (STA state).
As a result, the target alarm handler is handled as an activation target of the RI600PX.
The following describes an example for coding these service calls.
This service call sets the activation time of the alarm handler specified by almid in almtim (msec), and moves the alarm handler from the non-operational state (STP state) to operational state (STA state).
As a result, the target alarm handler is handled as an activation target of the RI600PX.
The following describes an example for coding these service calls.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note 3*/ void Task1 (VP_INT exinf); /*Refer to note 3*/ void Task1 (VP_INT exinf) { ID almid = 1; /*Declares and initializes variable*/ /* ......... */ sta_alm (almid); /*Start alarm handler operation*/ /* ......... */ } |
Note 1 When 0 is specified for almtim, the alarm handler will start at the next base clock interruption.
Note 2 When the target alarm handler has already started (STA state), this service call sets the activation time of the target alarm handler in almtim (msec) after canceling the activation time.
Note 3 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
Moving to the non-operational state (STP state) is implemented by issuing the following service call from the processing program.
- stp_alm, istp_alm
This service call moves the alarm handler specified by parameter cycid from the operational state (STA state) to non-operational state (STP state).
As a result, the target alarm handler is excluded from activation targets of the RI600PX until issuance of sta_alm or ista_alm.
The following describes an example for coding these service calls.
This service call moves the alarm handler specified by parameter cycid from the operational state (STA state) to non-operational state (STP state).
As a result, the target alarm handler is excluded from activation targets of the RI600PX until issuance of sta_alm or ista_alm.
The following describes an example for coding these service calls.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note 2*/ void Task1 (VP_INT exinf); /*Refer to note 2*/ void Task1 (VP_INT exinf) { ID almid = 1; /*Declares and initializes variable*/ /* ......... */ stp_alm (almid); /*Stop alarm handler operation*/ /* ......... */ } |
Note 1 This service call does not perform queuing of stop requests. If the target alarm handler has been moved to the non-operational state (STP state), therefore, no processing is performed but it is not handled as an error.
Note 2 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
- ref_alm, iref_alm
Stores alarm handler state packet (current state, time until the next activation, etc.) of the alarm handler specified by parameter cycid in the area specified by parameter pk_rcyc.
The following describes an example for coding these service calls.
Stores alarm handler state packet (current state, time until the next activation, etc.) of the alarm handler specified by parameter cycid in the area specified by parameter pk_rcyc.
The following describes an example for coding these service calls.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note 2*/ void Task1 (VP_INT exinf); /*Refer to note 2*/ void Task1 (VP_INT exinf) { ID almid = 1; /*Declares and initializes variable*/ T_RALM pk_ralm; /*Declares data structure*/ STAT almstat; /*Declares variable*/ RELTIM lefttim; /*Declares variable*/ /* ......... */ ref_alm (almid, &pk_ralm); /*Reference alarm handler state*/ almstat = pk_ralm.almstat; /*Reference current state*/ lefttim = pk_ralm.lefttim; /*Reference time left */ /* ......... */ } |
Note 1 For details about the alarm handler state packet, refer to "[Alarm handler state packet: T_RALM]".
Note 2 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
Note that even if the system time is changed, the actual time at which the time management requests made before that (e.g., task time-outs, task delay by dly_tsk, cyclic handlers, and alarm handlers) are generated will not change.
- set_tim, iset_tim
These service calls change the system time (unit: msec) to the time specified by parameter p_systim.
The following describes an example for coding these service calls.
These service calls change the system time (unit: msec) to the time specified by parameter p_systim.
The following describes an example for coding these service calls.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note 2*/ void Task1 (VP_INT exinf); /*Refer to note 2*/ void Task1 (VP_INT exinf) { SYSTIM p_systim; /*Declares data structure*/ p_systim.ltime = 3600; /*Initializes data structure*/ p_systim.utime = 0; /*Initializes data structure*/ /* ......... */ set_tim (&p_systim); /*Set system time*/ /* ......... */ } |
Note 2 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
The system time can be referenced by issuing the following service call from the processing program.
- get_tim, iget_tim
These service calls store the system time (unit: msec) into the area specified by parameter p_systim.
The following describes an example for coding these service calls.
These service calls store the system time (unit: msec) into the area specified by parameter p_systim.
The following describes an example for coding these service calls.
#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #pragma task Task1 /*Refer to note 2*/ void Task1 (VP_INT exinf); /*Refer to note 2*/ void Task1 (VP_INT exinf) { SYSTIM p_systim; /*Declares data structure*/ UW ltime; /*Declares variable*/ UH utime; /*Declares variable*/ /* ......... */ get_tim (&p_systim); /*Reference System Time*/ ltime = p_systim.ltime; /*Acquirer system time (lower 32 bits)*/ utime = p_systim.utime; /*Acquirer system time (higher 16 bits)*/ /* ......... */ } |
Note 2 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
Note The source file for the base clock timer initialization routine provided by the RI600PX as a sample file is "init_cmt.c".
- Basic form of base clock timer initialization routine
The following shows the basic form of base clock timer initialization routine.
The following shows the basic form of base clock timer initialization routine.
- Description
The base clock timer initialization routine is called by vsta_knl and ivsta_knl.
The "_RI_CLOCK_TIMER" is macro generated in "kernel_id.h" by the cfg600px. The definition value for "_RI_CLOCK_TIMER" is depend on Selection of timer channel for base clock (timer) in the system configuration file. Details are shown below.
The base clock timer initialization routine is called by vsta_knl and ivsta_knl.
The "_RI_CLOCK_TIMER" is macro generated in "kernel_id.h" by the cfg600px. The definition value for "_RI_CLOCK_TIMER" is depend on Selection of timer channel for base clock (timer) in the system configuration file. Details are shown below.
When "CMT0", "CMT1", "CMT2" or "CMT3" is specified for "clock.timer", the cfg600px generates the inline-function "void _RI_init_cmt(void)" for initializing the base clock timer. The _RI_init_cmt_knl() should be implemented only to call _RI_init_cmt().
When "NOTIMER" is specified for "clock.timer", the _RI_init_cmt_knl() should be implemented so that nothing may be processed.
- Service call
The base clock timer initialization routine can issue service calls whose "Useful range" is "Non-task".
The base clock timer initialization routine can issue service calls whose "Useful range" is "Non-task".