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.
μ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 handle simultaneous multiple requests like the 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 standardize 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 [Overall Note and Supplement] is applicable. 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. |
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 at 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 3.0 system call (tk_cre_cyc_u) that can specify time in microseconds is used to define the cyclic handler that is invoked every 2,500 microseconds to perform the processing X within this cyclic handler. Similarly using another physical timer, a physical timer handler is invoked every 1,800 microseconds to perform the processing Y within this physical timer handler.
However, in this case, the timer interrupt interval used by μT-Kernel Time Management Function 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
Related Service Profile Items
Only when all the service profile items below are set to be effective, this API can be used.
Additionally, the following service profile items are related to this API.
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. |
StopPhysicalTimer - Stop Physical Timer
Related Service Profile Items
Only when all the service profile items below are set to be effective, this API can be used.
Additionally, the following service profile items are related to this API.
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.
GetPhysicalTimerCount - Get Physical Timer Count
Related Service Profile Items
Only when all the service profile items below are set to be effective, this API can be used.
Additionally, the following service profile items are related to this API.
Description
Gets the current count value of the physical timer specified by ptmrno, and returns it as the return parameter count.
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) |
Related Service Profile Items
Only when all the service profile items below are set to be effective, this API can be used.
Additionally, the following service profile items are related to this API.
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 a typical implementation, an interrupt handler to implement the function of physical timer is defined within μT-Kernel/SM, and is configured so that an interrupt to be raised when the physical timer counter value wraps around from the upper limit to zero. In this interrupt handler, the physical timer handler which is defined in this function is called as well as other processing for implementation of physical timer such as the support for TA_ALM_PTMR and TA_CYC_PTMR.
GetPhysicalTimerConfig - Get Physical Timer Configuration Information
Return Parameter
pk_rptmr Detail
Related Service Profile Items
Only when all the service profile items below are set to be effective, this API can be used.
Additionally, the following service profile items are related to this API.
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: 232 - 1, then the clock is MATH: 232 - 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: 216 - 1 for a 16-bit timer counter, and MATH: 232 - 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 substring "configuration" of this function name suggests, the values acquired by this function, ptmrclk, maxcount, and defhdr are assumed to be statically fixed by hardware or by the initialization done during the startup processing of the system, and are not expected to change during the subsequent execution of the system. Note, however, that there is a chance of adding dynamical reconfiguration feature to the core specification or implementation-defined feature: for example, changing the clock frequency of the physical timer. When such modifications are introduced, the information acquired by this function can be a value dynamically changed during the execution of the system. Such changes of use cases depend heavily on the operation methods or applications, and it was considered better to handle such differences in the upper library that use physical timer rather than in the base μT-Kernel specification. Hence, μT-Kernel specification does not define the possibility of dynamically changing nature of the configuration information acquired by this function. In a nutshell, whether the information acquired by this function may change during the execution of the system is implementation-dependent.