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 17package android.hardware.audio@2.0; 18 19import android.hardware.audio.common@2.0; 20import IStream; 21 22interface IStreamIn extends IStream { 23 typedef android.hardware.audio@2.0::Result Result; 24 25 /** 26 * Returns the source descriptor of the input stream. Calling this method is 27 * equivalent to getting AUDIO_PARAMETER_STREAM_INPUT_SOURCE on the legacy 28 * HAL. 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 * @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 * Set up required transports for receiving audio buffers from the driver. 86 * 87 * The transport consists of three message queues: 88 * -- command queue is used to instruct the reader thread what operation 89 * to perform; 90 * -- data queue is used for passing audio data from the driver 91 * to the client; 92 * -- status queue is used for reporting operation status 93 * (e.g. amount of bytes actually read or error code). 94 * 95 * The driver operates on a dedicated thread. The client must ensure that 96 * the thread is given an appropriate priority and assigned to correct 97 * scheduler and cgroup. For this purpose, the method returns identifiers 98 * of the driver thread. 99 * 100 * @param frameSize the size of a single frame, in bytes. 101 * @param framesCount the number of frames in a buffer. 102 * @param threadPriority priority of the driver thread. 103 * @return retval OK if both message queues were created successfully. 104 * INVALID_STATE if the method was already called. 105 * INVALID_ARGUMENTS if there was a problem setting up 106 * the queues. 107 * @return commandMQ a message queue used for passing commands. 108 * @return dataMQ a message queue used for passing audio data in the format 109 * specified at the stream opening. 110 * @return statusMQ a message queue used for passing status from the driver 111 * using ReadStatus structures. 112 * @return threadInfo identifiers of the driver's dedicated thread. 113 */ 114 prepareForReading(uint32_t frameSize, uint32_t framesCount) 115 generates ( 116 Result retval, 117 fmq_sync<ReadParameters> commandMQ, 118 fmq_sync<uint8_t> dataMQ, 119 fmq_sync<ReadStatus> statusMQ, 120 ThreadInfo threadInfo); 121 122 /** 123 * Return the amount of input frames lost in the audio driver since the last 124 * call of this function. 125 * 126 * Audio driver is expected to reset the value to 0 and restart counting 127 * upon returning the current value by this function call. Such loss 128 * typically occurs when the user space process is blocked longer than the 129 * capacity of audio driver buffers. 130 * 131 * @return framesLost the number of input audio frames lost. 132 */ 133 getInputFramesLost() generates (uint32_t framesLost); 134 135 /** 136 * Return a recent count of the number of audio frames received and the 137 * clock time associated with that frame count. 138 * 139 * @return retval INVALID_STATE if the device is not ready/available, 140 * NOT_SUPPORTED if the command is not supported, 141 * OK otherwise. 142 * @return frames the total frame count received. This must be as early in 143 * the capture pipeline as possible. In general, frames 144 * must be non-negative and must not go "backwards". 145 * @return time is the clock monotonic time when frames was measured. In 146 * general, time must be a positive quantity and must not 147 * go "backwards". 148 */ 149 getCapturePosition() 150 generates (Result retval, uint64_t frames, uint64_t time); 151}; 152