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 android.hardware.audio.effect@2.0::IEffect; 21 22 interface IStream { 23 typedef android.hardware.audio@2.0::Result Result; 24 25 /** 26 * Return the frame size (number of bytes per sample). 27 * 28 * @return frameSize frame size in bytes. 29 */ 30 getFrameSize() generates (uint64_t frameSize); 31 32 /** 33 * Return the frame count of the buffer. Calling this method is equivalent 34 * to getting AUDIO_PARAMETER_STREAM_FRAME_COUNT on the legacy HAL. 35 * 36 * @return count frame count. 37 */ 38 getFrameCount() generates (uint64_t count); 39 40 /** 41 * Return the size of input/output buffer in bytes for this stream. 42 * It must be a multiple of the frame size. 43 * 44 * @return buffer buffer size in bytes. 45 */ 46 getBufferSize() generates (uint64_t bufferSize); 47 48 /** 49 * Return the sampling rate in Hz. 50 * 51 * @return sampleRateHz sample rate in Hz. 52 */ 53 getSampleRate() generates (uint32_t sampleRateHz); 54 55 /** 56 * Return supported sampling rates of the stream. Calling this method is 57 * equivalent to getting AUDIO_PARAMETER_STREAM_SUP_SAMPLING_RATES on the 58 * legacy HAL. 59 * 60 * @return sampleRateHz supported sample rates. 61 */ 62 getSupportedSampleRates() generates (vec<uint32_t> sampleRates); 63 64 /** 65 * Sets the sampling rate of the stream. Calling this method is equivalent 66 * to setting AUDIO_PARAMETER_STREAM_SAMPLING_RATE on the legacy HAL. 67 * 68 * @param sampleRateHz sample rate in Hz. 69 * @return retval operation completion status. 70 */ 71 setSampleRate(uint32_t sampleRateHz) generates (Result retval); 72 73 /** 74 * Return the channel mask of the stream. 75 * 76 * @return mask channel mask. 77 */ 78 getChannelMask() generates (AudioChannelMask mask); 79 80 /** 81 * Return supported channel masks of the stream. Calling this method is 82 * equivalent to getting AUDIO_PARAMETER_STREAM_SUP_CHANNELS on the legacy 83 * HAL. 84 * 85 * @return masks supported audio masks. 86 */ 87 getSupportedChannelMasks() generates (vec<AudioChannelMask> masks); 88 89 /** 90 * Sets the channel mask of the stream. Calling this method is equivalent to 91 * setting AUDIO_PARAMETER_STREAM_CHANNELS on the legacy HAL. 92 * 93 * @param format audio format. 94 * @return retval operation completion status. 95 */ 96 setChannelMask(AudioChannelMask mask) generates (Result retval); 97 98 /** 99 * Return the audio format of the stream. 100 * 101 * @return format audio format. 102 */ 103 getFormat() generates (AudioFormat format); 104 105 /** 106 * Return supported audio formats of the stream. Calling this method is 107 * equivalent to getting AUDIO_PARAMETER_STREAM_SUP_FORMATS on the legacy 108 * HAL. 109 * 110 * @return formats supported audio formats. 111 */ 112 getSupportedFormats() generates (vec<AudioFormat> formats); 113 114 /** 115 * Sets the audio format of the stream. Calling this method is equivalent to 116 * setting AUDIO_PARAMETER_STREAM_FORMAT on the legacy HAL. 117 * 118 * @param format audio format. 119 * @return retval operation completion status. 120 */ 121 setFormat(AudioFormat format) generates (Result retval); 122 123 /** 124 * Convenience method for retrieving several stream parameters in 125 * one transaction. 126 * 127 * @return sampleRateHz sample rate in Hz. 128 * @return mask channel mask. 129 * @return format audio format. 130 */ 131 getAudioProperties() generates ( 132 uint32_t sampleRateHz, AudioChannelMask mask, AudioFormat format); 133 134 /** 135 * Applies audio effect to the stream. 136 * 137 * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of 138 * the effect to apply. 139 * @return retval operation completion status. 140 */ 141 addEffect(uint64_t effectId) generates (Result retval); 142 143 /** 144 * Stops application of the effect to the stream. 145 * 146 * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of 147 * the effect to remove. 148 * @return retval operation completion status. 149 */ 150 removeEffect(uint64_t effectId) generates (Result retval); 151 152 /** 153 * Put the audio hardware input/output into standby mode. 154 * Driver must exit from standby mode at the next I/O operation. 155 * 156 * @return retval operation completion status. 157 */ 158 standby() generates (Result retval); 159 160 /** 161 * Return the set of device(s) which this stream is connected to. 162 * 163 * @return device set of device(s) which this stream is connected to. 164 */ 165 getDevice() generates (AudioDevice device); 166 167 /** 168 * Connects the stream to the device. 169 * 170 * This method must only be used for HALs that do not support 171 * 'IDevice.createAudioPatch' method. Calling this method is 172 * equivalent to setting AUDIO_PARAMETER_STREAM_ROUTING in the legacy HAL 173 * interface. 174 * 175 * @param address device to connect the stream to. 176 * @return retval operation completion status. 177 */ 178 setDevice(DeviceAddress address) generates (Result retval); 179 180 /** 181 * Notifies the stream about device connection state. Calling this method is 182 * equivalent to setting AUDIO_PARAMETER_DEVICE_[DIS]CONNECT on the legacy 183 * HAL. 184 * 185 * @param address audio device specification. 186 * @param connected whether the device is connected. 187 * @return retval operation completion status. 188 */ 189 setConnectedState(DeviceAddress address, bool connected) 190 generates (Result retval); 191 192 /** 193 * Sets the HW synchronization source. Calling this method is equivalent to 194 * setting AUDIO_PARAMETER_STREAM_HW_AV_SYNC on the legacy HAL. 195 * 196 * @param hwAvSync HW synchronization source 197 * @return retval operation completion status. 198 */ 199 setHwAvSync(AudioHwSync hwAvSync) generates (Result retval); 200 201 /** 202 * Generic method for retrieving vendor-specific parameter values. 203 * The framework does not interpret the parameters, they are passed 204 * in an opaque manner between a vendor application and HAL. 205 * 206 * @param keys parameter keys. 207 * @return retval operation completion status. 208 * @return parameters parameter key value pairs. 209 */ 210 getParameters(vec<string> keys) 211 generates (Result retval, vec<ParameterValue> parameters); 212 213 /** 214 * Generic method for setting vendor-specific parameter values. 215 * The framework does not interpret the parameters, they are passed 216 * in an opaque manner between a vendor application and HAL. 217 * 218 * @param parameters parameter key value pairs. 219 * @return retval operation completion status. 220 */ 221 setParameters(vec<ParameterValue> parameters) generates (Result retval); 222 223 /** 224 * Dumps information about the stream into the provided file descriptor. 225 * This is used for the dumpsys facility. 226 * 227 * @param fd dump file descriptor. 228 */ 229 debugDump(handle fd); 230 231 /** 232 * Called by the framework to start a stream operating in mmap mode. 233 * createMmapBuffer() must be called before calling start(). 234 * Function only implemented by streams operating in mmap mode. 235 * 236 * @return retval OK in case the success. 237 * NOT_SUPPORTED on non mmap mode streams 238 * INVALID_STATE if called out of sequence 239 */ 240 start() generates (Result retval); 241 242 /** 243 * Called by the framework to stop a stream operating in mmap mode. 244 * Function only implemented by streams operating in mmap mode. 245 * 246 * @return retval OK in case the succes. 247 * NOT_SUPPORTED on non mmap mode streams 248 * INVALID_STATE if called out of sequence 249 */ 250 stop() generates (Result retval) ; 251 252 /** 253 * Called by the framework to retrieve information on the mmap buffer used for audio 254 * samples transfer. 255 * Function only implemented by streams operating in mmap mode. 256 * 257 * @param minSizeFrames minimum buffer size requested. The actual buffer 258 * size returned in struct MmapBufferInfo can be larger. 259 * @return retval OK in case the success. 260 * NOT_SUPPORTED on non mmap mode streams 261 * NOT_INITIALIZED in case of memory allocation error 262 * INVALID_ARGUMENTS if the requested buffer size is too large 263 * INVALID_STATE if called out of sequence 264 * @return info a MmapBufferInfo struct containing information on the MMMAP buffer created. 265 */ 266 createMmapBuffer(int32_t minSizeFrames) 267 generates (Result retval, MmapBufferInfo info); 268 269 /** 270 * Called by the framework to read current read/write position in the mmap buffer 271 * with associated time stamp. 272 * Function only implemented by streams operating in mmap mode. 273 * 274 * @return retval OK in case the success. 275 * NOT_SUPPORTED on non mmap mode streams 276 * INVALID_STATE if called out of sequence 277 * @return position a MmapPosition struct containing current HW read/write position in frames 278 * with associated time stamp. 279 */ 280 getMmapPosition() 281 generates (Result retval, MmapPosition position); 282 283 /** 284 * Called by the framework to deinitialize the stream and free up 285 * all the currently allocated resources. It is recommended to close 286 * the stream on the client side as soon as it is becomes unused. 287 * 288 * @return retval OK in case the success. 289 * NOT_SUPPORTED if called on IStream instead of input or 290 * output stream interface. 291 * INVALID_STATE if the stream was already closed. 292 */ 293 close() generates (Result retval); 294 }; 295
