| // Copyright 2023 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.hardware.audio; |
| |
| using fuchsia.hardware.audio.signalprocessing; |
| |
| @available(added=12) |
| type CompositeProperties = table { |
| /// Driver type is input (true) or output (false) |
| /// If not included, then the driver may be used for both input and output. |
| /// |
| /// Optional. |
| /// |
| /// # Deprecation |
| /// |
| /// Removed in favor of the signal processing topology describing the one or many |
| /// input and output pipelines that could not be expressed with this one field for |
| /// the whole driver. If the driver exposes only one input or output that is also |
| /// described by the signal processing topology. |
| @available(deprecated=12, removed=13) |
| 1: is_input bool; |
| |
| /// UI string for the manufacturer name. If not set, the manufacturer is unknown. |
| /// |
| /// Optional. |
| 2: manufacturer string:MAX_UI_STRING_SIZE; |
| |
| /// UI string for the product name. If not set, the product name is unknown. |
| /// |
| /// Optional. |
| 3: product string:MAX_UI_STRING_SIZE; |
| |
| /// A unique identifier. If not included, there is no unique id for the Device. |
| /// `unique_id` arrays starting with 0x42, 0x54, ... (or `BT` in ASCII) are |
| /// reserved for drivers implementing Bluetooth technologies. |
| /// `unique_id` arrays starting with 0x55, 0x53, 0x42, ... (or `USB` in ASCII) are |
| /// reserved for drivers implementing USB technologies. |
| /// Note that even though the above values map to readable ASCII characters, array |
| /// values can span the entire uint8 range (0-255). |
| /// |
| /// Optional. |
| 4: unique_id array<uint8, UNIQUE_ID_SIZE>; |
| |
| /// An identifier for the clock domain in which this hardware operates. If |
| /// two hardware devices have the same clock domain, their clock rates are |
| /// identical and perfectly synchronized. Although these two clocks have the |
| /// same rate, the clock positions may be offset from each other by an |
| /// arbitrary (but fixed) amount. The clock_domain typically comes from a |
| /// system wide entity, such as a platform bus or global clock tree. |
| /// |
| /// There are two special values: |
| /// |
| /// * `CLOCK_DOMAIN_MONOTONIC` means the hardware is operating at the same |
| /// rate as the system montonic clock. |
| /// |
| /// * `CLOCK_DOMAIN_EXTERNAL` means the hardware is operating at an unknown |
| /// rate and is not synchronized with any known clock, not even with |
| /// other clocks in domain `CLOCK_DOMAIN_EXTERNAL`. |
| /// |
| /// If the domain is not `CLOCK_DOMAIN_MONOTONIC`, client must use position |
| /// notification updates to recover the hardware's clock. |
| /// |
| /// Required. |
| 5: clock_domain ClockDomain; |
| }; |
| |
| /// The `Composite` interface is a FIDL protocol exposed by audio drivers. The `Composite` interface |
| /// is generic and allows the configuration of various audio hardware types including those supported |
| /// by the `StreamConfig`, `Dai` and `Codec` FIDL interfaces. The `Composite` interface is more |
| /// generic and provides more flexible routing within audio subsystems. Also see |
| /// [Audio Driver Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite.md) |
| @available(added=12) |
| closed protocol Composite { |
| /// Allows providing driver health state. |
| compose Health; |
| |
| /// Allows providing signal processing capabilities. |
| /// Supporting the `signalprocessing` protocols -- and exposing one or more elements and one or |
| /// more topologies -- is required for `Composite` implementations (unlike `Codec`, `Dai` and |
| /// `StreamConfig` implementations where this is optional). |
| compose fuchsia.hardware.audio.signalprocessing.Connector; |
| |
| /// Resets the hardware including all DAI interconnects and signal processing. |
| /// As a result, all channels obtained by `CreateRingBuffer` will be closed. |
| /// |
| /// `Reset` returns when the hardware is fully reset. At this point, a client would need to |
| /// reconfigure any DAI interconnects, select a signal processing topology and reconfigure |
| /// any processing elements, and reconstruct any ring buffers. |
| /// |
| /// If the driver can't successfully reset the hardware, it will return an error and then close |
| /// the protocol channel, in this case the client may obtain a new protocol channel and retry. |
| strict Reset() -> () error DriverError; |
| |
| /// Retrieves top level static properties. |
| strict GetProperties() -> (struct { |
| properties CompositeProperties; |
| }); |
| |
| /// Retrieves the ring buffer formats supported by a `RING_BUFFER` processing element |
| /// in the topology supported by this driver as returned by `GetElements` from |
| /// fuchsia.hardware.audio.signalprocessing. |
| /// Returns `SHOULD_WAIT` if the ring buffer formats are not available at the time, the |
| /// client may retry at a later time. |
| /// Returns `INVALID_ARGS` if the `processing_element_id` does not match an id returned |
| /// by `GetElements`. |
| /// Returns `WRONG_TYPE` if the `ElementType` of the element represented by the id is not |
| /// `RING_BUFFER`. |
| /// Retrieving multiple `SupportedFormats` allows for cases where exclusive combinations of |
| /// the parameters in `SupportedFormats` may be supported. |
| strict GetRingBufferFormats(struct { |
| processing_element_id uint64; |
| }) -> (struct { |
| ring_buffer_formats vector<SupportedFormats>:MAX_COUNT_FORMATS; |
| }) error DriverError; |
| |
| /// `CreateRingBuffer` is sent by clients to select a ring buffer format for the `RING_BUFFER` |
| /// processing element specified by `processing_element_id`. The format is based on information |
| /// that the driver provides in `GetRingBufferFormats`, what is supported by the client, and |
| /// any other requirement. The returned `ring_buffer` channel is used to access and control the |
| /// audio buffer provided by the driver. |
| /// Returns `INVALID_ARGS` if the `processing_element_id` does not match an id returned |
| /// by `GetElements`. |
| /// Returns `WRONG_TYPE` if the `ElementType` of the element represented by the id is not |
| /// `RING_BUFFER`. |
| strict CreateRingBuffer(resource struct { |
| processing_element_id uint64; |
| format Format; |
| ring_buffer server_end:RingBuffer; |
| }) -> () error DriverError; |
| |
| /// Retrieves the DAI formats supported by a `DAI_INTERCONNECT` processing element |
| /// in the topology supported by this driver as returned by `GetElements` from |
| /// fuchsia.hardware.audio.signalprocessing. |
| /// Returns `SHOULD_WAIT` if the DAI formats are not available at the time, the client |
| /// may retry at a later time. |
| /// Returns `INVALID_ARGS` if the `processing_element_id` does not match an id returned |
| /// by `GetElements`. |
| /// Returns `WRONG_TYPE` if the `ElementType` of the element represented by the id is not |
| /// `DAI_INTERCONNECT`. |
| /// Retrieving multiple `DaiSupportedFormats` allows for cases where exclusive combinations of |
| /// the parameters in SupportedFormats may be supported. |
| strict GetDaiFormats(struct { |
| processing_element_id uint64; |
| }) -> (struct { |
| dai_formats vector<DaiSupportedFormats>:MAX_COUNT_FORMATS; |
| }) error DriverError; |
| |
| /// `SetDaiFormat` is sent by clients to select a DAI format for the `DAI_INTERCONNECT` |
| /// processing element specified by `processing_element_id`. The format is based on information |
| /// that the driver provides in `GetDaiFormats`, what is supported by the client, and any other |
| /// requirement. |
| /// Returns `INVALID_ARGS` if the `processing_element_id` does not match an id returned |
| /// by `GetElements`. |
| /// Returns `WRONG_TYPE` if the `ElementType` of the element represented by the id is not |
| /// `DAI_INTERCONNECT`. |
| strict SetDaiFormat(struct { |
| processing_element_id uint64; |
| format DaiFormat; |
| }) -> () error DriverError; |
| }; |
| |
| @available(added=12) |
| service DeviceService { |
| device client_end:Composite; |
| }; |