blob: 37b0f2d26a4e232b8868f51a6e160d72794ccda9 [file] [log] [blame]
// 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 (for the chosen format) of the delay internal to the hardware it
/// abstracts.
///
/// "Internal" refers to the hardware between the hardware interconnect (DAI) and the ring
/// buffer (e.g. an SoC audio subsystem), whereas "external" refers to hardware on the far side
/// of any hardware interconnect (DAI) (e.g. hardware codecs).
///
/// For a given frame during playback, this is any delay after the driver/HW copies it
/// out of the ring-buffer, before it exits any hardware interconnect.
/// For a given frame during recording, this is any delay after it enters the hardware
/// interconnect, before the driver/HW copies it into the ring-buffer.
///
/// `internal_delay` must be taken into account by the client when determining the requirements
/// for minimum lead time (during playback) and minimum capture delay (during capture).
///
/// This delay must not include the inherent delay added by the temporary buffering needed
/// to copy data in and out of the ring buffer, which is contained in `RingBufferProperties`
/// field `driver_transfer_bytes`.
///
/// Required.
1: internal_delay zx.Duration;
/// The driver's best estimate (for the chosen format) of the delay external to the hardware it
/// abstracts.
///
/// "External" refers to hardware on the far side of any hardware interconnect (DAI) (e.g.
/// hardware codecs), whereas "internal" refers to hardware between the hardware interconnect
/// (DAI) and the ring buffer (e.g. an SoC audio subsystem).
///
/// `external_delay` must be taken into account by the client when determining the requirements
/// for minimum lead time (during playback) and minimum capture delay (during capture).
///
/// If not included, `external_delay` is unknown. If unknown, a client may treat it however it
/// chooses (consider it zero or some large number, autodetect it, etc).
///
/// Like `internal_delay`, this delay must not include the inherent delay added by the temporary
/// buffering needed to copy data in and out of the ring buffer, which is contained in
/// `RingBufferProperties` field `driver_transfer_bytes`.
///
/// Optional.
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 (for the chosen format) of the delay external to the hardware it
/// abstracts. External delay must be taken into account when precisely synchronizing
/// presentation across multiple entities (e.g. devices).
/// If not included `external_delay` is unknown.
///
/// # Deprecation
///
/// Not needed anymore since the functionality is available via `WatchDelayInfo` below.
@available(deprecated=9, removed=HEAD)
1: external_delay zx.Duration;
/// Size (in bytes) of the temporary buffer used by the driver when consuming or generating 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 `driver_transfer_bytes` below.
@available(deprecated=9, removed=HEAD)
2: fifo_depth uint32;
/// When set to true, indicates that the ring buffer runs in a different cache coherency domain,
/// and thus clients must ensure that their data writes are flushed all the way to main memory
/// (during playback), or that their view of the ring buffer must be invalidated before any
/// reads (during capture). This is because there may be hardware external to the CPUs that
/// reads/writes main memory, bypassing the CPUs.
///
/// When set to false, indicates that the ring buffer runs in the same cache coherency domain as
/// the CPUs, hence the driver is not required to flush/invalidate the ring buffer.
/// Note that in this case, the driver and client still must synchronize their data access, for
/// instance by inserting the appropriate acquire fences before reading and releasing fences
/// after writing.
///
/// Required.
3: needs_cache_flush_or_invalidate bool;
/// The driver's best estimate of the time needed for the hardware to emit (during playback) or
/// accept (during capture) frames, after a channel is activated by `SetActiveChannels`.
/// The driver estimates that after `SetActiveChannels(channel)->(set_time)` enables a channel,
/// its data will resume flowing at approximately `set_time` + `turn_on_delay`.
/// Hardware can take time to become fully operational (e.g. due to a power state change, or
/// communication delays between a Bluetooth driver's multiple hardware entities). The client
/// must take this delay into account, if it is unacceptable to drop the actual audio frames
/// and instead play/capture silence during this interval.
/// If not included, `turn_on_delay` is unknown.
///
/// Optional.
4: turn_on_delay zx.Duration;
/// Size (in bytes) of the temporary buffer used by the driver/HW when consuming or generating
/// the ring buffer contents.
///
/// The ring buffer contents must be produced and consumed at the rate specified with the
/// `CreateRingBuffer` command, using data transfers between a temporary buffer and the ring
/// buffer. For playback, audio frames are consumed by the driver in transfers as large as
/// `driver_transfer_bytes`. For capture, audio frames are produced by the driver in transfers
/// as large as `driver_transfer_bytes`. In both cases, this many frames must accumulate before
/// they are read from or committed to the ring buffer.
///
/// These data transfers mean that there is always a section of the ring buffer that is unsafe
/// for the client to be writing/reading. This unsafe buffer region is defined on one side by
/// the current position 'P', and on the other side by the 'safe pointer' location 'S'. Once the
/// ring buffer starts, these two pointers begin moving. 'P' begins moving from position 0 at
/// the `start_time` from `Start`. The region between these pointers must not be read or
/// written by the client at that time. The diagrams below note these pointers as 'P' and 'S'.
///
/// During playback, client must write data BEFORE hardware transfers occur. During capture,
/// client can read captured data only AFTER hardware transfers occur. For this reason, during
/// playback 'S' is always ahead of 'P', whereas during capture 'S' is always behind 'P'.
///
///
/// ## Playback
///
/// Before they start the ring buffer, clients may safely write any ring buffer location. It is
/// recommended that they write at least `driver_transfer_bytes` of initial audio, since they
/// must always stay at least that far ahead of where the driver/HW is reading, and upon `Start`
/// the hardware might immediately consume that much data from the ring buffer. Otherwise, the
/// client relies on the zeroed-out contents of the VMO to be the initial audio read by the
/// driver/HW.
///
/// ```
/// Ring Buffer
/// +-------------------------+-------------------------------------------------------------+
/// |<--- safe to write --->|
/// | (to pre-populate the ring buffer before starting the hardware) |
/// +-------------------------+-------------------------------------------------------------+
/// 0=P S 0
/// ```
///
/// Once the ring buffer is started, it is not safe for the client to write data to the ring
/// buffer between 'P' and 'S', because this represents data already in use (potentially already
/// consumed). The client may safely write the rest of the ring buffer (between 'S' and '0/P').
///
/// ```
/// Ring Buffer
/// +-------------------------+-------------------------------------------------------------+
/// |<--- unsafe to write --->|<--- safe to write --->|
/// |< driver_transfer_bytes >| (empty unless prewritten by the client) |
/// +-------------------------+-------------------------------------------------------------+
/// 0=P S 0
/// ```
///
/// As time passes, the driver/HW reads the data in chunks of `driver_transfer_bytes` or less,
/// at the rate specified in `CreateRingBuffer`. The Position/Safe pointers move to the right at
/// the same rate, but do so smoothly. As a result, the "unsafe for client writes" area moves
/// gradually through the ring buffer, while maintaining a constant size equal to
/// `driver_transfer_bytes`. Thus, after some period we now have:
///
/// ```
/// Ring Buffer
/// +------------+-------------------------+------------------------------------------------+
/// |<-- safe -->|<--- unsafe to write --->|<-- safe to write -->|
/// | to write |< driver_transfer_bytes >| (not yet consumed by the hardware) |
/// +------------+-------------------------+------------------------------------------------+
/// 0 P S 0
/// ```
///
/// Later, 'S' wraps around the ring buffer before 'P' does. Note that the region from 0 to 'S',
/// plus the region from 'P' to the end of the ring buffer, adds up to `driver_transfer_bytes`:
///
/// ```
/// Ring Buffer
/// +---------------+------------------------------------------------------------+----------+
/// |<--- unsafe -->|<--- safe to write --->|<-unsafe->|
/// |< driver_transf| |er_bytes >|
/// +---------------+------------------------------------------------------------+----------+
/// 0 S P 0
/// ```
///
/// In steady state, any area outside of the pointers 'P' and 'S' is safe to write:
///
/// ```
/// Ring Buffer
/// +--------------------------------+-------------------------+----------------------------+
/// [<-- safe to write -->|<--- unsafe to write --->|<-- safe to write -->|
/// | (prior data already consumed) |< driver_transfer_bytes >| |
/// +--------------------------------+-------------------------+----------------------------+
/// 0 P S 0
/// ```
///
///
/// ## Recording
///
/// While recording, it is only safe for the client to read that part of the ring buffer that is
/// not simultaneously being written by the driver/HW. Before capture begins, it may read the
/// entire ring buffer, but the driver has not yet written anything for the client to read. This
/// is the ring buffer at the moment that the client starts the ring buffer:
///
/// ```
/// Ring Buffer
/// +---------------------------------------------------------------------------------------+
/// [<--- empty (not yet written by the hardware) -->|
/// +---------------------------------------------------------------------------------------+
/// 0=S=P 0
/// ```
///
/// Once capture begins, the driver/HW acquires frames, eventually making its first data
/// transfer to the ring buffer starting at '0'. These transfers are of unknown size but may be
/// as large as `driver_transfer_bytes`; they occur at the rate specified in `CreateRingBuffer`.
/// Before the driver/HW has written at least `driver_transfer_bytes` into the ring buffer, the
/// client cannot yet safely read any of the newly captured frames:
///
/// ```
/// Ring Buffer
/// +--------------+------------------------------------------------------------------------+
/// [<-- unsafe -->|<-- safe to read -->|
/// |< driver_transfer_bytes >| (but empty, not yet written by the hardware) |
/// +--------------+------------------------------------------------------------------------+
/// 0=S P 0
/// ```
///
/// Once the driver/HW has written at least `driver_transfer_bytes` of data into the ring
/// buffer, 'S' begins to smoothly move forward at the same rate as 'P' (as determined by the
/// ring buffer's rate and sample format). The client can safely read frames in the region
/// between '0' and 'S'. It is unsafe for the client to read data between 'S' and 'P', because
/// this is where the driver/HW is simultaneously writing. This region gradually progresses
/// across the ring buffer, maintaining a constant size of `driver_transfer_bytes`.
/// After some time we have:
///
/// ```
/// Ring Buffer
/// +----------------+-------------------------+--------------------------------------------+
/// [< safe to read >|<--- unsafe to read --->|<-- safe to read -->|
/// | captured audio |< driver_transfer_bytes >| (not yet written by the hardware) |
/// +----------------+-------------------------+--------------------------------------------+
/// 0 S P 0
/// ```
///
/// Later, 'P' wraps around the ring buffer before 'S' does. Note that the region from 0 to 'P',
/// plus the region from 'S' to the end of the ring buffer, adds up to `driver_transfer_bytes`:
///
/// ```
/// Ring Buffer
/// +-----------+------------------------------------------------------------+--------------+
/// |<--unsafe->|<--- safe to read --->|<---unsafe--->|
/// |< driver_tr| (captured audio) |ansfer_bytes >|
/// +-----------+------------------------------------------------------------+--------------+
/// 0 P S 0
/// ```
///
/// In steady state, i.e. once the process has wrapped around the ring buffer, any area outside
/// of pointers 'S' and 'P' is safe to read:
///
/// ```
/// Ring Buffer
/// +--------------------------------+-------------------------+----------------------------+
/// [<-- safe to read -->|<--- unsafe --->|<-- safe to read -->|
/// | |< driver_transfer_bytes >| |
/// +--------------------------------+-------------------------+----------------------------+
/// 0 S P 0
/// ```
///
///
/// ## Hardware versus software
///
/// The ring buffer data may be directly consumed/generated by hardware, i.e.
/// `driver_transfer_bytes` can be mapped directly to the size of a hardware FIFO block, since a
/// hardware FIFO block determines the upper limit amount of data read ahead or held back.
/// Note that if the FIFO buffer is not used in the traditional "high water" way (such as a
/// "ping pong" design where only half the FIFO size is used at any time -- even during the very
/// first transfers at `Start` time), then `driver_transfer_bytes` may be set to a smaller value
/// but must be at least equal to the largest amount of data ever stored in the FIFO buffer.
/// Even if the transfer size never exceeds half the size of the FIFO, if the full size of the
/// FIFO is used (for instance, upon `Start` when filling an initially empty hardware FIFO),
/// then `driver_transfer_bytes` must be set to the entire size of the FIFO buffer.
///
/// 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 `driver_transfer_bytes` read ahead amount must be large enough such that the
/// driver guarantees no undetected underruns, based on the client requirement to generate data
/// based on the `CreateRingBuffer` rate and the `start_time` from `Start`. For capture,
/// `driver_transfer_bytes` must be large enough for the driver to guarantee no underruns when
/// generating the data as determined by the `CreateRingBuffer` and `Start` commands.
///
///
/// `driver_transfer_bytes` must not include the impact of delays caused by hardware or software
/// processing abstracted by the driver. Those delays are communicated by `internal_delay` and
/// `external_delay` fields in `DelayInfo`; they are orthogonal to this value.
///
/// Required.
@available(added=HEAD)
5: driver_transfer_bytes uint32;
};
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;
};
closed protocol RingBuffer {
/// Accessor for top level static properties.
strict 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.
/// 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 as`CLOCK_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.
/// `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.
/// 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.
strict WatchClockRecoveryPositionInfo() -> (struct {
position_info RingBufferPositionInfo;
});
/// 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.
///
/// 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(https://fxbug.dev/42067582): Reconsider the `clock_recovery_notifications_per_ring` parameter,
// once we must recover a clock from a device being actively rate-adjusted in hardware.
strict 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,
/// i.e. the driver/HW has started to read or write from or to the ring buffer position 0,
/// subject to the buffering described in `driver_transfer_bytes`.
///
/// 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, 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.
strict 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`, or if `Stop` is called for a second time before the
/// first call has completed, then the channel must be closed with `ZX_ERR_BAD_STATE`.
// TODO(https://fxbug.dev/42115360): Add timestamp parameter.
strict 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 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.
strict 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.
/// 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.
@available(added=HEAD)
strict WatchDelayInfo() -> (struct {
delay_info DelayInfo;
});
};