1/* 2 * Copyright (C) 2018 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@4.0; 18 19import android.hardware.audio.common@4.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 * Optional method 28 * 29 * @return retval operation completion status. 30 * @return source audio source. 31 */ 32 getAudioSource() generates (Result retval, AudioSource source); 33 34 /** 35 * Set the input gain for the audio driver. 36 * Optional method 37 * 38 * @param gain 1.0f is unity, 0.0f is zero. 39 * @result retval operation completion status. 40 */ 41 setGain(float gain) generates (Result retval); 42 43 /** 44 * Commands that can be executed on the driver reader thread. 45 */ 46 enum ReadCommand : int32_t { 47 READ, 48 GET_CAPTURE_POSITION 49 }; 50 51 /** 52 * Data structure passed to the driver for executing commands 53 * on the driver reader thread. 54 */ 55 struct ReadParameters { 56 ReadCommand command; // discriminator 57 union Params { 58 uint64_t read; // READ command, amount of bytes to read, >= 0. 59 // No parameters for GET_CAPTURE_POSITION. 60 } params; 61 }; 62 63 /** 64 * Data structure passed back to the client via status message queue 65 * of 'read' operation. 66 * 67 * Possible values of 'retval' field: 68 * - OK, read operation was successful; 69 * - INVALID_ARGUMENTS, stream was not configured properly; 70 * - INVALID_STATE, stream is in a state that doesn't allow reads. 71 */ 72 struct ReadStatus { 73 Result retval; 74 ReadCommand replyTo; // discriminator 75 union Reply { 76 uint64_t read; // READ command, amount of bytes read, >= 0. 77 struct CapturePosition { // same as generated by getCapturePosition. 78 uint64_t frames; 79 uint64_t time; 80 } capturePosition; 81 } reply; 82 }; 83 84 /** 85 * Called when the metadata of the stream's sink has been changed. 86 * @param sinkMetadata Description of the audio that is suggested by the clients. 87 */ 88 updateSinkMetadata(SinkMetadata sinkMetadata); 89 90 /** 91 * Set up required transports for receiving audio buffers from the driver. 92 * 93 * The transport consists of three message queues: 94 * -- command queue is used to instruct the reader thread what operation 95 * to perform; 96 * -- data queue is used for passing audio data from the driver 97 * to the client; 98 * -- status queue is used for reporting operation status 99 * (e.g. amount of bytes actually read or error code). 100 * 101 * The driver operates on a dedicated thread. The client must ensure that 102 * the thread is given an appropriate priority and assigned to correct 103 * scheduler and cgroup. For this purpose, the method returns identifiers 104 * of the driver thread. 105 * 106 * @param frameSize the size of a single frame, in bytes. 107 * @param framesCount the number of frames in a buffer. 108 * @param threadPriority priority of the driver thread. 109 * @return retval OK if both message queues were created successfully. 110 * INVALID_STATE if the method was already called. 111 * INVALID_ARGUMENTS if there was a problem setting up 112 * the queues. 113 * @return commandMQ a message queue used for passing commands. 114 * @return dataMQ a message queue used for passing audio data in the format 115 * specified at the stream opening. 116 * @return statusMQ a message queue used for passing status from the driver 117 * using ReadStatus structures. 118 * @return threadInfo identifiers of the driver's dedicated thread. 119 */ 120 prepareForReading(uint32_t frameSize, uint32_t framesCount) 121 generates ( 122 Result retval, 123 fmq_sync<ReadParameters> commandMQ, 124 fmq_sync<uint8_t> dataMQ, 125 fmq_sync<ReadStatus> statusMQ, 126 ThreadInfo threadInfo); 127 128 /** 129 * Return the amount of input frames lost in the audio driver since the last 130 * call of this function. 131 * 132 * Audio driver is expected to reset the value to 0 and restart counting 133 * upon returning the current value by this function call. Such loss 134 * typically occurs when the user space process is blocked longer than the 135 * capacity of audio driver buffers. 136 * 137 * @return framesLost the number of input audio frames lost. 138 */ 139 getInputFramesLost() generates (uint32_t framesLost); 140 141 /** 142 * Return a recent count of the number of audio frames received and the 143 * clock time associated with that frame count. 144 * 145 * @return retval INVALID_STATE if the device is not ready/available, 146 * NOT_SUPPORTED if the command is not supported, 147 * OK otherwise. 148 * @return frames the total frame count received. This must be as early in 149 * the capture pipeline as possible. In general, frames 150 * must be non-negative and must not go "backwards". 151 * @return time is the clock monotonic time when frames was measured. In 152 * general, time must be a positive quantity and must not 153 * go "backwards". 154 */ 155 getCapturePosition() 156 generates (Result retval, uint64_t frames, uint64_t time); 157 158 /** 159 * Returns an array with active microphones in the stream. 160 * 161 * @return retval INVALID_STATE if the call is not successful, 162 * OK otherwise. 163 * 164 * @return microphones array with microphones info 165 */ 166 getActiveMicrophones() 167 generates(Result retval, vec<MicrophoneInfo> microphones); 168}; 169