Physical Timer Functions
Physical timer functions are useful in the system equipped with more than one hardware timer when processing should be performed based on smaller unit of elapsed time than the timer interrupt interval (TTimPeriod).
A physical timer means a hardware counter that is monotonically incremented by one from 0 at a constant time interval. When a count value reaches a certain value (upper limit) specified for each physical timer, the handler (physical timer handler) specified for each physical timer is started and the count value is reset to 0.
More than one physical timer can be used depending on the number of hardware timers available in the system. The number of available physical timers is implementation-dependent. In the usual T-Kernel implementation, one hardware timer is used to realize the time management functions. Therefore it is assumed that remaining hardware timers are used for the physical timers.
Positive integer of ascending order like 1, 2, ... is used as a physical timer number. For example, when there are four hardware timers, as one of them is used for the T-Kernel time management functions, remaining three hardware timers are available with physical timer numbers assigned as 1, 2, and 3, respectively.
The T-Kernel/SM physical timer functions do not manage coordination between an individual physical timer and tasks that use the timer. If more than one task share one physical timer, coordination like mutual exclusion control must be performed on the application side.
 | Additional Notes |
|---|---|
For the T-Kernel time management functions, the kernel starts alarm handler or cyclic handler, processes timeout, and processes these requests, all in the handler that is started on the time interval specified by "timer interrupt interval" (TTimPeriod) in the Section called Standard System Configuration Information. On the other hand, the physical timer functions only standardize the primitive functions such as setting a hardware timer, reading a count value, and triggering interrupt. They do not perform multiple processings like the T-Kernel time management functions do. Based on this observation, the physical timer functions carry the name of "physical timer" since they have lower abstraction level than conventional time management functions, and are closer to hardware layer. Due to the above positioning, the physical timer functions are made to be as simple as possible and limited to a small specification, and are assumed to be realized by library functions which have small overhead. This policy is reflected in the specification of using the statically fixed physical timer numbers rather than dynamical ID numbers, and the specification of never performing the management of mapping with the requesting task or the requests from more than one task. Physical timer functions are implemented by standardizing APIs that operate the timer (counter) device. However, the timer devices have direct relation with time related behaviors such as calling interrupt handler based on a small elapsed time, making such devises more closely connected with the kernel than other devices (storage and communication). For this reason, the physical timer is provided as more generic function by standardizing its specification as a part of the T-Kernel/SM instead of standardizing it as part of device driver specification. Since the physical timer functions belong to the T-Kernel/SM, the T-Kernel/SM [Overall Note and Supplement] is applied. Hardware timer counter used as a physical timer is assumed to be 32-bit or less. Therefore, 32-bit UW is used for the data type that represents the count values or upper limits. In the future, 64-bit functions can be added. |
| Rationale for the Specification |
|---|---|
In the T-Kernel 2.0, the time management functions are enhanced, and the physical timer functions have been introduced in order to make effective use of multiple hardware timers implemented on the recent embedded microcomputers or SoC (System on a Chip) and enhance the portability of programs that operate these timers. |
| Difference from T-Kernel 1.0 |
|---|---|
These functions were added in T-Kernel 2.0. |
Use Case of Physical Timer
Examples of effective use of physical timer functions are as follows:
- (a)Example of processing to be realized
Assume that there are a cyclic processing X to be run every 2,500 microseconds and a cyclic processing Y to be run every 1,800 microseconds. Physical timers can achieve this efficiently.
- (b)Implementation with physical timer functions
Two physical timers are used, and one is set to start a physical timer handler every 2,500 microseconds.
For example, if the physical timer clock frequency is 10 MHz, as 1 clock corresponds to 0.1 microseconds (= 100 nanoseconds), set a physical timer upper limit (
limit) to 24,999 (= 25,000 - 1) to make the physical timer handler start when the count value is changed from 24,999 to 0.As this is a cyclic processing,
modeof StartPhysicalTimer should be set to TA_CYC_PTMR.Processing X is performed within this physical timer handler.
Similarly using another physical timer, the physical timer handler is set to start every 1,800 microseconds to perform the processing Y within this physical timer handler.
The timer interrupt interval (TTimPeriod) used by the T-Kernel time management functions can be left as the default value (10 milliseconds) since it has no relationship with the physical timer functions.
- (c)Implementation without physical timer functions
Instead of the physical timer handler, the T-Kernel 2.0 system call (tk_cre_cyc_u) that can specify time in microseconds is used to define the cyclic handler to start it every 2,500 microseconds to perform the processing X within this cyclic handler. Similarly, a cyclic handler is defined to start it every 1,800 microseconds to perform the processing Y within this cyclic handler.
However, in this case, the timer interrupt interval must be set with small enough interval so that the time of every 2,500 microseconds and every 1,800 microseconds can be processed precisely. Specifically, both processing every 2,500 microseconds and processing every 1,800 microseconds can be achieved with almost exact timing by using the timer interrupt interval of 100 microseconds which is a common divisor of 2,500 microseconds and 1,800 microseconds.
With the method (b) which uses the physical timer functions, the timer interrupt interval can be left as the default value (every 10 milliseconds) since the T-Kernel time management functions are not used. Interrupts by the physical timer will occur every 2,500 and 1,800 microseconds, from which the physical timer handler is called to perform the processing X and Processing Y. No unnecessary interrupt related to timer will occur other than these.
On the other hand, for the method of (c) which does not use a physical timer, because the timer interrupt interval must be shortened, the overhead increases accordingly as the number of timer interrupts increases. For example, when comparing (b) and (c) in terms of the number of timer related interrupts that occur in 10 milliseconds period, (b) will have a total interrupt number of 10; 1 (= 10 milliseconds/10 milliseconds) for time management functions, 4 (= 10 milliseconds/2,500 microseconds) as physical timer interrupt for processing X, and 5 (= 10 milliseconds/1,800 microseconds) as physical timer interrupt for processing Y. For (c), timer interrupt number is 100 (10 milliseconds/100 microseconds) for time management functions. This is a trade-off situation with the accuracy of time. The smaller timer interval may be required depending on the difference between cycles or phases of processing X and processing Y, resulting in even larger overhead. In these cases, the physical timer functions are clearly effective.
However, the physical timer functions are highly effective only when the number of processings that depend on time is small and statically fixed, and enough number of hardware timers exist for them. Because the physical timer functions are, as its name shows, subject to the constraints of physical hardware resources, physical timer functions cannot be used effectively when the number of hardware timers is too small. Additionally, it will experience difficulty with the case where the number of time-dependent processings dynamically increases. In these cases, using the conventional time management functions such as the cyclic handler and alarm handler will achieve more flexible handling.
Though the application area of physical timer functions and time management functions in microseconds may overlap, they have different characteristics shown above. Therefore, it is recommended to use appropriate one depending on the hardware configuration and applications. The physical timer functions have been added for this reason.
StartPhysicalTimer - Start Physical Timer
Description
Sets the count value of the physical timer specified by ptmrno to 0, and then starts counting. After this function is executed, the count value is incremented by one at a constant time interval that is the inverse of the timer clock frequency.
limit specifies the upper limit of the count value. When a time period equal to the inverse of the clock frequency has elapsed after the count value reaches the upper limit, the count value is reset to 0. At that timing, if a physical timer handler is defined for this physical timer, that handler will be started. The duration between when the counting is started by StartPhysicalTimer() call and when the counter is reset to zero is (inverse of timer clock frequency) x (upper limit + 1).
If limit is set to 0, an E_PAR error will occur.
mode specifies the following modes:
| TA_ALM_PTMR | 0 | The counting is stopped when the count value is reset to 0 from the upper limit value. Afterward, the count value remains as 0. |
| TA_CYC_PTMR | 1 | The count value starts to increase again, after it is reset to 0 from the upper limit value. Therefore, the cycle of increasing and resetting the count value repeats periodically. |
Difference from T-Kernel 1.0
This API was added in T-Kernel 2.0.
StopPhysicalTimer - Stop Physical Timer
Description
Stops the counting operation of the physical timer specified by ptmrno.
After executing this function, the last count value of the physical timer is retained. Therefore, if GetPhysicalTimerCount is executed after this function is executed, that function will return the physical timer count value just before this function is executed.
Executing this function for the physical timer that has already stopped counting does nothing. It does not generate any error.
Additional Notes
If the physical timer that is no longer used is kept running, it may not adversely affect the program operation, but clock signals will be used unnecessarily, which may not be desirable in terms of electric power saving. So, it is recommended to stop the physical timer no longer used by executing this function.
Use of this function is effective for the case TA_CYC_PTMR is specified for the physical timer and its use is ended. If TA_ALM_PTMR is specified as the mode, the physical timer automatically stopped counting after the count value is reset to 0 from the upper limit value, which results in the same state as that after this function being executed. In this case, it is not necessary to issue this function additionally. Issuing this function does not cause any problem, but nothing is changed.
Difference from T-Kernel 1.0
This API was added in T-Kernel 2.0.
GetPhysicalTimerCount - Get Physical Timer Count
Description
Gets the current count value of the physical timer specified by ptmrno, and returns it as the return parameter count.
Difference from T-Kernel 1.0
This API was added in T-Kernel 2.0.
DefinePhysicalTimerHandler - Define Physical Timer Handler
Parameter
| UINT |
ptmrno
| Physical Timer Number | Physical timer number |
| CONST T_DPTMR* |
pk_dptmr
| Packet to Define Physical Timer Handler | Physical timer handler definition information |
pk_dptmr Detail
Error Code
| E_OK | Normal completion |
| E_NOMEM | Insufficient memory (memory for control block cannot be allocated) |
| E_RSATR | Reserved attribute (ptmratr is invalid or cannot be used) |
| E_PAR | Parameter error (ptmrno, pk_dptmr, or ptmrhdr is invalid or cannot be used, or the physical timer handler for ptmrno cannot be defined) |
Description
If pk_dptmr is not NULL, this function defines the physical timer handler for the physical timer specified by ptmrno. The physical timer handler is a handler running as a task-independent portion, and is started when the physical timer count is reset to 0 from the upper limit value specified by limit of StartPhysicalTimer.
The programming format of physical timer handler is similar to that of cyclic handler or alarm handler. This means that if the TA_HLNG attribute is specified, the physical timer handler is started via a high-level language support routine and terminated by a return from the function. If the TA_ASM attribute is specified, the physical timer handler format is implementation-dependent. Regardless of which attribute is specified, exinf is passed as a startup parameter of physical timer handler.
If pk_dptmr is NULL, this function cancels the definition of the physical timer handler for the physical timer specified by ptmrno. The physical timer handlers for all the physical timers are undefined right after the system startup.
If the physical timer handler for the physical timer specified by ptmrno cannot be defined (if the pk_rptmr->defhdr in GetPhysicalTimerConfig returns FALSE), the E_PAR error occurs. If the physical timer specified by ptmrno does not exist or cannot be used, the E_PAR error also occurs.
Additional Notes
In an implementation, the interrupt handler to realize the physical timer function should be defined within T-Kernel/SM, and set to be started when the physical timer count is reset to 0 from the upper limit value. Within this interrupt handler, call the physical timer handler defined by this function, and perform the processing related to the physical timer implementation (such as one related to TA_ALM_PTMR and TA_CYC_PTMR).
Difference from T-Kernel 1.0
This API was added in T-Kernel 2.0.
GetPhysicalTimerConfig - Get Physical Timer Configuration Information
Return Parameter
pk_rptmr Detail
Description
Gets the configuration information of the physical timer specified by ptmrno.
The retrievable configuration information includes the physical timer clock frequency ptmrclk, the maximum count value maxcount, and whether the support for physical timer handler exists defhdr.
ptmrclk indicates the clock frequency used to count up the target physical timer. If ptmrclk is set to 1, the clock is 1 Hz, and if it is set to MATH: 2^32 - 1, then the clock is MATH: 2^32 - 1 Hz (approximately 4 GHz). If the clock is long (less than 1 Hz), then ptmrclk is 0. If ptmrclk is other than 0, the physical timer count value is monotonically incremented by 1, from 0 to the upper limit value limit, at a constant time interval that is the inverse of ptmrclk.
maxcount is the maximum value that can be counted by the target physical timer, and also the maximum value that can be set as the upper limit value. Generally, maxcount is MATH: 2^16 - 1 for a 16-bit timer counter, and MATH: 2^32 - 1 for a 32-bit timer counter, but it may be other value depending on the hardware or system configuration.
If defhdr is TRUE, the physical timer handler, which is started when the target physical timer count reaches the upper limit value, can be defined. If defhdr is FALSE, the physical timer handler for this physical timer cannot be defined.
If the physical timer specified by ptmrno does not exist or cannot be used, the E_PAR error occurs. For the physical timer number, a positive integer value is assigned in ascending order, so if the system has N physical timers, the E_PAR error occurs when ptmrno is 0 or larger than N.
Additional Notes
As the name of this function including "configuration" implies, the information ptmrclk, maxcount, and defhdr retrieved by this function are fixed statically by the hardware specification or the configuration at system start up, and it is assumed that they are not changed during the system operation. However, there is the possibility that the function to actively set or change the physical timer configuration (such as the clock frequency) is implemented in the future release or as additional implementation-dependent function. In such a case, the information retrieved by this function may become dynamic information that changes during the system operation. Such differences in usage depend heavily on the operation and usage, so it is better to absorb it in the upper library that uses the physical timer, rather than defining it as the specification of T-Kernel. For this reason, the T-Kernel specification does not specify the possibility that the configuration information retrieved by this function is changed during the system operation. That is, whether the information retrieved by this function may change during the operation is implementation-dependent.
Difference from T-Kernel 1.0
This API was added in T-Kernel 2.0.