RtSetHalTimerPeriodCounts

RtSetHalTimerPeriodCounts sets the APIC counts per wRTOS HAL timer period.

Syntax

Copy

bool RtSetHalTimerPeriodCounts(
    [in]    ULONG PeriodicCounts
);

Parameters

[in] PeriodicCounts

Specifies a new value for the APIC counts per wRTOS HAL timer period.

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. Call GetLastError to obtain an error code.

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.
RtSetTimer RtSetTimerRelative	Shifted	Shifted	The expiration and interval of timers created by users are based on HAL ticks.
Sleep SleepEx RtSleepFt / RtSleepFtEx	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.
RtWaitForSingleObject / RtWaitForSingleObjectEx RtWaitForMultipleObjects / RtWaitForMultipleObjectsEx	Shifted	Shifted	The waiting timeout is based on HAL ticks.
RtkWaitForSingleObject / RtkWaitForMultipleObjects	N/A	Shifted	The waiting timeout 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.
RtQueryPerformanceCounter RtQueryPerformanceFrequency	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 wRTOS 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 supported version	Header	Library
wRTOS 1.0 SDK	RtApi.h	RtApi.lib (Windows), Startup.lib (RTSS)