Enum RingBufferRequest 

pub enum RingBufferRequest {
    GetProperties {
        responder: RingBufferGetPropertiesResponder,
    },
    WatchClockRecoveryPositionInfo {
        responder: RingBufferWatchClockRecoveryPositionInfoResponder,
    },
    GetVmo {
        min_frames: u32,
        clock_recovery_notifications_per_ring: u32,
        responder: RingBufferGetVmoResponder,
    },
    Start {
        responder: RingBufferStartResponder,
    },
    Stop {
        responder: RingBufferStopResponder,
    },
    SetActiveChannels {
        active_channels_bitmask: u64,
        responder: RingBufferSetActiveChannelsResponder,
    },
    WatchDelayInfo {
        responder: RingBufferWatchDelayInfoResponder,
    },
    #[non_exhaustive]
    _UnknownMethod {
        ordinal: u64,
        control_handle: RingBufferControlHandle,
        method_type: MethodType,
    },
}

Ring buffers are used to convey audio between parties (usually in different processes), allowing concurrent, asynchronous data access without requiring locks. This pattern works because both parties share an understanding of which buffer areas are safe to access, and how those areas change over time.

For in-depth description of the responsibilities for both producers and consumers, before the ring buffer is started as well as while it is active, please see Ring Buffer Behavior.

Variants

GetProperties

Accessor for top level static properties.

Fields

responder: RingBufferGetPropertiesResponder

WatchClockRecoveryPositionInfo

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 asCLOCK_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.

Fields

responder: RingBufferWatchClockRecoveryPositionInfoResponder

GetVmo

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.

Fields

min_frames: u32

clock_recovery_notifications_per_ring: u32

responder: RingBufferGetVmoResponder

Start

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.

Fields

responder: RingBufferStartResponder

Stop

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.

Fields

responder: RingBufferStopResponder

SetActiveChannels

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.

Fields

active_channels_bitmask: u64

responder: RingBufferSetActiveChannelsResponder

WatchDelayInfo

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.

Fields

responder: RingBufferWatchDelayInfoResponder

#[non_exhaustive]

_UnknownMethod

An interaction was received which does not match any known method.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

ordinal: u64

Ordinal of the method that was called.

control_handle: RingBufferControlHandle

method_type: MethodType

Implementations

impl RingBufferRequest

pub fn into_get_properties(self) -> Option<RingBufferGetPropertiesResponder>

pub fn into_watch_clock_recovery_position_info( self, ) -> Option<RingBufferWatchClockRecoveryPositionInfoResponder>

pub fn into_get_vmo(self) -> Option<(u32, u32, RingBufferGetVmoResponder)>

pub fn into_start(self) -> Option<RingBufferStartResponder>

pub fn into_stop(self) -> Option<RingBufferStopResponder>

pub fn into_set_active_channels( self, ) -> Option<(u64, RingBufferSetActiveChannelsResponder)>

pub fn into_watch_delay_info(self) -> Option<RingBufferWatchDelayInfoResponder>

pub fn method_name(&self) -> &'static str

Name of the method defined in FIDL

Trait Implementations

impl Debug for RingBufferRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.