sdk/fidl/fuchsia.hardware.audio/codec.fidl - fuchsia - Git at Google

 // Copyright 2020 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 zx;
 using fuchsia.hardware.audio.signalprocessing;

 /// Textual information about the codec.
 @available(deprecated=11, removed=12)
 type CodecInfo = struct {
     /// Unique identifier for the codec.
     unique_id string:UNIQUE_ID_SIZE;

     /// Name of the codec manufacturer.
     manufacturer string:MAX_UI_STRING_SIZE;

     /// Product name of the codec.
     product_name string:MAX_UI_STRING_SIZE;
 };

 @available(added=20)
 type CodecProperties = table {
     /// Driver type is input (true) or output (false)
     /// If not included, then the driver may be used for both input and output.
     ///
     /// Optional.
     1: is_input bool;

     /// UI string for the manufacturer name. If not included, the manufacturer is unspecified.
     ///
     /// Optional.
     2: manufacturer string:MAX_UI_STRING_SIZE;

     /// UI string for the product name. If not included, the product name is unspecified.
     ///
     /// Optional.
     3: product string:MAX_UI_STRING_SIZE;

     /// Unique identifier for the codec.
     /// If not included, there is no unique id for the Codec.
     ///
     /// Optional.
     4: unique_id array<uint8, UNIQUE_ID_SIZE>;

     /// Plug Detect Capabilities.
     ///
     /// Required.
     5: plug_detect_capabilities PlugDetectCapabilities;
 };

 /// Gain type of representation.
 ///
 /// # Deprecation
 ///
 /// Not needed anymore since the functionality is available in the signal processing API defined
 /// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
 /// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
 @available(deprecated=9, removed=12)
 type GainType = strict enum : uint8 {
     /// Gain specified in dB, for example -103.0dB or +3.2dB.
     DECIBELS = 1;

     /// Gain specified as a percentage, for example 10.0% or 80.5%.
     PERCENT = 2;
 };

 /// Gain format/parameters.
 ///
 /// # Deprecation
 ///
 /// Not needed anymore since the functionality is available in the signal processing API defined
 /// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
 /// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
 @available(deprecated=9, removed=12)
 type GainFormat = table {
     /// Specifies what the numbers for gain represent, e.g. a percentage.
     ///
     /// Required.
     1: type GainType;

     /// Minimum gain.
     ///
     /// Required.
     2: min_gain float32;

     /// Maximum gain.
     ///
     /// Required.
     3: max_gain float32;

     /// Gain step in decibels, this value must not be negative, but may be zero to convey an
     /// effectively continuous range of values. Must not exceed `max_gain_db` - `min_gain_db`.
     ///
     /// Required.
     4: gain_step float32;

     /// Gain mute capability. If not included, mute is not supported.
     ///
     /// Optional.
     5: can_mute bool;

     /// Automatic Gain Control (AGC) capability. If not included, AGC is not supported.
     ///
     /// Optional.
     6: can_agc bool;
 };

 /// Codec format information.
 type CodecFormatInfo = table {
     /// The driver's best estimate of the external delay (in nanoseconds) present in the pipeline
     /// for the chosen format. When precisely synchronizing presentation across multiple entities
     /// (e.g. devices), the external delay should be taken into account.
     /// If not included `external_delay` is unknown.
     ///
     /// Optional.
     1: external_delay zx.Duration;

     /// The driver's best estimate of the amount of time (in nanoseconds) it takes the hardware to
     /// actually start playback/capture after a `Start` command is issued.
     /// It may take some time for the hardware to get into fully operational mode, for example due
     /// a power state change. This delay must be taken into account if not getting the initial audio
     /// samples played or captured is not acceptable.
     /// If not included `turn_on_delay` is unknown.
     ///
     /// Optional.
     2: turn_on_delay zx.Duration;

     /// The driver's best estimate of the amount of time (in nanoseconds) it takes the hardware to
     /// actually stop playback/capture after a `Stop` command is issued.
     /// It may take some time for the hardware to get into fully stopped mode, for example due
     /// a power state change. This delay must be taken into account if playback/capture of samples
     /// after a 'Stop' command is not acceptable.
     /// If not included, the turn off delay is unknown.
     ///
     /// Optional.
     3: turn_off_delay zx.Duration;
 };

 /// For an overview see
 /// [[Audio Codec Interface]](https://fuchsia.dev/fuchsia-src/development/audio/drivers/codec).
 /// # Deprecation
 ///
 /// Not supported anymore, instead use an
 /// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
 /// with one DAI and no Ring Buffer, see
 /// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
 @available(deprecated=20)
 closed protocol Codec {
     /// Allows providing driver health state.
     compose Health;

     /// Allows providing signal processing capabilities.
     compose fuchsia.hardware.audio.signalprocessing.Connector;

     /// Resets the codec.
     /// `Reset` returns when the reset is completed. If the driver can't successfully reset the
     /// codec it will close the codec protocol channel, in this case the client may obtain a new
     /// codec protocol channel and retry.
     strict Reset() -> ();

     /// Retrieves textual information about the codec.
     @available(deprecated=11, removed=12)
     strict GetInfo() -> (struct {
         info CodecInfo;
     });

     /// Retrieves top level static properties.
     @available(added=20)
     strict GetProperties() -> (struct {
         properties CodecProperties;
     });

     /// Stops the codec operation.
     /// `Stop` returns when configuring the codec to stop is completed. This method does not wait
     /// for the hardware to actually stop playback/capture (i.e. `turn_off_delay` impact is not
     /// taken into account), nor is any such delay reflected in the returned `stop_time`.
     /// `stop_time` indicates when the driver finished configuring the codec to stop, as measured
     /// in the CLOCK_MONOTONIC timeline.
     /// If the driver cannot successfully configure the codec to stop, it will close the codec
     /// protocol channel, in which case the client may obtain a new codec protocol channel and retry.
     strict Stop() -> (struct {
         @available(removed=20)
         start_time zx.Time;

         @available(added=20)
         stop_time zx.Time;
     });

     /// Start/Re-start the codec operation.
     /// `Start` returns when configuring the codec to start is completed. This method does not wait
     /// for the hardware to actually start playback/capture (i.e. `turn_on_delay` impact is not taken
     /// into account), nor is any such delay reflected in the returned `start_time`.
     /// `start_time` indicates when the driver finished configuring the codec to start, as measured
     /// in the CLOCK_MONOTONIC timeline.
     /// If the driver can't successfully start the codec, it will close the codec protocol channel,
     /// in which case the client may obtain a new codec protocol channel and retry.
     strict Start() -> (struct {
         start_time zx.Time;
     });

     /// Returns whether a codec is bridgeable.
     ///
     /// # Deprecation
     ///
     /// Not supported anymore, bridged configurations are no longer changeable at runtime.
     /// A driver can still be configured to operate in bridged mode or not at boot time.
     @available(deprecated=17)
     strict IsBridgeable() -> (struct {
         supports_bridged_mode bool;
     });

     /// Sets a codec's bridged mode. This method is required, but it only needs to take action if
     /// the codec supports bridged mode as specified by its reply to `IsBridgeable`.
     ///
     /// # Deprecation
     ///
     /// Not supported anymore, bridged configurations are no longer changeable at runtime.
     /// A driver can still be configured to operate in bridged mode or not at boot time.
     @available(deprecated=17)
     strict SetBridgedMode(struct {
         enable_bridged_mode bool;
     });

     /// Retrieves the DAI formats supported by the codec, if not available at the time the codec
     /// may reply with an error status and the controller may retry at a later time.
     /// Retrieving multiple DaiSupportedFormats allows for cases where exclusive
     /// combinations of the parameters in DaiSupportedFormats may be supported.
     strict GetDaiFormats() -> (struct {
         formats vector<DaiSupportedFormats>:MAX_COUNT_FORMATS;
     }) error zx.Status;

     /// Sets the DAI format to be used in the interface between the controller and codec.
     /// Returns an error if not supported at the time of the request (e.g. for removable hardware).
     strict SetDaiFormat(struct {
         format DaiFormat;
     }) -> (struct {
         state CodecFormatInfo;
     }) error zx.Status;

     /// Retrieves gain format.
     ///
     /// # Deprecation
     ///
     /// Not needed anymore since the functionality is available in the signal processing API defined
     /// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
     /// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
     @available(deprecated=9, removed=12)
     strict GetGainFormat() -> (struct {
         gain_format GainFormat;
     });

     /// Retrieves Plug Detect Capabilities.
     @available(deprecated=11, removed=12)
     strict GetPlugDetectCapabilities() -> (struct {
         plug_detect_capabilities PlugDetectCapabilities;
     });

     /// Get the gain state via a hanging get. The driver will reply to the first `WatchGainState`
     /// sent by the client and this reply must include a `gain_db` set to 0dB or lower. The driver
     /// will not respond to subsequent client `WatchGainState` calls until the gain state changes
     /// from what was most recently reported.
     ///
     /// # Deprecation
     ///
     /// Not needed anymore since the functionality is available in the signal processing API defined
     /// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
     /// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
     @available(deprecated=9, removed=12)
     strict WatchGainState() -> (struct {
         gain_state GainState;
     });

     /// Client update of the gain state.
     ///
     /// # Deprecation
     ///
     /// Not needed anymore since the functionality is available in the signal processing API defined
     /// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
     /// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
     @available(deprecated=9, removed=12)
     strict SetGainState(struct {
         target_state GainState;
     });

     /// Get the plug detect state via a hanging get. The driver will reply to the first
     /// `WatchPlugState` sent by the client. The driver will not respond to subsequent client
     /// `WatchPlugState` calls until the plug state changes from what was most recently reported.
     strict WatchPlugState() -> (struct {
         plug_state PlugState;
     });
 };

 /// # Deprecation
 ///
 /// Not supported anymore, instead use an
 /// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
 /// with one DAI and no Ring Buffer, see
 /// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
 @available(deprecated=20)
 service CodecService {
     codec client_end:Codec;
 };
	// Copyright 2020 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 zx;
	using fuchsia.hardware.audio.signalprocessing;

	/// Textual information about the codec.
	@available(deprecated=11, removed=12)
	type CodecInfo = struct {
	/// Unique identifier for the codec.
	unique_id string:UNIQUE_ID_SIZE;

	/// Name of the codec manufacturer.
	manufacturer string:MAX_UI_STRING_SIZE;

	/// Product name of the codec.
	product_name string:MAX_UI_STRING_SIZE;
	};

	@available(added=20)
	type CodecProperties = table {
	/// Driver type is input (true) or output (false)
	/// If not included, then the driver may be used for both input and output.
	///
	/// Optional.
	1: is_input bool;

	/// UI string for the manufacturer name. If not included, the manufacturer is unspecified.
	///
	/// Optional.
	2: manufacturer string:MAX_UI_STRING_SIZE;

	/// UI string for the product name. If not included, the product name is unspecified.
	///
	/// Optional.
	3: product string:MAX_UI_STRING_SIZE;

	/// Unique identifier for the codec.
	/// If not included, there is no unique id for the Codec.
	///
	/// Optional.
	4: unique_id array<uint8, UNIQUE_ID_SIZE>;

	/// Plug Detect Capabilities.
	///
	/// Required.
	5: plug_detect_capabilities PlugDetectCapabilities;
	};

	/// Gain type of representation.
	///
	/// # Deprecation
	///
	/// Not needed anymore since the functionality is available in the signal processing API defined
	/// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
	/// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
	@available(deprecated=9, removed=12)
	type GainType = strict enum : uint8 {
	/// Gain specified in dB, for example -103.0dB or +3.2dB.
	DECIBELS = 1;

	/// Gain specified as a percentage, for example 10.0% or 80.5%.
	PERCENT = 2;
	};

	/// Gain format/parameters.
	///
	/// # Deprecation
	///
	/// Not needed anymore since the functionality is available in the signal processing API defined
	/// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
	/// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
	@available(deprecated=9, removed=12)
	type GainFormat = table {
	/// Specifies what the numbers for gain represent, e.g. a percentage.
	///
	/// Required.
	1: type GainType;

	/// Minimum gain.
	///
	/// Required.
	2: min_gain float32;

	/// Maximum gain.
	///
	/// Required.
	3: max_gain float32;

	/// Gain step in decibels, this value must not be negative, but may be zero to convey an
	/// effectively continuous range of values. Must not exceed `max_gain_db` - `min_gain_db`.
	///
	/// Required.
	4: gain_step float32;

	/// Gain mute capability. If not included, mute is not supported.
	///
	/// Optional.
	5: can_mute bool;

	/// Automatic Gain Control (AGC) capability. If not included, AGC is not supported.
	///
	/// Optional.
	6: can_agc bool;
	};

	/// Codec format information.
	type CodecFormatInfo = table {
	/// The driver's best estimate of the external delay (in nanoseconds) present in the pipeline
	/// for the chosen format. When precisely synchronizing presentation across multiple entities
	/// (e.g. devices), the external delay should be taken into account.
	/// If not included `external_delay` is unknown.
	///
	/// Optional.
	1: external_delay zx.Duration;

	/// The driver's best estimate of the amount of time (in nanoseconds) it takes the hardware to
	/// actually start playback/capture after a `Start` command is issued.
	/// It may take some time for the hardware to get into fully operational mode, for example due
	/// a power state change. This delay must be taken into account if not getting the initial audio
	/// samples played or captured is not acceptable.
	/// If not included `turn_on_delay` is unknown.
	///
	/// Optional.
	2: turn_on_delay zx.Duration;

	/// The driver's best estimate of the amount of time (in nanoseconds) it takes the hardware to
	/// actually stop playback/capture after a `Stop` command is issued.
	/// It may take some time for the hardware to get into fully stopped mode, for example due
	/// a power state change. This delay must be taken into account if playback/capture of samples
	/// after a 'Stop' command is not acceptable.
	/// If not included, the turn off delay is unknown.
	///
	/// Optional.
	3: turn_off_delay zx.Duration;
	};

	/// For an overview see
	/// [[Audio Codec Interface]](https://fuchsia.dev/fuchsia-src/development/audio/drivers/codec).
	/// # Deprecation
	///
	/// Not supported anymore, instead use an
	/// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
	/// with one DAI and no Ring Buffer, see
	/// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
	@available(deprecated=20)
	closed protocol Codec {
	/// Allows providing driver health state.
	compose Health;

	/// Allows providing signal processing capabilities.
	compose fuchsia.hardware.audio.signalprocessing.Connector;

	/// Resets the codec.
	/// `Reset` returns when the reset is completed. If the driver can't successfully reset the
	/// codec it will close the codec protocol channel, in this case the client may obtain a new
	/// codec protocol channel and retry.
	strict Reset() -> ();

	/// Retrieves textual information about the codec.
	@available(deprecated=11, removed=12)
	strict GetInfo() -> (struct {
	info CodecInfo;
	});

	/// Retrieves top level static properties.
	@available(added=20)
	strict GetProperties() -> (struct {
	properties CodecProperties;
	});

	/// Stops the codec operation.
	/// `Stop` returns when configuring the codec to stop is completed. This method does not wait
	/// for the hardware to actually stop playback/capture (i.e. `turn_off_delay` impact is not
	/// taken into account), nor is any such delay reflected in the returned `stop_time`.
	/// `stop_time` indicates when the driver finished configuring the codec to stop, as measured
	/// in the CLOCK_MONOTONIC timeline.
	/// If the driver cannot successfully configure the codec to stop, it will close the codec
	/// protocol channel, in which case the client may obtain a new codec protocol channel and retry.
	strict Stop() -> (struct {
	@available(removed=20)
	start_time zx.Time;

	@available(added=20)
	stop_time zx.Time;
	});

	/// Start/Re-start the codec operation.
	/// `Start` returns when configuring the codec to start is completed. This method does not wait
	/// for the hardware to actually start playback/capture (i.e. `turn_on_delay` impact is not taken
	/// into account), nor is any such delay reflected in the returned `start_time`.
	/// `start_time` indicates when the driver finished configuring the codec to start, as measured
	/// in the CLOCK_MONOTONIC timeline.
	/// If the driver can't successfully start the codec, it will close the codec protocol channel,
	/// in which case the client may obtain a new codec protocol channel and retry.
	strict Start() -> (struct {
	start_time zx.Time;
	});

	/// Returns whether a codec is bridgeable.
	///
	/// # Deprecation
	///
	/// Not supported anymore, bridged configurations are no longer changeable at runtime.
	/// A driver can still be configured to operate in bridged mode or not at boot time.
	@available(deprecated=17)
	strict IsBridgeable() -> (struct {
	supports_bridged_mode bool;
	});

	/// Sets a codec's bridged mode. This method is required, but it only needs to take action if
	/// the codec supports bridged mode as specified by its reply to `IsBridgeable`.
	///
	/// # Deprecation
	///
	/// Not supported anymore, bridged configurations are no longer changeable at runtime.
	/// A driver can still be configured to operate in bridged mode or not at boot time.
	@available(deprecated=17)
	strict SetBridgedMode(struct {
	enable_bridged_mode bool;
	});

	/// Retrieves the DAI formats supported by the codec, if not available at the time the codec
	/// may reply with an error status and the controller may retry at a later time.
	/// Retrieving multiple DaiSupportedFormats allows for cases where exclusive
	/// combinations of the parameters in DaiSupportedFormats may be supported.
	strict GetDaiFormats() -> (struct {
	formats vector<DaiSupportedFormats>:MAX_COUNT_FORMATS;
	}) error zx.Status;

	/// Sets the DAI format to be used in the interface between the controller and codec.
	/// Returns an error if not supported at the time of the request (e.g. for removable hardware).
	strict SetDaiFormat(struct {
	format DaiFormat;
	}) -> (struct {
	state CodecFormatInfo;
	}) error zx.Status;

	/// Retrieves gain format.
	///
	/// # Deprecation
	///
	/// Not needed anymore since the functionality is available in the signal processing API defined
	/// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
	/// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
	@available(deprecated=9, removed=12)
	strict GetGainFormat() -> (struct {
	gain_format GainFormat;
	});

	/// Retrieves Plug Detect Capabilities.
	@available(deprecated=11, removed=12)
	strict GetPlugDetectCapabilities() -> (struct {
	plug_detect_capabilities PlugDetectCapabilities;
	});

	/// Get the gain state via a hanging get. The driver will reply to the first `WatchGainState`
	/// sent by the client and this reply must include a `gain_db` set to 0dB or lower. The driver
	/// will not respond to subsequent client `WatchGainState` calls until the gain state changes
	/// from what was most recently reported.
	///
	/// # Deprecation
	///
	/// Not needed anymore since the functionality is available in the signal processing API defined
	/// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
	/// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
	@available(deprecated=9, removed=12)
	strict WatchGainState() -> (struct {
	gain_state GainState;
	});

	/// Client update of the gain state.
	///
	/// # Deprecation
	///
	/// Not needed anymore since the functionality is available in the signal processing API defined
	/// at //sdk/fidl/fuchsia.hardware.audio.signalprocessing. Use a `Gain` `Element` instead, see
	/// //sdk/fidl/fuchsia.hardware.audio.signalprocessing/gain.fidl.
	@available(deprecated=9, removed=12)
	strict SetGainState(struct {
	target_state GainState;
	});

	/// Get the plug detect state via a hanging get. The driver will reply to the first
	/// `WatchPlugState` sent by the client. The driver will not respond to subsequent client
	/// `WatchPlugState` calls until the plug state changes from what was most recently reported.
	strict WatchPlugState() -> (struct {
	plug_state PlugState;
	});
	};

	/// # Deprecation
	///
	/// Not supported anymore, instead use an
	/// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
	/// with one DAI and no Ring Buffer, see
	/// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
	@available(deprecated=20)
	service CodecService {
	codec client_end:Codec;
	};