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

 // Copyright 2019 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;

 /// Delay information as returned by the driver.
 @available(added=HEAD)
 type DelayInfo = table {
     /// The driver's best estimate of the delay internal to the hardware it abstracts for
     /// the chosen format.
     ///
     /// `internal_delay` must be taken into account by the client when determining either
     /// the minimum lead time requirement (for playback) or the minimum capture delay (for
     /// capture).
     ///
     /// The data plane contents must be produced and consumed at the rate specified by the drivers
     /// configuration. However, some amount of buffering is required when moving data (for instance
     /// reading from or writing into the ring buffer for StreamConfig and Dai drivers), and this
     /// adds delay. In addition to this minimum buffering, more delay may be incurred by additional
     /// processing done in hardware or software.
     ///
     /// In many cases the hardware abstracted by the driver mostly adds delay in the form of a
     /// FIFO buffer used to transfer data in and out of an audio interconnect.
     /// In these cases, when consuming playback data, the hardware reads ahead by enough samples
     /// to fill the FIFO buffer; when producing capture data, samples are first held in the FIFO
     /// buffer before they are committed it to main system memory.
     /// In these cases `internal_delay` can be calculated based on the rate, frame size and the size
     /// of a hardware FIFO block.
     ///
     /// Required.
     1: internal_delay zx.duration;

     /// The driver's best estimate of the delay external to the hardware it abstracts for
     /// the chosen format. If not included `external_delay` is unknown. If unknown, the
     /// client may treat `external_delay` as it chooses, e.g. may autodetect it, consider
     /// it zero, consider it a large number, etc.
     ///
     /// `external_delay` must be taken into account by the client when determining either
     /// the minimum lead time requirement (for playback) or the minimum capture delay (for
     /// capture).
     2: external_delay zx.duration;
 };

 /// Properties of the ring buffer. These values don't change once the ring buffer is created.
 type RingBufferProperties = table {
     /// The driver's best estimate of the external delay present in the presentation 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.
     //
     // # Deprecation
     //
     // Not needed anymore since the functionality is available via `WatchDelayInfo` below.
     // Should match `DelayInfo` `external_delay` until it's removed.
     @available(deprecated=9)
     1: external_delay zx.duration;

     /// Size (in bytes) representing a temporary buffer used by the driver in order to consume or
     /// generate the ring buffer contents. Required.
     /// The ring buffer contents must be produced and consumed at the rate specified with the
     /// `CreateRingBuffer` command, however some amount of buffering is required when the data is
     /// written into and read from the ring buffer. For playback the data is consumed by the driver
     /// by reading ahead up to `fifo_depth` bytes. For capture the data is produced by the driver
     /// holding up to `fifo_depth` bytes at the time before committing it to main system
     /// memory. Hence `fifo_depth` must be taken into account by the client when determining either
     /// the minimum lead time requirement (for playback) or the maximum capture delay (for capture).
     ///
     /// To convert `fifo_depth` to the corresponding number of audio frames, use the frame size
     /// returned by `CreateRingBuffer` in the `StreamConfig` protocol, note that the `fifo_depth`
     /// is not necessarily a multiple size of an audio frame.
     ///
     /// The ring buffer data may be directly consumed/generated by hardware, in this case
     /// `fifo_depth` maps directly to the size of a hardware FIFO block, since the hardware FIFO
     /// block determines the amount of data read ahead or held back.
     ///
     /// The ring buffer data may instead be consumed/generated by audio driver software that is
     /// conceptually situated between the ring buffer and the audio hardware. In this case, for
     /// playback the `fifo_depth` read ahead amount is set large enough such that the driver
     /// guarantees no undetected underruns, this assuming the client is generating the data as
     /// determined by the `CreateRingBuffer` and `Start` commands. For capture, the
     /// `fifo_depth` held back amount is set large enough such that the driver guarantees no
     /// undetected underruns when generating the data as determined by the `CreateRingBuffer` and
     /// `Start` commands. The driver must set `fifo_depth` big enough such that the potential
     /// delays added by any software interfacing with the audio hardware do not occur under most
     /// scenarios, and must detect and report underruns. How an underrun is reported is not defined
     /// in this API.
     //
     // # Deprecation
     //
     // Not needed anymore since the functionality is available via `WatchDelayInfo` below.
     // Should match `DelayInfo` `internal_delay` equivalent until it's removed.
     @available(deprecated=9)
     2: fifo_depth uint32;

     /// When set to true, indicates that the ring buffer runs in a different cache coherency domain,
     /// hence clients need to make sure that their data has been flushed all the way to main memory
     /// (in the case of playback) or that their view of the ring buffer will need to be invalidated
     /// before read (in the case of capture).
     ///
     /// When set to false, indicates that the ring buffer runs in the same cache coherency domain,
     /// hence the driver does not require flushing/invalidation, as in there is no hardware external
     /// to the CPUs reading/writing from/to main memory bypassing the CPUs.
     /// Note that in this case the driver and client still need to make sure they synchronize their
     /// access to the data, for instance inserting the appropriate acquire fences before reading
     /// and release fences after writing.
     ///
     /// Required.
     3: needs_cache_flush_or_invalidate bool;

     /// The driver's best estimate of the amount of time it takes the hardware to actually start
     /// playback/capture, after a channel is activated by `SetActiveChannels`.
     /// Restated: the driver estimates that after `SetActiveChannels` enables a channel, its data
     /// will resume flowing at approximately `set_time` + `turn_on_delay`.
     /// It may take some time for the hardware to get into fully operational mode, for example due
     /// a power state change or communication delays within the driver's multiple hardware entities
     /// as in a Bluetooth driver. 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.
     4: turn_on_delay zx.duration;
 };

 type RingBufferPositionInfo = struct {
     /// The driver's best estimate of the time (in the CLOCK_MONOTONIC timeline) at which the
     /// playback/capture pointer reached the position indicated by `position`.
     /// `turn_on_delay` impact should not be incorporated into 'timestamp'.
     /// No delays indicated in `DelayInfo` should be incorporated.
     timestamp zx.time;

     /// The playback/capture pointer position (in bytes) in the ring buffer at time
     /// `timestamp` as estimated by the driver.
     position uint32;
 };

 type GetVmoError = strict enum {
     /// The ring buffer setup failed due to an invalid argument, e.g. min_frames is too big.
     INVALID_ARGS = 1;

     /// The ring buffer setup failed due to an internal error.
     INTERNAL_ERROR = 2;
 };

 /// For an overview see
 /// [Audio Driver Streaming Interface](https://fuchsia.dev/fuchsia-src/concepts/drivers/driver_architectures/audio_drivers/audio_streaming)
 protocol RingBuffer {
     /// Accessor for top level static properties.
     GetProperties() -> (struct {
         properties RingBufferProperties;
     });

     /// Gets the ring buffer current position via a hanging get. 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. 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.
     /// `WatchClockRecoveryPositionInfo` may only be called after `GetVmo` was called, hence a
     /// `clock_recovery_notifications_per_ring` was specified.
     /// Must be delivered with timestamps that are monotonically increasing.
     WatchClockRecoveryPositionInfo() -> (struct {
         position_info RingBufferPositionInfo;
     });

     /// Requests a shared buffer to be used for moving bulk audio data. Requests the buffer size to
     /// fit at least `min_frames`, and returns the actual `num_frames` allocated in
     /// `ring_buffer`.
     ///
     /// 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.
     ///
     // TODO(fxbug.dev/116353): Reconsider the `clock_recovery_notifications_per_ring` parameter,
     // once we must recover a clock from a device being actively rate-adjusted in hardware.
     // TODO(fxbug.dev/116355): Clarify that drivers must incorporate "device DMA chunk size" into
     // the final ring-buffer size, so that a client can safely operate within their `min_frames`.
     GetVmo(struct {
         min_frames uint32;
         clock_recovery_notifications_per_ring uint32;
     }) -> (resource struct {
         num_frames uint32;
         ring_buffer zx.handle:VMO;
     }) error GetVmoError;

     /// 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.
     /// external_delay impact should not be incorporated into 'start_time'.
     /// If `Start` is called before `SetActiveChannels`, then by default all channels are active.
     /// 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, the channel must be closed
     /// with an error `ZX_ERR_BAD_STATE` returned.
     Start() -> (struct {
         start_time zx.time;
     });

     /// 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`.
     // TODO(fxbug.dev/39494): Add timestamp parameter.
     Stop() -> ();

     /// Sets which channels are active via a bitmask.
     /// The least significant bit corresponds to channel index 0.
     /// Channels not set (bits are 0) in the bitmask are inactive.
     /// 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.
     /// 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).
     /// Deactivating one, several, or all channels does not `Stop` the ring buffer.
     /// `SetActiveChannels` does not change the ring buffer's behavior with regard to
     /// `Start`/`Stop`, specifically 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.
     /// By default all channels are active.
     /// 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 may 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.
     /// For input channels, it is not required that the driver zero-out inactive channels.
     SetActiveChannels(struct {
         active_channels_bitmask uint64;
     }) -> (struct {
         set_time zx.time;
     }) error zx.status;

     /// 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.
     @available(added=HEAD)
     WatchDelayInfo() -> (struct {
         delay_info DelayInfo;
     });
 };
	// Copyright 2019 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;

	/// Delay information as returned by the driver.
	@available(added=HEAD)
	type DelayInfo = table {
	/// The driver's best estimate of the delay internal to the hardware it abstracts for
	/// the chosen format.
	///
	/// `internal_delay` must be taken into account by the client when determining either
	/// the minimum lead time requirement (for playback) or the minimum capture delay (for
	/// capture).
	///
	/// The data plane contents must be produced and consumed at the rate specified by the drivers
	/// configuration. However, some amount of buffering is required when moving data (for instance
	/// reading from or writing into the ring buffer for StreamConfig and Dai drivers), and this
	/// adds delay. In addition to this minimum buffering, more delay may be incurred by additional
	/// processing done in hardware or software.
	///
	/// In many cases the hardware abstracted by the driver mostly adds delay in the form of a
	/// FIFO buffer used to transfer data in and out of an audio interconnect.
	/// In these cases, when consuming playback data, the hardware reads ahead by enough samples
	/// to fill the FIFO buffer; when producing capture data, samples are first held in the FIFO
	/// buffer before they are committed it to main system memory.
	/// In these cases `internal_delay` can be calculated based on the rate, frame size and the size
	/// of a hardware FIFO block.
	///
	/// Required.
	1: internal_delay zx.duration;

	/// The driver's best estimate of the delay external to the hardware it abstracts for
	/// the chosen format. If not included `external_delay` is unknown. If unknown, the
	/// client may treat `external_delay` as it chooses, e.g. may autodetect it, consider
	/// it zero, consider it a large number, etc.
	///
	/// `external_delay` must be taken into account by the client when determining either
	/// the minimum lead time requirement (for playback) or the minimum capture delay (for
	/// capture).
	2: external_delay zx.duration;
	};

	/// Properties of the ring buffer. These values don't change once the ring buffer is created.
	type RingBufferProperties = table {
	/// The driver's best estimate of the external delay present in the presentation 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.
	//
	// # Deprecation
	//
	// Not needed anymore since the functionality is available via `WatchDelayInfo` below.
	// Should match `DelayInfo` `external_delay` until it's removed.
	@available(deprecated=9)
	1: external_delay zx.duration;

	/// Size (in bytes) representing a temporary buffer used by the driver in order to consume or
	/// generate the ring buffer contents. Required.
	/// The ring buffer contents must be produced and consumed at the rate specified with the
	/// `CreateRingBuffer` command, however some amount of buffering is required when the data is
	/// written into and read from the ring buffer. For playback the data is consumed by the driver
	/// by reading ahead up to `fifo_depth` bytes. For capture the data is produced by the driver
	/// holding up to `fifo_depth` bytes at the time before committing it to main system
	/// memory. Hence `fifo_depth` must be taken into account by the client when determining either
	/// the minimum lead time requirement (for playback) or the maximum capture delay (for capture).
	///
	/// To convert `fifo_depth` to the corresponding number of audio frames, use the frame size
	/// returned by `CreateRingBuffer` in the `StreamConfig` protocol, note that the `fifo_depth`
	/// is not necessarily a multiple size of an audio frame.
	///
	/// The ring buffer data may be directly consumed/generated by hardware, in this case
	/// `fifo_depth` maps directly to the size of a hardware FIFO block, since the hardware FIFO
	/// block determines the amount of data read ahead or held back.
	///
	/// The ring buffer data may instead be consumed/generated by audio driver software that is
	/// conceptually situated between the ring buffer and the audio hardware. In this case, for
	/// playback the `fifo_depth` read ahead amount is set large enough such that the driver
	/// guarantees no undetected underruns, this assuming the client is generating the data as
	/// determined by the `CreateRingBuffer` and `Start` commands. For capture, the
	/// `fifo_depth` held back amount is set large enough such that the driver guarantees no
	/// undetected underruns when generating the data as determined by the `CreateRingBuffer` and
	/// `Start` commands. The driver must set `fifo_depth` big enough such that the potential
	/// delays added by any software interfacing with the audio hardware do not occur under most
	/// scenarios, and must detect and report underruns. How an underrun is reported is not defined
	/// in this API.
	//
	// # Deprecation
	//
	// Not needed anymore since the functionality is available via `WatchDelayInfo` below.
	// Should match `DelayInfo` `internal_delay` equivalent until it's removed.
	@available(deprecated=9)
	2: fifo_depth uint32;

	/// When set to true, indicates that the ring buffer runs in a different cache coherency domain,
	/// hence clients need to make sure that their data has been flushed all the way to main memory
	/// (in the case of playback) or that their view of the ring buffer will need to be invalidated
	/// before read (in the case of capture).
	///
	/// When set to false, indicates that the ring buffer runs in the same cache coherency domain,
	/// hence the driver does not require flushing/invalidation, as in there is no hardware external
	/// to the CPUs reading/writing from/to main memory bypassing the CPUs.
	/// Note that in this case the driver and client still need to make sure they synchronize their
	/// access to the data, for instance inserting the appropriate acquire fences before reading
	/// and release fences after writing.
	///
	/// Required.
	3: needs_cache_flush_or_invalidate bool;

	/// The driver's best estimate of the amount of time it takes the hardware to actually start
	/// playback/capture, after a channel is activated by `SetActiveChannels`.
	/// Restated: the driver estimates that after `SetActiveChannels` enables a channel, its data
	/// will resume flowing at approximately `set_time` + `turn_on_delay`.
	/// It may take some time for the hardware to get into fully operational mode, for example due
	/// a power state change or communication delays within the driver's multiple hardware entities
	/// as in a Bluetooth driver. 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.
	4: turn_on_delay zx.duration;
	};

	type RingBufferPositionInfo = struct {
	/// The driver's best estimate of the time (in the CLOCK_MONOTONIC timeline) at which the
	/// playback/capture pointer reached the position indicated by `position`.
	/// `turn_on_delay` impact should not be incorporated into 'timestamp'.
	/// No delays indicated in `DelayInfo` should be incorporated.
	timestamp zx.time;

	/// The playback/capture pointer position (in bytes) in the ring buffer at time
	/// `timestamp` as estimated by the driver.
	position uint32;
	};

	type GetVmoError = strict enum {
	/// The ring buffer setup failed due to an invalid argument, e.g. min_frames is too big.
	INVALID_ARGS = 1;

	/// The ring buffer setup failed due to an internal error.
	INTERNAL_ERROR = 2;
	};

	/// For an overview see
	/// [Audio Driver Streaming Interface](https://fuchsia.dev/fuchsia-src/concepts/drivers/driver_architectures/audio_drivers/audio_streaming)
	protocol RingBuffer {
	/// Accessor for top level static properties.
	GetProperties() -> (struct {
	properties RingBufferProperties;
	});

	/// Gets the ring buffer current position via a hanging get. 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. 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.
	/// `WatchClockRecoveryPositionInfo` may only be called after `GetVmo` was called, hence a
	/// `clock_recovery_notifications_per_ring` was specified.
	/// Must be delivered with timestamps that are monotonically increasing.
	WatchClockRecoveryPositionInfo() -> (struct {
	position_info RingBufferPositionInfo;
	});

	/// Requests a shared buffer to be used for moving bulk audio data. Requests the buffer size to
	/// fit at least `min_frames`, and returns the actual `num_frames` allocated in
	/// `ring_buffer`.
	///
	/// 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.
	///
	// TODO(fxbug.dev/116353): Reconsider the `clock_recovery_notifications_per_ring` parameter,
	// once we must recover a clock from a device being actively rate-adjusted in hardware.
	// TODO(fxbug.dev/116355): Clarify that drivers must incorporate "device DMA chunk size" into
	// the final ring-buffer size, so that a client can safely operate within their `min_frames`.
	GetVmo(struct {
	min_frames uint32;
	clock_recovery_notifications_per_ring uint32;
	}) -> (resource struct {
	num_frames uint32;
	ring_buffer zx.handle:VMO;
	}) error GetVmoError;

	/// 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.
	/// external_delay impact should not be incorporated into 'start_time'.
	/// If `Start` is called before `SetActiveChannels`, then by default all channels are active.
	/// 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, the channel must be closed
	/// with an error `ZX_ERR_BAD_STATE` returned.
	Start() -> (struct {
	start_time zx.time;
	});

	/// 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`.
	// TODO(fxbug.dev/39494): Add timestamp parameter.
	Stop() -> ();

	/// Sets which channels are active via a bitmask.
	/// The least significant bit corresponds to channel index 0.
	/// Channels not set (bits are 0) in the bitmask are inactive.
	/// 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.
	/// 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).
	/// Deactivating one, several, or all channels does not `Stop` the ring buffer.
	/// `SetActiveChannels` does not change the ring buffer's behavior with regard to
	/// `Start`/`Stop`, specifically 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.
	/// By default all channels are active.
	/// 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 may 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.
	/// For input channels, it is not required that the driver zero-out inactive channels.
	SetActiveChannels(struct {
	active_channels_bitmask uint64;
	}) -> (struct {
	set_time zx.time;
	}) error zx.status;

	/// 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.
	@available(added=HEAD)
	WatchDelayInfo() -> (struct {
	delay_info DelayInfo;
	});
	};