class RingBuffer

Accessor for top level static properties.

Gets the ring buffer current position via a hanging get.

`WatchClockRecoveryPositionInfo` may only be called after `GetVmo` was called, where a

`clock_recovery_notifications_per_ring` was specified.

The driver must respond to a client's first `WatchClockRecoveryPositionInfo` call, but will

not respond to subsequent client calls until the position information has changed from what

was most recently provided to that client.

The driver must not respond to a `WatchClockRecoveryPositionInfo` until after it has replied

to the `Start` command.

At the `start_time` returned by `Start`, position is always 0. From there, it

progresses at the rate specified by the rate, sample format (and clock domain,

if the device is not in the same clock domain as`CLOCK_MONOTONIC`).

If `clock_recovery_notifications_per_ring` is not zero, the driver will reply with its

estimated position to be used for clock recovery at most at

`clock_recovery_notifications_per_ring` frequency.

The `RingBufferPositionInfo` return values must include timestamps that are monotonically

increasing.

The driver will close the protocol channel with an error of `ZX_ERR_BAD_STATE`, if there is

already a pending `WatchClockRecoveryPositionInfo` for this client.

Requests a shared buffer to be used for moving bulk audio data between client and driver.

The client requests `min_frames` as the size for part of the ring buffer it needs.

The driver returns the actual size of allocated ring buffer space in `num_frames`.

`num_frames` must be at least `min_frames` plus `driver_transfer_bytes` (in frames) such

that ring buffer contents can be transfered in and out, or else the call must be failed

with GetVmoError.INVALID_ARGS.

The driver may increase the ring buffer size beyond `min_frames` plus

`driver_transfer_bytes` (in frames) due to any internal requirements, for instance

alignment.

Clients can treat the entire returned ring buffer as safe to access, except for the

`driver_transfer_bytes` immediately adjacent to the current position, see the

`driver_transfer_bytes` parameter specification in `RingBufferProperties` for more details.

The returned VMO handle must include ZX_RIGHT_TRANSFER, ZX_RIGHT_READ and ZX_RIGHT_MAP.

If the ring buffer is "outgoing" (conveys audio data from client to device), then the

handle must also include ZX_RIGHT_WRITE.

If `clock_recovery_notifications_per_ring` is non-zero, the driver will send replies to

`WatchClockRecoveryPositionInfo` client requests at most at

`clock_recovery_notifications_per_ring` frequency. These notifications are meant to be used

for clock recovery.

Start the ring buffer.

The `start_time` value (in the CLOCK_MONOTONIC timeline) indicates when position began

moving, starting at the beginning of the ring buffer, i.e. the driver has started to read or

write from or to the ring buffer position 0, subject to the overall position and buffering

behavior described in 'Ring buffer behavior' below.

If `Start` is called before `GetVmo`, the channel must be closed with `ZX_ERR_BAD_STATE`.

If `Start` is called while this RingBuffer is already started, or if `Start` is called for

a second time before the first call has completed, then the channel must be closed with an

error `ZX_ERR_BAD_STATE` returned.

If `Start` is called before `SetActiveChannels`, then by default all channels are active.

Stop the ring buffer.

Once this call's response is received, no further position notifications will be sent until

`Start` is called again.

If `Stop` is called before `GetVmo`, the channel must be closed with `ZX_ERR_BAD_STATE`.

Sets which channels are active via a bitmask.

The total number of channels is the `number_of_channels` in `Format`, specifically in

`PcmFormat`, i.e. this bitmask has up to `number_of_channels` bits set (maximum 64).

The least significant bit corresponds to channel index 0. Channels not set (bits are 0) in

the bitmask are inactive. By default all channels are active. Hence creating a RingBuffer

turns on the hardware associated for all channels.

Inactive channels indicate to the driver that it may turn off hardware associated with the

inactive channels. A subsequent `SetActiveChannels` setting an inactive channel to active

may incur in a `turn_on_delay` to actually restart playback/capture of the channels.

Deactivating one, several, or all channels does not `Stop` the ring buffer, nor does it

change the ring buffer's behavior with regard to position. Once `Start` is called, a ring

buffer's position advances (and position notifications sent as needed) regardless of the

number of active channels, including if no channels are active. This means that the format

in the ring buffer is not changed.

If the driver does not support deactivating channels, it must return `ZX_ERR_NOT_SUPPORTED`.

If the mask is incorrect, i.e. enables channels outside the number of bits to use for a

given `number_of_channels`, then the driver must return `ZX_ERR_INVALID_ARGS`.

The `set_time` value (in the CLOCK_MONOTONIC timeline) indicates when configuring

the hardware to activate or deactivate channels is completed. `set_time` does not include

the potential `turn_on_delay`, the driver does not delay the reply waiting for the

hardware to actually turn on, the driver replies with a `set_time` indicating when the

hardware configuration was completed. If the requested channel configuration is already

active, the returned `set_time` can be before `SetActiveChannels` was called but must be

before the reply is sent. If called again with the same configuration, the reply must

include the same `set_time` value as was previously returned.

For input channels, it is not required that the driver zero-out inactive channels.

If `SetActiveChannels` is called for a second time before the first call has completed,

the channel must be closed with an error `ZX_ERR_BAD_STATE` returned.

Get information about delays via a hanging get.

The driver will immediately reply to the first `WatchDelayInfo` sent by the client.

The driver will not respond to subsequent client `WatchDelayInfo` calls until the delay info

changes from what was most recently reported.

If `WatchDelayInfo` is called for a second time before the first call has completed, the

channel must be closed with an error `ZX_ERR_BAD_STATE` returned.