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 android.hardware.audio.effect@2.0::IEffect;
21
22interface 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