/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.audio@4.0;
import android.hardware.audio.common@4.0;
import IStream;
import IStreamOutCallback;
interface IStreamOut extends IStream {
/**
* Return the audio hardware driver estimated latency in milliseconds.
*
* @return latencyMs latency in milliseconds.
*/
getLatency() generates (uint32_t latencyMs);
/**
* This method is used in situations where audio mixing is done in the
* hardware. This method serves as a direct interface with hardware,
* allowing to directly set the volume as apposed to via the framework.
* This method might produce multiple PCM outputs or hardware accelerated
* codecs, such as MP3 or AAC.
* Optional method
*
* @param left left channel attenuation, 1.0f is unity, 0.0f is zero.
* @param right right channel attenuation, 1.0f is unity, 0.0f is zero.
* @return retval operation completion status.
* If a volume is outside [0,1], return INVALID_ARGUMENTS
*/
setVolume(float left, float right) generates (Result retval);
/**
* Commands that can be executed on the driver writer thread.
*/
enum WriteCommand : int32_t {
WRITE,
GET_PRESENTATION_POSITION,
GET_LATENCY
};
/**
* Data structure passed back to the client via status message queue
* of 'write' operation.
*
* Possible values of 'retval' field:
* - OK, write operation was successful;
* - INVALID_ARGUMENTS, stream was not configured properly;
* - INVALID_STATE, stream is in a state that doesn't allow writes;
* - INVALID_OPERATION, retrieving presentation position isn't supported.
*/
struct WriteStatus {
Result retval;
WriteCommand replyTo; // discriminator
union Reply {
uint64_t written; // WRITE command, amount of bytes written, >= 0.
struct PresentationPosition { // same as generated by
uint64_t frames; // getPresentationPosition.
TimeSpec timeStamp;
} presentationPosition;
uint32_t latencyMs; // Same as generated by getLatency.
} reply;
};
/**
* Called when the metadata of the stream's source has been changed.
* @param sourceMetadata Description of the audio that is played by the clients.
*/
updateSourceMetadata(SourceMetadata sourceMetadata);
/**
* Set up required transports for passing audio buffers to the driver.
*
* The transport consists of three message queues:
* -- command queue is used to instruct the writer thread what operation
* to perform;
* -- data queue is used for passing audio data from the client
* to the driver;
* -- status queue is used for reporting operation status
* (e.g. amount of bytes actually written or error code).
*
* The driver operates on a dedicated thread. The client must ensure that
* the thread is given an appropriate priority and assigned to correct
* scheduler and cgroup. For this purpose, the method returns identifiers
* of the driver thread.
*
* @param frameSize the size of a single frame, in bytes.
* @param framesCount the number of frames in a buffer.
* @return retval OK if both message queues were created successfully.
* INVALID_STATE if the method was already called.
* INVALID_ARGUMENTS if there was a problem setting up
* the queues.
* @return commandMQ a message queue used for passing commands.
* @return dataMQ a message queue used for passing audio data in the format
* specified at the stream opening.
* @return statusMQ a message queue used for passing status from the driver
* using WriteStatus structures.
* @return threadInfo identifiers of the driver's dedicated thread.
*/
prepareForWriting(uint32_t frameSize, uint32_t framesCount)
generates (
Result retval,
fmq_sync<WriteCommand> commandMQ,
fmq_sync<uint8_t> dataMQ,
fmq_sync<WriteStatus> statusMQ,
ThreadInfo threadInfo);
/**
* Return the number of audio frames written by the audio DSP to DAC since
* the output has exited standby.
* Optional method
*
* @return retval operation completion status.
* @return dspFrames number of audio frames written.
*/
getRenderPosition() generates (Result retval, uint32_t dspFrames);
/**
* Get the local time at which the next write to the audio driver will be
* presented. The units are microseconds, where the epoch is decided by the
* local audio HAL.
* Optional method
*
* @return retval operation completion status.
* @return timestampUs time of the next write.
*/
getNextWriteTimestamp() generates (Result retval, int64_t timestampUs);
/**
* Set the callback interface for notifying completion of non-blocking
* write and drain.
*
* Calling this function implies that all future 'write' and 'drain'
* must be non-blocking and use the callback to signal completion.
*
* 'clearCallback' method needs to be called in order to release the local
* callback proxy on the server side and thus dereference the callback
* implementation on the client side.
*
* @return retval operation completion status.
*/
setCallback(IStreamOutCallback callback) generates (Result retval);
/**
* Clears the callback previously set via 'setCallback' method.
*
* Warning: failure to call this method results in callback implementation
* on the client side being held until the HAL server termination.
*
* If no callback was previously set, the method should be a no-op
* and return OK.
*
* @return retval operation completion status: OK or NOT_SUPPORTED.
*/
clearCallback() generates (Result retval);
/**
* Returns whether HAL supports pausing and resuming of streams.
*
* @return supportsPause true if pausing is supported.
* @return supportsResume true if resume is supported.
*/
supportsPauseAndResume()
generates (bool supportsPause, bool supportsResume);
/**
* Notifies to the audio driver to stop playback however the queued buffers
* are retained by the hardware. Useful for implementing pause/resume. Empty
* implementation if not supported however must be implemented for hardware
* with non-trivial latency. In the pause state, some audio hardware may
* still be using power. Client code may consider calling 'suspend' after a
* timeout to prevent that excess power usage.
*
* Implementation of this function is mandatory for offloaded playback.
*
* @return retval operation completion status.
*/
pause() generates (Result retval);
/**
* Notifies to the audio driver to resume playback following a pause.
* Returns error INVALID_STATE if called without matching pause.
*
* Implementation of this function is mandatory for offloaded playback.
*
* @return retval operation completion status.
*/
resume() generates (Result retval);
/**
* Returns whether HAL supports draining of streams.
*
* @return supports true if draining is supported.
*/
supportsDrain() generates (bool supports);
/**
* Requests notification when data buffered by the driver/hardware has been
* played. If 'setCallback' has previously been called to enable
* non-blocking mode, then 'drain' must not block, instead it must return
* quickly and completion of the drain is notified through the callback. If
* 'setCallback' has not been called, then 'drain' must block until
* completion.
*
* If 'type' is 'ALL', the drain completes when all previously written data
* has been played.
*
* If 'type' is 'EARLY_NOTIFY', the drain completes shortly before all data
* for the current track has played to allow time for the framework to
* perform a gapless track switch.
*
* Drain must return immediately on 'stop' and 'flush' calls.
*
* Implementation of this function is mandatory for offloaded playback.
*
* @param type type of drain.
* @return retval operation completion status.
*/
drain(AudioDrain type) generates (Result retval);
/**
* Notifies to the audio driver to flush the queued data. Stream must
* already be paused before calling 'flush'.
* Optional method
*
* Implementation of this function is mandatory for offloaded playback.
*
* @return retval operation completion status.
*/
flush() generates (Result retval);
/**
* Return a recent count of the number of audio frames presented to an
* external observer. This excludes frames which have been written but are
* still in the pipeline. The count is not reset to zero when output enters
* standby. Also returns the value of CLOCK_MONOTONIC as of this
* presentation count. The returned count is expected to be 'recent', but
* does not need to be the most recent possible value. However, the
* associated time must correspond to whatever count is returned.
*
* Example: assume that N+M frames have been presented, where M is a 'small'
* number. Then it is permissible to return N instead of N+M, and the
* timestamp must correspond to N rather than N+M. The terms 'recent' and
* 'small' are not defined. They reflect the quality of the implementation.
*
* Optional method
*
* @return retval operation completion status.
* @return frames count of presented audio frames.
* @return timeStamp associated clock time.
*/
getPresentationPosition()
generates (Result retval, uint64_t frames, TimeSpec timeStamp);
/**
* Selects a presentation for decoding from a next generation media stream
* (as defined per ETSI TS 103 190-2) and a program within the presentation.
* Optional method
*
* @param presentationId selected audio presentation.
* @param programId refinement for the presentation.
* @return retval operation completion status.
*/
selectPresentation(int32_t presentationId, int32_t programId)
generates (Result retval);
};