KSPROPERTY_RTAUDIO_CLOCKREGISTER

The KSPROPERTY_RTAUDIO_CLOCKREGISTER property maps the wall clock register of the audio device into a virtual memory location that the client can access.

The following table summarizes the features of this property.

Usage Summary Table

The property descriptor (instance data) consists of a KSRTAUDIO_HWREGISTER_PROPERTY structure that contains a KSPROPERTY structure. Before sending the request, the client loads the KSRTAUDIO_HWREGISTER_PROPERTY structure with values that indicate the preferred base address for the clock register.

The property value (operation data) is a pointer to a KSRTAUDIO_HWREGISTER structure into which the property handler writes the register address and the register-update frequency. This register address is the user-mode or kernel-mode virtual address into which the hardware register is mapped. The client can directly read the register from this address.

Return Value

A KSPROPERTY_RTAUDIO_CLOCKREGISTER property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an error code that indicates a failure.

Remarks

Some audio devices contain clock registers. A clock register is a wall clock counter that starts running when the hardware powers up and stops when the hardware powers down. Software uses clock registers to synchronize between two or more controller devices by measuring the relative drift between the hardware clocks of the device.

If successful, the property request maps the clock register to a virtual memory address that is accessible from either user-mode or kernel-mode, as specified by the client. Thereafter, the client reads from this address to obtain the current value of the clock register.

The property request fails if the audio hardware does not support a clock register that can be mapped to virtual memory.

The mapping of the clock register is destroyed when the pin closes. The client can map the register only once in the lifetime of a pin instance, and any subsequent call to map the clock register again for that instance fails.

It is typically faster to read a clock register than it is to send a KSPROPERTY_CLOCK_TIME request, which requires transitions between user-mode and kernel-mode for user-mode clients.

Requirements

See also

KSRTAUDIO_HWREGISTER_PROPERTY

KSRTAUDIO_HWREGISTER