audio/5.0/IStreamOut.hal - LeafOS-Project/android_hardware_interfaces - Gitiles

 /*
  * 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@5.0;

 import android.hardware.audio.common@5.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);
 };
	/*
	* 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@5.0;

	import android.hardware.audio.common@5.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);
	};