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