1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware.audio@2.0; 18 19 import android.hardware.audio.common@2.0; 20 import IStream; 21 import IStreamOutCallback; 22 23 interface IStreamOut extends IStream { 24 typedef android.hardware.audio@2.0::Result Result; 25 26 /** 27 * Return the audio hardware driver estimated latency in milliseconds. 28 * 29 * @return latencyMs latency in milliseconds. 30 */ 31 getLatency() generates (uint32_t latencyMs); 32 33 /** 34 * This method is used in situations where audio mixing is done in the 35 * hardware. This method serves as a direct interface with hardware, 36 * allowing to directly set the volume as apposed to via the framework. 37 * This method might produce multiple PCM outputs or hardware accelerated 38 * codecs, such as MP3 or AAC. 39 * 40 * @param left left channel attenuation, 1.0f is unity, 0.0f is zero. 41 * @param right right channel attenuation, 1.0f is unity, 0.0f is zero. 42 * @return retval operation completion status. 43 */ 44 setVolume(float left, float right) generates (Result retval); 45 46 /** 47 * Commands that can be executed on the driver writer thread. 48 */ 49 enum WriteCommand : int32_t { 50 WRITE, 51 GET_PRESENTATION_POSITION, 52 GET_LATENCY 53 }; 54 55 /** 56 * Data structure passed back to the client via status message queue 57 * of 'write' operation. 58 * 59 * Possible values of 'retval' field: 60 * - OK, write operation was successful; 61 * - INVALID_ARGUMENTS, stream was not configured properly; 62 * - INVALID_STATE, stream is in a state that doesn't allow writes; 63 * - INVALID_OPERATION, retrieving presentation position isn't supported. 64 */ 65 struct WriteStatus { 66 Result retval; 67 WriteCommand replyTo; // discriminator 68 union Reply { 69 uint64_t written; // WRITE command, amount of bytes written, >= 0. 70 struct PresentationPosition { // same as generated by 71 uint64_t frames; // getPresentationPosition. 72 TimeSpec timeStamp; 73 } presentationPosition; 74 uint32_t latencyMs; // Same as generated by getLatency. 75 } reply; 76 }; 77 78 /** 79 * Set up required transports for passing audio buffers to the driver. 80 * 81 * The transport consists of three message queues: 82 * -- command queue is used to instruct the writer thread what operation 83 * to perform; 84 * -- data queue is used for passing audio data from the client 85 * to the driver; 86 * -- status queue is used for reporting operation status 87 * (e.g. amount of bytes actually written or error code). 88 * 89 * The driver operates on a dedicated thread. The client must ensure that 90 * the thread is given an appropriate priority and assigned to correct 91 * scheduler and cgroup. For this purpose, the method returns identifiers 92 * of the driver thread. 93 * 94 * @param frameSize the size of a single frame, in bytes. 95 * @param framesCount the number of frames in a buffer. 96 * @return retval OK if both message queues were created successfully. 97 * INVALID_STATE if the method was already called. 98 * INVALID_ARGUMENTS if there was a problem setting up 99 * the queues. 100 * @return commandMQ a message queue used for passing commands. 101 * @return dataMQ a message queue used for passing audio data in the format 102 * specified at the stream opening. 103 * @return statusMQ a message queue used for passing status from the driver 104 * using WriteStatus structures. 105 * @return threadInfo identifiers of the driver's dedicated thread. 106 */ 107 prepareForWriting(uint32_t frameSize, uint32_t framesCount) 108 generates ( 109 Result retval, 110 fmq_sync<WriteCommand> commandMQ, 111 fmq_sync<uint8_t> dataMQ, 112 fmq_sync<WriteStatus> statusMQ, 113 ThreadInfo threadInfo); 114 115 /** 116 * Return the number of audio frames written by the audio DSP to DAC since 117 * the output has exited standby. 118 * 119 * @return retval operation completion status. 120 * @return dspFrames number of audio frames written. 121 */ 122 getRenderPosition() generates (Result retval, uint32_t dspFrames); 123 124 /** 125 * Get the local time at which the next write to the audio driver will be 126 * presented. The units are microseconds, where the epoch is decided by the 127 * local audio HAL. 128 * 129 * @return retval operation completion status. 130 * @return timestampUs time of the next write. 131 */ 132 getNextWriteTimestamp() generates (Result retval, int64_t timestampUs); 133 134 /** 135 * Set the callback interface for notifying completion of non-blocking 136 * write and drain. 137 * 138 * Calling this function implies that all future 'write' and 'drain' 139 * must be non-blocking and use the callback to signal completion. 140 * 141 * 'clearCallback' method needs to be called in order to release the local 142 * callback proxy on the server side and thus dereference the callback 143 * implementation on the client side. 144 * 145 * @return retval operation completion status. 146 */ 147 setCallback(IStreamOutCallback callback) generates (Result retval); 148 149 /** 150 * Clears the callback previously set via 'setCallback' method. 151 * 152 * Warning: failure to call this method results in callback implementation 153 * on the client side being held until the HAL server termination. 154 * 155 * @return retval operation completion status: OK or NOT_SUPPORTED. 156 */ 157 clearCallback() generates (Result retval); 158 159 /** 160 * Returns whether HAL supports pausing and resuming of streams. 161 * 162 * @return supportsPause true if pausing is supported. 163 * @return supportsResume true if resume is supported. 164 */ 165 supportsPauseAndResume() 166 generates (bool supportsPause, bool supportsResume); 167 168 /** 169 * Notifies to the audio driver to stop playback however the queued buffers 170 * are retained by the hardware. Useful for implementing pause/resume. Empty 171 * implementation if not supported however must be implemented for hardware 172 * with non-trivial latency. In the pause state, some audio hardware may 173 * still be using power. Client code may consider calling 'suspend' after a 174 * timeout to prevent that excess power usage. 175 * 176 * Implementation of this function is mandatory for offloaded playback. 177 * 178 * @return retval operation completion status. 179 */ 180 pause() generates (Result retval); 181 182 /** 183 * Notifies to the audio driver to resume playback following a pause. 184 * Returns error INVALID_STATE if called without matching pause. 185 * 186 * Implementation of this function is mandatory for offloaded playback. 187 * 188 * @return retval operation completion status. 189 */ 190 resume() generates (Result retval); 191 192 /** 193 * Returns whether HAL supports draining of streams. 194 * 195 * @return supports true if draining is supported. 196 */ 197 supportsDrain() generates (bool supports); 198 199 /** 200 * Requests notification when data buffered by the driver/hardware has been 201 * played. If 'setCallback' has previously been called to enable 202 * non-blocking mode, then 'drain' must not block, instead it must return 203 * quickly and completion of the drain is notified through the callback. If 204 * 'setCallback' has not been called, then 'drain' must block until 205 * completion. 206 * 207 * If 'type' is 'ALL', the drain completes when all previously written data 208 * has been played. 209 * 210 * If 'type' is 'EARLY_NOTIFY', the drain completes shortly before all data 211 * for the current track has played to allow time for the framework to 212 * perform a gapless track switch. 213 * 214 * Drain must return immediately on 'stop' and 'flush' calls. 215 * 216 * Implementation of this function is mandatory for offloaded playback. 217 * 218 * @param type type of drain. 219 * @return retval operation completion status. 220 */ 221 drain(AudioDrain type) generates (Result retval); 222 223 /** 224 * Notifies to the audio driver to flush the queued data. Stream must 225 * already be paused before calling 'flush'. 226 * 227 * Implementation of this function is mandatory for offloaded playback. 228 * 229 * @return retval operation completion status. 230 */ 231 flush() generates (Result retval); 232 233 /** 234 * Return a recent count of the number of audio frames presented to an 235 * external observer. This excludes frames which have been written but are 236 * still in the pipeline. The count is not reset to zero when output enters 237 * standby. Also returns the value of CLOCK_MONOTONIC as of this 238 * presentation count. The returned count is expected to be 'recent', but 239 * does not need to be the most recent possible value. However, the 240 * associated time must correspond to whatever count is returned. 241 * 242 * Example: assume that N+M frames have been presented, where M is a 'small' 243 * number. Then it is permissible to return N instead of N+M, and the 244 * timestamp must correspond to N rather than N+M. The terms 'recent' and 245 * 'small' are not defined. They reflect the quality of the implementation. 246 * 247 * @return retval operation completion status. 248 * @return frames count of presented audio frames. 249 * @return timeStamp associated clock time. 250 */ 251 getPresentationPosition() 252 generates (Result retval, uint64_t frames, TimeSpec timeStamp); 253 }; 254
