Time Management Functions
Time management functions perform time-dependent processing. They include functions for system time management, cyclic handlers, and alarm handlers.
The generic name used in the following for cyclic handlers and alarm handlers is time event handlers.
System Time Management
System time management functions manipulate system time. Functions are provided for system clock setting and reference, and for referencing system operating time.
tk_set_tim - Set Time
Parameter
pk_tim Detail:
Description
Sets the system clock to the value specified in pk_tim.
System time is expressed as cumulative milliseconds from 0:00:00 (GMT), January 1, 1985.
Additional Notes
The relative time specified in RELTIM or TMO does not change even if the system clock is changed by calling tk_set_tim during system operation. For example, if a timeout is set to elapse in 60 seconds and the system clock is advanced by 60 seconds by tk_set_tim while waiting for the timeout, the timeout occurs not immediately but 60 seconds after it was set. Instead, tk_set_tim changes the system time at which the timeout occurs.
The time specified in pk_tim for tk_set_tim() is not restricted to the resolution of the timer interrupt cycle. But the time that is read later by tk_get_tim() changes according to the time resolution of the timer interrupt cycle. For example, in the system where the timer interrupt cycle is 10 milliseconds, if the time of 0005 (ms) is specified in tk_set_tim(), then the time obtained later by tk_get_tim() changes as follows: 0005 (ms) → 0015 (ms) → 0025 (ms).
tk_set_tim_u - Set Time (in microseconds)
Description
This system call takes 64-bit tim_u in microseconds instead of the parameter pk_tim of tk_set_tim.
Whereas the parameter pk_tim of tk_set_tim is passed in packet using the structure SYSTIM, the parameter tim_u of tk_set_tim_u is passed by value (not packet) using the 64-bit signed integer SYSTIM_U.
The specification of this system call is same as that of tk_set_tim, except the above-mentioned point. For more details, see the description of tk_set_tim.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
tk_get_tim - Get System Time
Return Parameter
pk_tim Detail:
Description
Reads the current value of the system clock and returns in it pk_tim.
System time is expressed as cumulative milliseconds from 0:00:00 (GMT), January 1, 1985.
The resolution of the current system time read by this system call varies depending on the time resolution of the timer interrupt interval (cycle).
Additional Notes
tk_get_tim() cannot be used to get the elapsed time that is shorter than the timer interrupt interval (cycle). To find out the elapsed time shorter than the timer interrupt interval (cycle), use the return parameter ofs of tk_get_tim_u() or td_get_tim().
tk_get_tim_u - Get System Time (Microseconds)
Description
This system call takes 64-bit tim_u in microseconds instead of the return parameter pk_tim of tk_get_tim. It also includes the return parameter ofs that returns the relative time in nanoseconds.
tim_u has the resolution of time interrupt interval (cycle), but even more precise time information is obtained in ofs as the elapsed time from tim_u in nanoseconds. The resolution of ofs is implementation-dependent, but generally is the resolution of hardware timer.
If ofs = NULL is set, the information of ofs is not stored.
The specification of this system call is same as that of tk_get_tim, except the above-mentioned point. In addition, the specification of this system call is the same as that of td_get_tim, except that the data type of tim_u is SYSTIM_U. For more details, see the description of tk_get_tim and td_get_tim.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
tk_get_otm - Get Operating Time
Return Parameter
pk_tim Detail:
Description
Gets the system operating time (up time).
System operating time, unlike system time, indicates the length of time elapsed linearly since the system was started. It is not affected by clock settings made by tk_set_tim.
System operating time must have the same precision as system time.
tk_get_otm_u - Get Operating Time (Microseconds)
Description
This system call takes 64-bit tim_u in microseconds instead of the return parameter pk_tim of tk_get_otm. It also includes the return parameter ofs that returns the relative time in nanoseconds.
tim_u has the resolution of time interrupt interval (cycle), but even more precise time information is obtained in ofs as the elapsed time from tim_u in nanoseconds. The resolution of ofs is implementation-dependent, but generally is the resolution of hardware timer.
If ofs = NULL is set, the information of ofs is not stored.
The specification of this system call is same as that of tk_get_otm, except the above-mentioned point. In addition, the specification of this system call is the same as that of td_get_otm, except that the data type of tim_u is SYSTIM_U. For more details, see the description of tk_get_otm and td_get_otm.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
Cyclic Handler
A cyclic handler is a time event handler started at regular intervals. Cyclic handler functions are provided for creating and deleting a cyclic handler, activating and deactivating a cyclic handler operation, and referencing cyclic handler status. A cyclic handler is an object identified by an ID number. The ID number for the cyclic handler is called a cyclic handler ID.
The time interval at which a cyclic handler is started (cycle time) and the cycle phase are specified for each cyclic handler when it is created. When a cyclic handler operation is requested, T-Kernel determines the time at which the cyclic handler should next be started based on the cycle time and cycle phase set for it. When a cyclic handler is created, the time when it is to be started next is the time of its creation plus the cycle phase. When the time comes to start a cyclic handler, exinf, containing extended information about the cyclic handler, is passed to it as a starting parameter. The time when the cyclic handler is started plus its cycle time becomes the next start time. Sometimes when a cyclic handler is activated, the next start time will be newly set.
In principle the cycle phase of a cyclic handler is no longer than its cycle time. The behavior is implementation-dependent when the cycle phase is made longer than the cycle time.
A cyclic handler has two activation states, active and inactive. While a cyclic handler is inactive, it is not started even when its start time arrives, although calculation of the next start time does take place. When a system call for activating a cyclic handler is called (tk_sta_cyc), the cyclic handler goes to active state, and the next start time is decided if necessary. When a system call for deactivating a cyclic handler is called (tk_stp_cyc), the cyclic handler goes to inactive state. Whether a cyclic handler upon creation is active or inactive is decided by a cyclic handler attribute.
The cycle phase of a cyclic handler is a relative time specifying the first time the cyclic handler is to be started, in relation to the time when the system call creating it was invoked. The cycle time of a cyclic handler is likewise a relative time, specifying the next time the cyclic handler is to be started in relation to the time it should have started (not the time it started). For this reason, the intervals between times the cyclic handler is started will individually be shorter than the cycle time in some cases, but their average over a longer time span will match the cycle time.
 | Additional Notes |
|---|---|
Actual time resolution in T-Kernel time management functions processing uses one that is specified by the "timer interrupt interval" (TTimPeriod) in the Section called Standard System Configuration Information in the Chapter called T-Kernel/SM Functions. It also means that a cyclic handler or an alarm handler is actually started at the time according to the time resolution provided by the timer interrupt interval (TTimPeriod). For this reason, the cyclic handler is actually started at the time of timer interrupt occurrence immediately after the time when the cyclic handler should be started. A general T-Kernel implementation checks if a cyclic handler or an alarm handler that is to be started within the processing of timer interrupt exists, and then starts them as necessary. |
tk_cre_cyc - Create Cyclic Handler
Parameter
pk_ccyc Detail:
| void* |
exinf
| Extended Information | Extended information |
| ATR |
cycatr
| Cyclic Handler Attribute | Cyclic handler attribute |
| FP |
cychdr
| Cyclic Handler Address | Cyclic handler address |
| RELTIM |
cyctim
| Cycle Time | Interval of cyclic start (ms) |
| RELTIM |
cycphs
| Cycle Phase | Cycle phase (ms) |
| UB |
dsname[8]
| DS Object name | DS object name |
| (Other implementation-dependent parameters may be added beyond this point.) | |||
Description
Creates a cyclic handler, assigning to it a cyclic handler ID. This is performed by assigning a control block for the generated cyclic handler.
A cyclic handler is a handler running at specified intervals as a task-independent portion.
exinf can be used freely by the user to set miscellaneous information about the created cyclic handler. The information set in this parameter can be referenced by tk_ref_cyc. If a larger area is needed for indicating user information, or if the information may need to be changed after the message buffer is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The kernel pays no attention to the contents of exinf.
cycatr indicates system attributes in its lower bits and implementation-dependent attributes in its higher bits. The system attribute part of cycatr is as follows.
cycatr := (TA_ASM || TA_HLNG) | [TA_STA] | [TA_PHS] | [TA_DSNAME]
| TA_ASM | The handler is written in assembly language |
| TA_HLNG | The handler is written in high-level language |
| TA_STA | Activate immediately upon cyclic handler creation |
| TA_PHS | Save the cycle phase |
| TA_DSNAME | Specifies DS object name |
#define TA_ASM 0x00000000 /* assembly language program */ #define TA_HLNG 0x00000001 /* high-level language program */ #define TA_STA 0x00000002 /* activate cyclic handler */ #define TA_PHS 0x00000004 /* save cyclic handler cycle phase */ #define TA_DSNAME 0x00000040 /* DS object name */
cychdr specifies the cyclic handler start address, cyctim the cycle time, and cycphs the cycle phase.
When the TA_HLNG attribute is specified, the cyclic handler is started via a high-level language support routine. The high-level language support routine takes care of saving and restoring register values. The cyclic handler terminates by a simple return from a function. The cyclic handler takes the following format when the TA_HLNG attribute is specified.
void cychdr( void *exinf )
{
/*
(processing)
*/
return; /* Exit cyclic handler*/
}
The cyclic handler format when the TA_ASM attribute is specified is implementation-dependent, but exinf must be passed in a starting parameter.
cycphs indicates the length of time until the cyclic handler is initially started after being created by tk_cre_cyc. Thereafter it is started periodically at the interval set in cyctim. If zero is specified in cycphs, the cyclic handler starts immediately after it is created. Zero cannot be specified in cyctim.
The starting of the cyclic handler for the nth time occurs after at least cycphs + cyctim * (n - 1) time has elapsed from the cyclic handler creation.
When TA_STA is specified, the cyclic handler goes to active state immediately on creation, and starts at the intervals noted above. If TA_STA is not specified, the cycle time is calculated but the cyclic handler is not actually started.
When TA_PHS is specified, then even if tk_sta_cyc is called activating the cyclic handler, the cycle time is not reset, and the cycle time calculated as above from the time of cyclic handler creation continues to apply. If TA_PHS is not specified, calling tk_sta_cyc resets the cycle time and the cyclic handler is started at cyctim intervals measured from the time tk_sta_cyc was called. Note that the resetting of cycle time by tk_sta_cyc does not affect cycphs. In this case the starting of the cyclic handler for the nth time occurs after at least cyctim * n has elapsed from the calling of tk_sta_cyc.
Even if a system call is invoked from a cyclic handler and this causes the task in RUNNING state up to that time to go to another state, with a different task going to RUNNING state, dispatching (task switching) does not occur while the cyclic handler is running. Completion of execution by the cyclic handler has precedence even if dispatching is necessary; only when the cyclic handler terminates does the dispatch take place. In other words, a dispatch request that is generated while a cyclic handler is running is not processed immediately, but is delayed until the cyclic handler terminates. This is called delayed dispatching.
A cyclic handler runs as a task-independent portion. As such, it is not possible to call in a cyclic handler a system call that can enter WAITING state, or one that is intended for the invoking task.
When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used to identify objects by debugger, and it is handled only by T-Kernel/DS API, td_ref_dsname and td_set_dsname. For more details, see the description of td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.
Additional Notes
Once a cyclic handler is defined, it continues to run at the specified cycles either until tk_stp_cyc is called to deactivate it or until it is deleted. There is no parameter to specify the number of cycles in tk_cre_cyc.
When multiple time event handlers or interrupt handlers operate at the same time, it is implementation-dependent whether to have them run serially (after one handler exits, another starts) or in a nested manner (one handler operation is suspended, another runs, and when that one finishes the previous one resumes). In either case, since time event handlers and interrupt handlers run as task-independent portion, the principle of delayed dispatching applies.
If 0 is specified in cycphs, the first startup of the cyclic handler is executed immediately after this system call execution. However, depending on the implementation, the first startup (execution) of the cyclic handler may be executed while processing this system call, instead of immediately after the completion of this system call execution. In such case, the interrupt disabled or other state in the cyclic handler may differ from the state at the second and subsequent ordinary startups. In addition, when 0 is set to cycphs, the first startup of the cyclic handler is executed without waiting for a timer interrupt, that is, regardless of the timer interrupt interval. This behavior also differs from the second and subsequent startups of the cyclic handler, and from the startup of the cyclic handler with cycphs set to other than 0.
tk_cre_cyc_u - Create Cyclic Handler (in microseconds)
Parameter
pk_ccyc_u Detail:
| void* |
exinf
| Extended Information | Extended information |
| ATR |
cycatr
| Cyclic Handler Attribute | Cyclic handler attribute |
| FP |
cychdr
| Cyclic Handler Address | Cyclic handler address |
| RELTIM_U |
cyctim_u
| Cycle Time | Interval of cyclic start (microseconds) |
| RELTIM_U |
cycphs_u
| Cycle Phase | Cycle phase (microseconds) |
| UB |
dsname[8]
| DS Object name | DS object name |
| (Other implementation-dependent parameters may be added beyond this point.) | |||
Description
This system call takes 64-bit cyctim_u and cycphs_u in microseconds instead of the parameters cyctim and cycphs of tk_cre_cyc.
The specification of this system call is same as that of tk_cre_cyc, except that the parameter is replaced with cyctim_u and cycphs_u. For more details, see the description of tk_cre_cyc.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
tk_del_cyc - Delete Cyclic Handler
Description
Deletes a cyclic handler.
tk_sta_cyc - Start Cyclic Handler
Description
Activates a cyclic handler, putting it in active state.
If the TA_PHS attribute was specified, the cycle time of the cyclic handler is not reset when the cyclic handler goes to active state. If it was already in active state when this system call was executed, it continues unchanged in active state.
If the TA_PHS attribute was not specified, the cycle time is reset when the cyclic handler goes to active state. If it was already in active state, it continues in active state but its cycle time is reset. In this case, the next time the cyclic handler starts is after cyctim has elapsed.
tk_stp_cyc - Stop Cyclic Handler
Description
Deactivates a cyclic handler, putting it in inactive state. It the cyclic handler was already in inactive state, this system call has no effect (no operation).
tk_ref_cyc - Reference Cyclic Handler Status
Return Parameter
pk_rcyc Detail:
Description
References the status of the cyclic handler specified in cycid, passing in return parameters the cyclic handler activation state (cycstat), the time remaining until the next start (lfttim), and extended information (exinf).
The following information is returned in cycstat.
cycstat:= (TCYC_STP | TCYC_STA)
#define TCYC_STP 0x00 /* cyclic handler is inactive */ #define TCYC_STA 0x01 /* cyclic handler is active */
lfttim returns the remaining time (milliseconds) until the next time when the cyclic handler is invoked. It does not matter whether the cyclic handler is currently running or stopped.
exinf returns the extended information specified as a parameter when the cyclic handler is generated.exinf is passed to the cyclic handler as a parameter.
If the cyclic handler specified in cycid does not exist for, error code E_NOEXS is returned.
The time remaining lfttim returned in the cyclic handler status information (T_RCYC) is a value rounded to milliseconds. To know the value in microseconds, call tk_ref_cyc_u.
tk_ref_cyc_u - Reference Cyclic Handler Status (Microseconds)
Return Parameter
pk_rcyc_u Detail:
Description
This system call takes 64-bit lfttim_u in microseconds instead of the return parameter lfttim of tk_ref_cyc.
The specification of this system call is same as that of tk_ref_cyc, except that the return parameter is replaced with lfttim_u. For more details, see the description of tk_ref_cyc.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
Alarm Handler
An alarm handler is a time event handler that starts at a specified time. Functions are provided for creating and deleting an alarm handler, activating and deactivating the alarm handler, and referencing the alarm handler status. An alarm handler is an object identified by an ID number. The ID number for an alarm handler is called an alarm handler ID.
The time at which an alarm handler starts (called the alarm time) can be set independently for each alarm handler. When the alarm time arrives, exinf, containing extended information about the alarm handler, is passed to it as a starting parameter.
After an alarm handler is created, initially it has no alarm time set and is in inactive state. The alarm time is set when the alarm handler is activated by calling tk_sta_alm, as relative time from the time that system call is executed. When tk_stp_alm is called deactivating the alarm handler, the alarm time setting is canceled. Likewise, when an alarm time arrives and the alarm handler runs, the alarm time is canceled and the alarm handler becomes inactive.
| Additional Notes |
|---|---|
An alarm handler is actually started at the time according to the time resolution provided by the timer interrupt interval (TTimPeriod). For more details, see the additional notes for the Section called Cyclic Handler. |
tk_cre_alm - Create Alarm Handler
Parameter
pk_calm Detail:
Description
Creates an alarm handler, assigning to it an alarm handler ID. This is performed by assigning a control block for the generated alarm handler.
An alarm handler is a handler running at the specified time as a task-independent portion.
exinf can be used freely by the user to set miscellaneous information about the created alarm handler. The information set in this parameter can be referenced by tk_ref_alm. If a larger area is needed for indicating user information, or if the information may need to be changed after the message buffer is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The kernel pays no attention to the contents of exinf.
almatr indicates system attributes in its lower bits and implementation-dependent attributes in its higher bits. The system attribute part of almatr is as follows.
almatr := (TA_ASM || TA_HLNG) | [TA_DSNAME]
| TA_ASM | The handler is written in assembly language |
| TA_HLNG | The handler is written in high-level language |
| TA_DSNAME | Specifies DS object name |
#define TA_ASM 0x00000000 /* assembly language program */ #define TA_HLNG 0x00000001 /* high-level language program */ #define TA_DSNAME 0x00000040 /* DS object name */
almhdr specifies the alarm handler start address.
When the TA_HLNG attribute is specified, the alarm handler is started via a high-level language support routine. The high-level language support routine takes care of saving and restoring register values. The alarm handler terminates by a simple return from a function. The alarm handler takes the following format when the TA_HLNG attribute is specified.
void almhdr( void *exinf )
{
/*
(processing)
*/
return; /* exit alarm handler */
}
The alarm handler format when the TA_ASM attribute is specified is implementation-dependent, but exinf must be passed in a starting parameter.
Even if a system call is invoked from an alarm handler and this causes the task in RUNNING state up to that time to go to another state, with a different task going to RUNNING state, dispatching (task switching) does not occur while the alarm handler is running. Completion of execution by the alarm handler has precedence even if dispatching is necessary; only when the alarm handler terminates does the dispatch take place. In other words, a dispatch request that is generated while an alarm handler is running is not processed immediately, but is delayed until the alarm handler terminates. This is called delayed dispatching.
An alarm handler runs as a task-independent portion. As such, it is not possible to call in an alarm handler a system call that can enter WAITING state, or one that is intended for the invoking task.
When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used to identify objects by debugger, and it is handled only by T-Kernel/DS API, td_ref_dsname and td_set_dsname. For more details, see the description of td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.
Additional Notes
When multiple time event handlers or interrupt handlers operate at the same time, it is an implementation-dependent whether to have them run serially (after one handler exits, another starts) or in a nested manner (one handler operation is suspended, another runs, and when that one finishes the previous one resumes). In either case, since time event handlers and interrupt handlers run as task-independent portion, the principle of delayed dispatching applies.
tk_del_alm - Delete Alarm Handler
Description
Deletes an alarm handler.
tk_sta_alm - Start Alarm Handler
Description
Sets the alarm time of the alarm handler specified in almid to the time given in almtim, putting the alarm handler in active state. almtim is specified as relative time from the time of calling tk_sta_alm. After the time specified in almtim has elapsed, the alarm handler starts. If the alarm handler is already active when this system call is invoked, the existing almtim setting is canceled and the alarm handler is activated anew with the alarm time specified here.
If almtim = 0 is set, the alarm handler starts as soon as it is activated.
tk_sta_alm_u - Start Alarm Handler (in microseconds)
Description
This system call takes 64-bit almtim_u in microseconds instead of the parameter almtim of tk_sta_alm.
The specification of this system call is same as that of tk_sta_alm, except that the parameter is replaced with almtim_u. For more details, see the description of tk_sta_alm.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
tk_stp_alm - Stop Alarm Handler
Description
Cancels the alarm time of the alarm handler specified in almid, putting it in inactive state. It the cyclic handler was already in inactive state, this system call has no effect (no operation).
tk_ref_alm - Reference Alarm Handler Status
Return Parameter
pk_ralm Detail:
Description
References the status of the alarm handler specified in almid, passing in return parameters the time remaining until the handler starts (lfttim), and extended information (exinf).
The following information is returned in almstat.
almstat:= (TALM_STP | TALM_STA)
#define TALM_STP 0x00 0x00 /* alarm handler is inactive */ #define TALM_STA 0x01 0x01 /* alarm handler is active */
If the alarm handler is active (TALM_STA), the relative time until the alarm handler is scheduled to be started next time is returned to lfttim. This value is within the range almtim ≧ lfttim ≧ 0 specified with tk_sta_alm. Since lfttim is decremented with each timer interrupt, lfttim = 0 means the alarm handler will start at the next timer interrupt.
exinf returns the extended information specified as a parameter when the alarm handler is generated. exinf is passed to the alarm handler as a parameter.
If the alarm handler is inactive (TALM_STP), lfttim is indeterminate.
If the alarm handler specified with tk_ref_alm in almid does not exist, error code E_NOEXS is returned.
The time remaining lfttim returned in the alarm handler status information (T_RALM) is a value rounded to milliseconds. To know the value in microseconds, call tk_ref_alm_u.
tk_ref_alm_u - Reference Alarm Handler Status (Microseconds)
Return Parameter
pk_ralm_u Detail:
Description
This system call takes 64-bit lfttim_u in microseconds instead of the return parameter lfttim of tk_ref_alm.
The specification of this system call is same as that of tk_ref_alm, except that the return parameter is replaced with lfttim_u. For more details, see the description of tk_ref_alm.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.