Enum ControlRequest

pub enum ControlRequest {
    GetElements {
        responder: ControlGetElementsResponder,
    },
    WatchElementState {
        processing_element_id: u64,
        responder: ControlWatchElementStateResponder,
    },
    GetTopologies {
        responder: ControlGetTopologiesResponder,
    },
    WatchTopology {
        responder: ControlWatchTopologyResponder,
    },
    SetElementState {
        processing_element_id: u64,
        state: SettableElementState,
        responder: ControlSetElementStateResponder,
    },
    SetTopology {
        topology_id: u64,
        responder: ControlSetTopologyResponder,
    },
    SetGain {
        payload: ControlSetGainRequest,
        responder: ControlSetGainResponder,
    },
    CreateRingBuffer {
        payload: ControlCreateRingBufferRequest,
        responder: ControlCreateRingBufferResponder,
    },
    SetDaiFormat {
        payload: ControlSetDaiFormatRequest,
        responder: ControlSetDaiFormatResponder,
    },
    CodecStart {
        responder: ControlCodecStartResponder,
    },
    CodecStop {
        responder: ControlCodecStopResponder,
    },
    Reset {
        responder: ControlResetResponder,
    },
    _UnknownMethod {
        ordinal: u64,
        control_handle: ControlControlHandle,
        method_type: MethodType,
    },
}

A Control instance is used to change the settings or state of an audio device. It also creates the ring buffer used to pass audio data between client and device. Each Control is associated with an initialized audio device; conversely each device is associated with either zero or one Control at any time.

Variants

GetElements

Returns a vector of supported processing elements. Must return one or more processing elements, or ZX_ERR_NOT_SUPPORTED. If GetTopologies returns one or more topologies, then GetElements must return one or more elements.

Fields

responder: ControlGetElementsResponder

WatchElementState

Get the processing element state via a hanging get. For a given processing_element_id, the driver will reply to the first WatchElementState sent by the client. The driver will not respond to subsequent client WatchElementState calls for a given processing_element_id until any field of the Element table changes from what was most recently reported for that processing_element_id.

The driver will close the protocol channel with an error of ZX_ERR_BAD_STATE, if this method is called again while there is already a pending WatchElementState for this client and processing_element_id.

Fields

processing_element_id: u64

responder: ControlWatchElementStateResponder

GetTopologies

Returns a vector of supported topologies. Must return one or more topologies, or ZX_ERR_NOT_SUPPORTED. If more than one topology is returned, then the client may choose any of the topologies from the list with SetTopology. If only one topology is returned, then the topology definition is informational only since the one and only topology used can’t be changed with SetTopology. If GetElements returns one or more elements, then GetTopologies must return one or more topologies.

Fields

responder: ControlGetTopologiesResponder

WatchTopology

Get the current topology via a hanging get. The driver will immediately reply to the first WatchTopology sent by each client. The driver will not respond to subsequent WatchTopology calls from that client until the signal-processing topology changes, which occurs as a result of a SetTopology call. The driver will close the protocol channel with an error of ZX_ERR_BAD_STATE, if this method is called again while there is already a pending WatchTopology for this client.

Fields

responder: ControlWatchTopologyResponder

SetElementState

Controls a processing element using a unique ElementId returned by GetElements. Note that SettableElementState is a subset of ElementState, because some fields returned from WatchElementState (e.g. latency) can only be observed (not set) by the client.

Returns ZX_ERR_INVALID_ARGS if the processing_element_id does not match an id returned by GetElements or the type of SettableTypeSpecificElementState does not match the ElementType of the processing element returned by GetElements for this id. The driver may return ZX_ERR_INVALID_ARGS if the state values are invalid, i.e. any of the values violates rules specified in this protocol, e.g. trying to change an EQUALIZER processing element’s EqualizerBandState frequency when this processing element did not advertise CAN_CONTROL_FREQUENCY in its supported_controls.

SetElementState may be called before or after non-SignalProcessing protocol calls. If called after non-SignalProcessing protocol calls then SetElementState may or may not require renegotiation of the driver state as reached with calls of the protocol composing SignalProcessing, e.g. Dai. For instance, SetElementState changing an AGL processing element’s parameters may not require renegotiation of the Dai state because changing a gain parameter usually does not change the set of supported audio formats. By contrast, if SetElementState changes the parameters of a CONNECTION_POINT element, the change may require renegotiation because it may invalidate the set of supported formats returned in a previous GetDaiFormats Dai protocol call.

It is the driver’s job to determine when renegotiation is required. If renegotiation is required, then SetElementState must return ZX_ERR_BAD_STATE and the client must close the protocol channel such that the protocol negotiations are started over. The client then must make the SetElementState call that returned ZX_ERR_BAD_STATE before any non-SignalProcessing protocol calls.

Fields

processing_element_id: u64

state: SettableElementState

responder: ControlSetElementStateResponder

SetTopology

Sets the topology to be used using an id to the vector returned by GetTopologies. The current topology is communicated by WatchTopology responses. To change which topology is active, a client uses SetTopology. If the specified topology_id is not within thetopologies returned by GetTopologies, this call will return ZX_ERR_INVALID_ARGS. If GetTopologies returns only one Topology, SetTopology is optional and has no effect.

SetTopology may be called before or after non-SignalProcessing protocol calls. If called after non-SignalProcessing protocol calls, then SetTopology may return ZX_ERR_BAD_STATE to indicate that the operation can not proceed without renegotiation of the driver state. See SetElementState for further discussion.

Fields

topology_id: u64

responder: ControlSetTopologyResponder

SetGain

Change the device’s overall gain state.

Should only be called for StreamConfig devices.

Fields

payload: ControlSetGainRequest

responder: ControlSetGainResponder

CreateRingBuffer

Create the ring buffer used to pass audio to/from this device. If the device is Composite, then the targeted RING_BUFFER ENDPOINT must be identified by element_id.

Should only be called for Composite and StreamConfig devices.

Fields

payload: ControlCreateRingBufferRequest

responder: ControlCreateRingBufferResponder

SetDaiFormat

Set the wire format for the digital interconnect connected to this Codec endpoint. This method returns information related to the format that was set, including delay values. If the device is Composite, then the targeted DAI_INTERCONNECT ENDPOINT must be identified by element_id.

Should only be called for Codec and Composite devices.

Fields

payload: ControlSetDaiFormatRequest

responder: ControlSetDaiFormatResponder

CodecStart

Start the Codec hardware. If successful, this returns after the Codec was started and start_time indicates the time when the hardware started. Note that the Codec’s DaiFormat must be set (by a successful SetDaiFormat call) before calling this method.

Should only be called for Codec devices.

Fields

responder: ControlCodecStartResponder

CodecStop

Stop the Codec hardware. If successful, this returns after the Codec was stopped and stop_time indicates the time when the hardware stopped. Note that the Codec’s DaiFormat must be set (by a successful SetDaiFormat call) before calling this method.

Should only be called for Codec devices.

Fields

responder: ControlCodecStopResponder

Reset

Reset the hardware – stopping the hardware, releasing any ring buffers, and clearing any DaiFormats or RingBufferFormats that were set.

This method returns when the hardware reset is complete. After calling this method, the device is still controlled, but any ring buffers must be re-created and re-started. For devices with DAI_INTERCONNECTs (such as Codecs and some Composites), SetDaiFormat and CodecStart must be called again (in that order) to return the interconnect to the active operational mode. As applicable, SetTopology and SetElementState must also be called.

Should only be called for Codec and Composite devices.

Fields

responder: ControlResetResponder

_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: ControlControlHandle

method_type: MethodType

Implementations

impl ControlRequest

pub fn into_get_elements(self) -> Option<ControlGetElementsResponder>

pub fn into_watch_element_state( self, ) -> Option<(u64, ControlWatchElementStateResponder)>

pub fn into_get_topologies(self) -> Option<ControlGetTopologiesResponder>

pub fn into_watch_topology(self) -> Option<ControlWatchTopologyResponder>

pub fn into_set_element_state( self, ) -> Option<(u64, SettableElementState, ControlSetElementStateResponder)>

pub fn into_set_topology(self) -> Option<(u64, ControlSetTopologyResponder)>

pub fn into_set_gain( self, ) -> Option<(ControlSetGainRequest, ControlSetGainResponder)>

pub fn into_create_ring_buffer( self, ) -> Option<(ControlCreateRingBufferRequest, ControlCreateRingBufferResponder)>

pub fn into_set_dai_format( self, ) -> Option<(ControlSetDaiFormatRequest, ControlSetDaiFormatResponder)>

pub fn into_codec_start(self) -> Option<ControlCodecStartResponder>

pub fn into_codec_stop(self) -> Option<ControlCodecStopResponder>

pub fn into_reset(self) -> Option<ControlResetResponder>

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

Name of the method defined in FIDL

Trait Implementations

impl Debug for ControlRequest

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

Formats the value using the given formatter.