1/* 2 * Copyright (C) 2020 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 17package android.hardware.audio@7.0; 18 19import android.hardware.audio.common@7.0; 20import IStream; 21 22interface IStreamIn extends IStream { 23 /** 24 * Returns the source descriptor of the input stream. Calling this method is 25 * equivalent to getting AUDIO_PARAMETER_STREAM_INPUT_SOURCE on the legacy 26 * HAL. 27 * 28 * Optional method 29 * 30 * @return retval operation completion status. 31 * @return source audio source. 32 */ 33 getAudioSource() generates (Result retval, AudioSource source); 34 35 /** 36 * Set the input gain for the audio driver. 37 * 38 * Optional method 39 * 40 * @param gain 1.0f is unity, 0.0f is zero. 41 * @result retval operation completion status. 42 */ 43 setGain(float gain) generates (Result retval); 44 45 /** 46 * Called when the metadata of the stream's sink has been changed. 47 * 48 * Optional method 49 * 50 * @param sinkMetadata Description of the audio that is suggested by the clients. 51 * @return retval operation completion status. 52 * If any of the metadata fields contains an invalid value, 53 * returns INVALID_ARGUMENTS. 54 * If method isn't supported by the HAL returns NOT_SUPPORTED. 55 */ 56 updateSinkMetadata(SinkMetadata sinkMetadata) generates (Result retval); 57 58 /** 59 * Commands that can be executed on the driver reader thread. 60 */ 61 enum ReadCommand : int32_t { 62 READ, 63 GET_CAPTURE_POSITION 64 }; 65 66 /** 67 * Data structure passed to the driver for executing commands 68 * on the driver reader thread. 69 */ 70 struct ReadParameters { 71 ReadCommand command; // discriminator 72 union Params { 73 uint64_t read; // READ command, amount of bytes to read, >= 0. 74 // No parameters for GET_CAPTURE_POSITION. 75 } params; 76 }; 77 78 /** 79 * Data structure passed back to the client via status message queue 80 * of 'read' operation. 81 * 82 * Possible values of 'retval' field: 83 * - OK, read operation was successful; 84 * - INVALID_ARGUMENTS, stream was not configured properly; 85 * - INVALID_STATE, stream is in a state that doesn't allow reads. 86 */ 87 struct ReadStatus { 88 Result retval; 89 ReadCommand replyTo; // discriminator 90 union Reply { 91 uint64_t read; // READ command, amount of bytes read, >= 0. 92 struct CapturePosition { // same as generated by getCapturePosition. 93 uint64_t frames; 94 uint64_t time; 95 } capturePosition; 96 } reply; 97 }; 98 99 /** 100 * Set up required transports for receiving audio buffers from the driver. 101 * 102 * The transport consists of three message queues: 103 * -- command queue is used to instruct the reader thread what operation 104 * to perform; 105 * -- data queue is used for passing audio data from the driver 106 * to the client; 107 * -- status queue is used for reporting operation status 108 * (e.g. amount of bytes actually read or error code). 109 * 110 * The driver operates on a dedicated thread. The client must ensure that 111 * the thread is given an appropriate priority and assigned to correct 112 * scheduler and cgroup. For this purpose, the method returns the identifier 113 * of the driver thread. 114 * 115 * @param frameSize the size of a single frame, in bytes. 116 * @param framesCount the number of frames in a buffer. 117 * @param threadPriority priority of the driver thread. 118 * @return retval OK if both message queues were created successfully. 119 * INVALID_STATE if the method was already called. 120 * INVALID_ARGUMENTS if there was a problem setting up 121 * the queues. 122 * @return commandMQ a message queue used for passing commands. 123 * @return dataMQ a message queue used for passing audio data in the format 124 * specified at the stream opening. 125 * @return statusMQ a message queue used for passing status from the driver 126 * using ReadStatus structures. 127 * @return threadId identifier of the driver's dedicated thread; the caller 128 * may adjust the thread priority to match the priority 129 * of the thread that provides audio data. 130 */ 131 prepareForReading(uint32_t frameSize, uint32_t framesCount) 132 generates ( 133 Result retval, 134 fmq_sync<ReadParameters> commandMQ, 135 fmq_sync<uint8_t> dataMQ, 136 fmq_sync<ReadStatus> statusMQ, 137 int32_t threadId); 138 139 /** 140 * Return the amount of input frames lost in the audio driver since the last 141 * call of this function. 142 * 143 * Audio driver is expected to reset the value to 0 and restart counting 144 * upon returning the current value by this function call. Such loss 145 * typically occurs when the user space process is blocked longer than the 146 * capacity of audio driver buffers. 147 * 148 * @return framesLost the number of input audio frames lost. 149 */ 150 getInputFramesLost() generates (uint32_t framesLost); 151 152 /** 153 * Return a recent count of the number of audio frames received and the 154 * clock time associated with that frame count. The count must not reset to 155 * zero when a PCM input enters standby. 156 * 157 * @return retval INVALID_STATE if the device is not ready/available, 158 * NOT_SUPPORTED if the command is not supported, 159 * OK otherwise. 160 * @return frames the total frame count received. This must be as early in 161 * the capture pipeline as possible. In general, frames 162 * must be non-negative and must not go "backwards". 163 * @return time is the clock monotonic time when frames was measured. In 164 * general, time must be a positive quantity and must not 165 * go "backwards". 166 */ 167 getCapturePosition() 168 generates (Result retval, uint64_t frames, uint64_t time); 169 170 /** 171 * Returns an array with active microphones in the stream. 172 * 173 * @return retval INVALID_STATE if the call is not successful, 174 * OK otherwise. 175 * 176 * @return microphones array with microphones info 177 */ 178 getActiveMicrophones() 179 generates(Result retval, vec<MicrophoneInfo> microphones); 180 181 /** 182 * Specifies the logical microphone (for processing). 183 * 184 * If the feature is not supported an error should be returned 185 * If multiple microphones are present, this should be treated as a preference 186 * for their combined direction. 187 * 188 * Optional method 189 * 190 * @param Direction constant 191 * @return retval OK if the call is successful, an error code otherwise. 192 */ 193 setMicrophoneDirection(MicrophoneDirection direction) 194 generates(Result retval); 195 196 /** 197 * Specifies the zoom factor for the selected microphone (for processing). 198 * 199 * If the feature is not supported an error should be returned 200 * If multiple microphones are present, this should be treated as a preference 201 * for their combined field dimension. 202 * 203 * Optional method 204 * 205 * @param the desired field dimension of microphone capture. Range is from -1 (wide angle), 206 * though 0 (no zoom) to 1 (maximum zoom). 207 * 208 * @return retval OK if the call is not successful, an error code otherwise. 209 */ 210 setMicrophoneFieldDimension(float zoom) generates(Result retval); 211}; 212