CHAPTER 10 TIME MANAGEMENT FUNCTIONS
This chapter describes the time management functions performed by the RI600PX.
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.
The system time is a time used by the RI600PX for performing time management (in millisecond).
10.2.1 Base clock timer interrupt
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.
10.2.2 Base clock interval
In the RI600PX, service call parameters for time specification are specified in
msec units.
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).
By specifying the base clock interval, processing regards that the time equivalent to the base clock interval elapses during a base clock timer interrupt.
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.
Delayed wake-up is implemented by issuing the following service call from the processing program.
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.
A time-out is implemented by issuing the following service call from the processing program.
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.
10.6.1 Basic form of 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.
#include "kernel.h" /*Standard header file definition*/
#include "kernel_id.h" /*Header file generated by cfg600px*/
#pragma cychandler Cychdr1 /*Refer to note*/
void Cychdr1 (VP_INT exinf);
void Cychdr1 (VP_INT exinf)
{
/* ......... */
return; /*Terminate cyclic handler*/
}
|
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".
10.6.2 Processing in cyclic handler
- Stack
A cyclic handler uses the system stack.
- 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".
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.
- PSW register when processing is started
Table 10-1 PSW Register When Cyclic Handler is Started
|
|
|
|
|
|
|
|
|
|
|
Do not lower IPL more than the start of processing.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
10.6.3 Create cyclic handler
Cyclic handlers are created by one of the following methods.
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.
- Cyclic handler attribute (
cycatr)
The following informations are specified as
cycatr.
- Whether the cyclic handler is in the operational state. (TA_STA attribute)
- Whether the activation phase is saved. (TA_PHS attribute)
- Extended information (
exinf)
- Cyclic handler start address (
cychdr)
- Activation cycle (
cyctim)
- Activation phase (
cycphs)
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.
#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".
10.6.4 Delete cyclic handler
-
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.
#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".
10.6.5 Start cyclic handler operation
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.
- 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.
Figure 10-1 TA_PHS Attribute: Specified
- 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.
Figure 10-2 TA_PHS Attribute: Not Specified
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*/
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".
10.6.6 Stop cyclic handler operation
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.
#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".
10.6.7 Reference cyclic handler state
A cyclic handler status by issuing the following service call from the processing program.
-
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.
#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 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 alarm handler is a routine started when the specified time passes.
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.
10.7.1 Basic form of 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.
#include "kernel.h" /*Standard header file definition*/
#include "kernel_id.h" /*Header file generated by cfg600px*/
#pragma alarmhand Almhdr1 /*Refer to note*/
void Almhdr1 (VP_INT exinf); /*Refer to note*/
void Almhdr1 (VP_INT exinf)
{
/* ......... */
return; /*Terminate alarm handler*/
}
|
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".
10.7.2 Processing in alarm handler
- Stack
A alarm handler uses the system stack.
- 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".
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.
- PSW register when processing is started
Table 10-2 PSW Register When Alarm Handler is Started)
|
|
|
|
|
|
|
|
|
|
|
Do not lower IPL more than the start of processing.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
10.7.3 Create alarm handler
Cyclic handlers are created by one of the following methods.
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.
- Alarm handler attribute (
almatr)
Only TA_HLNG can be specified for
almatr.
- Extended information (
exinf)
- Alarm handler start address (
almhdr)
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.
#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".
10.7.4 Delete alarm handler
-
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.
#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".
10.7.5 Start alarm handler operation
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.
#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".
10.7.6 Stop alarm handler operation
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.
#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".
10.7.7 Reference Alarm Handler State
A alarm handler status by issuing the following service call from the processing program.
-
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.
#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 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 set by issuing the following service call from the processing program.
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.
#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".
10.8.2 Reference system time
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.
#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".
10.9 Base Clock Timer Initialization Routine (_RI_init_cmt_knl( ))
10.9.1 User-own cording module
The base clock timer initialization routine must be implemented as user-own coding module.
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.
#include "kernel.h" // Provided by RI600PX
#include "kernel_id.h" // Generated by cfg600px
#if (((_RI_CLOCK_TIMER) >=0) && ((_RI_CLOCK_TIMER) <= 3))
#include "ri_cmt.h"
#endif
////////////////////////////////////////////////////////////
// Timer initialize call-back
////////////////////////////////////////////////////////////
void _RI_init_cmt_knl(void);
void _RI_init_cmt_knl(void)
{
#if (((_RI_CLOCK_TIMER) >=0) && ((_RI_CLOCK_TIMER) <= 3))
_RI_init_cmt();
#endif
}
|
Note The function name of the base clock timer initialization routine is "_RI_init_cmt_knl".
- 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.
|
|
"_RI_CLOCK_TIMER" definition value
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 "OTHER" is specified for "clock.timer", the application must implement _RI_init_cmt_knl().
When "NOTIMER" is specified for "clock.timer", the _RI_init_cmt_knl() should be implemented so that nothing may be processed.
- Stack
The base clock timer initialization routine uses the system stack.
- Service call
The base clock timer initialization routine can issue service calls whose "Useful range" is "Non-task".
- PSW register when processing is started
Table 10-3 PSW Register When Base Clock Timer Initialization Routine is Started
|
|
|
|
|
|
|
|
|
|
|
Do not lower IPL more than the start of processing.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
