Miles Sound System SDK 7.2a

AIL_set_timer_frequency

The function AIL_set_timer_frequency programs a timer for callback service at frequencies ranging from 1 Hz (Hertz, or cycles per second) to 1,000,000 Hz.

void AIL_set_timer_frequency(
  HTIMER timer,
  U32 hertz
);

In Parameters

timer: is a handle to the timer to program.
hertz: specifies the desired callback rate in hertz (callbacks per second).

Discussion

Any one of three functions may be used to program a timer's callback rate. These functions are AIL_set_timer_period, AIL_set_timer_frequency, and AIL_set_timer_divisor. All three of these functions perform exactly the same task, but accept their values in different units. Frequency in megahertz, for example, is the reciprocal of period in microseconds. For slow timer repetition rates, greater precision may be obtained by expressing timer frequencies lower than one hertz (Hz) in reciprocal form, and calling AIL_set_timer_period instead.

In practice, the fastest possible rate will be substantially slower than the theoretical value due to the host system's interrupt-processing overhead. MSS may exhibit internal stack overflows if any timer is programmed for a rate of more than a thousand or so calls per second. This does not necessarily indicate a fault in either the DOS extender or MSS, but is a sign that the PC hardware in use is incapable of keeping up with the demands of very-high-speed timer service in protected mode.

Under normal circumstances, the programmed timer service rate will exhibit a long-term accuracy of better than ± 100 parts per million (ppm). This accuracy figure may be somewhat degraded under certain environments such as Microsoft Windows.

The fastest possible timer period available under the Windows MSS API is 5 milliseconds (200 Hz) by default. This period limit may be changed to as little as 1 millisecond (1000 Hz) by changing the AIL_MM_PERIOD preference value immediately after calling AIL_startup.

Group: Timer Services
Related Functions: AIL_register_timer, AIL_set_timer_divisor, AIL_set_timer_frequency, AIL_set_timer_period, AIL_startup
Related Basic Types: HTIMER, MILES_PREFERENCES, U32, void