RtSetHalTimerPeriodCounts
RtSetHalTimerPeriodCounts sets the APIC counts per RTX64 HAL timer period.
Syntax
bool RtSetHalTimerPeriodCounts( ULONG PeriodicCounts );
Parameters
PeriodicCounts
Specifies a new value for the APIC counts per RTX64 HAL timer period.
Return Value
The function returns true if it succeeds. Otherwise, it returns false. Call GetLastError for additional error information.
Remarks
RtSetHalTimerPeriodCounts allows you to set a new value for the APIC counts per HAL timer period, therefore adjusting the reference frequency of the APIC timer. The HAL timer is used for all other timers or clock-related functions. Adjusting the HAL timer period count will affect the entire system, not just the calling application.
To adjust RTSS time, call RtGetHalTimerPeriodCounts to obtain the current APIC counts and the base APIC counts. To adjust RTSS time to run slower, increase the APIC counts and call RtSetHalTimerPeriodCounts to set on APIC timer. To adjust RTSS time to run faster, decrease the APIC counts and call RtSetHalTimerPeriodCounts to set on APIC timer. The new count can either be calculated by multiplying or dividing a percentage of the current APIC counts, or by incrementing/decrementing certain counts on the current APIC counts.
To avoid significant side effects on RTSS timers and timing-relative RTAPIs (processed by HAL ticks), the adjustment of the APIC counts should not be less than 90% or greater than 110% of the base APIC counts. Otherwise, RtSetHalTimerPeriodCounts returns FASLE and GetLastError returns ERROR_INVALID_PARAMETER.
Below is a matrix of the Real-Time APIs that are impacted by adjusting APIC Counts per HAL Timer Period:
Function | RTSS Behavior Change | Windows Behavior Change | Notes |
---|---|---|---|
RtGetClockTime | Shifted | No Change | On the RTSS side, the returning time is based on HAL ticks. On the Windows side, RtGetClockTime is implemented based on TSC. |
Shifted | Shifted | The expiration and interval of timers created by users are based on HAL ticks. | |
Shifted | No Change | On the RTSS side, the sleeping duration is based on HAL ticks. On the Windows side, the Real-Time APIs are based on the system timer. | |
Shifted | Shifted | The waiting timeout is based on HAL ticks. | |
RtkWaitForSingleObject / RtkWaitForMultipleObjects | N/A | Shifted | The waiting timeout is based on HAL ticks. |
RtSetThreadTimeQuantum / RtSetThreadTimeQuantumEx | Shifted | N/A | The time quantum is based on HAL ticks. |
RtSetFlushTLBTickMod | Shifted | N/A | The mod value is based on HAL ticks. |
RtGetThreadTimes | No Change | N/A | The times are based on system time. |
RtGetRtssTimeAsFileTime | No Change | N/A | The returning file time is converted from system time. |
No Change | No Change | The Real-Time and Windows APIs are based on TSC. | |
time | No Change | No Change | Time in C-Runtime returns system time. |
Below is a matrix of the RTX64 program samples that are impacted by adjusting APIC Counts per HAL Timer Period:
Sample | Impact |
---|---|
srtm.rtss | The number of expiration ticks and latency results are valid. |
srtm.exe | The results are invalid because of inconsistency between expiration tick interval and RtGetClockTime. |
ksrtm.exe | The latency results are valid. The number of expiration ticks is shifted because the sampling duration is based on system time. |
LatencyView | Latency results on RTSS cores are valid. Latency results on Windows cores are invalid. |
RtPerfMonitorEx.rtss | The results of response latency and ISR to IST latency are valid. HAL clock tick intervals represent the real durations. |
Requirements
Minimum Required Version | RTX64 3.3 |
Header | Rtapi.h |
Library | RtApi.lib (Windows), Rtx_Rtss.lib (RTSS) |
See Also: