1/*
2 * Copyright (C) 2019 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@6.0;
18
19import android.hardware.audio.common@6.0;
20import android.hardware.audio.effect@6.0::IEffect;
21
22interface IStream {
23    /**
24     * Return the frame size (number of bytes per sample).
25     *
26     * @return frameSize frame size in bytes.
27     */
28    getFrameSize() generates (uint64_t frameSize);
29
30    /**
31     * Return the frame count of the buffer. Calling this method is equivalent
32     * to getting AUDIO_PARAMETER_STREAM_FRAME_COUNT on the legacy HAL.
33     *
34     * @return count frame count.
35     */
36    getFrameCount() generates (uint64_t count);
37
38    /**
39     * Return the size of input/output buffer in bytes for this stream.
40     * It must be a multiple of the frame size.
41     *
42     * @return buffer buffer size in bytes.
43     */
44    getBufferSize() generates (uint64_t bufferSize);
45
46    /**
47     * Return the sampling rate in Hz.
48     *
49     * @return sampleRateHz sample rate in Hz.
50     */
51    getSampleRate() generates (uint32_t sampleRateHz);
52
53    /**
54     * Return supported native sampling rates of the stream for a given format.
55     * A supported native sample rate is a sample rate that can be efficiently
56     * played by the hardware (typically without sample-rate conversions).
57     *
58     * This function is only called for dynamic profile. If called for
59     * non-dynamic profile is should return NOT_SUPPORTED or the same list
60     * as in audio_policy_configuration.xml.
61     *
62     * Calling this method is equivalent to getting
63     * AUDIO_PARAMETER_STREAM_SUP_SAMPLING_RATES on the legacy HAL.
64     *
65     *
66     * @param format audio format for which the sample rates are supported.
67     * @return retval operation completion status.
68     *                Must be OK if the format is supported.
69     * @return sampleRateHz supported sample rates.
70     */
71    getSupportedSampleRates(AudioFormat format)
72            generates (Result retval, vec<uint32_t> sampleRates);
73
74    /**
75     * Sets the sampling rate of the stream. Calling this method is equivalent
76     * to setting AUDIO_PARAMETER_STREAM_SAMPLING_RATE on the legacy HAL.
77     * Optional method. If implemented, only called on a stopped stream.
78     *
79     * @param sampleRateHz sample rate in Hz.
80     * @return retval operation completion status.
81     */
82    setSampleRate(uint32_t sampleRateHz) generates (Result retval);
83
84    /**
85     * Return the channel mask of the stream.
86     *
87     * @return mask channel mask.
88     */
89    getChannelMask() generates (bitfield<AudioChannelMask> mask);
90
91    /**
92     * Return supported channel masks of the stream. Calling this method is
93     * equivalent to getting AUDIO_PARAMETER_STREAM_SUP_CHANNELS on the legacy
94     * HAL.
95     *
96     * @param format audio format for which the channel masks are supported.
97     * @return retval operation completion status.
98     *                Must be OK if the format is supported.
99     * @return masks supported audio masks.
100     */
101    getSupportedChannelMasks(AudioFormat format)
102            generates (Result retval, vec<bitfield<AudioChannelMask>> masks);
103
104    /**
105     * Sets the channel mask of the stream. Calling this method is equivalent to
106     * setting AUDIO_PARAMETER_STREAM_CHANNELS on the legacy HAL.
107     * Optional method
108     *
109     * @param format audio format.
110     * @return retval operation completion status.
111     */
112    setChannelMask(bitfield<AudioChannelMask> mask) generates (Result retval);
113
114    /**
115     * Return the audio format of the stream.
116     *
117     * @return format audio format.
118     */
119    getFormat() generates (AudioFormat format);
120
121    /**
122     * Return supported audio formats of the stream. Calling this method is
123     * equivalent to getting AUDIO_PARAMETER_STREAM_SUP_FORMATS on the legacy
124     * HAL.
125     *
126     * @return retval operation completion status.
127     * @return formats supported audio formats.
128     *                 Must be non empty if retval is OK.
129     */
130    getSupportedFormats() generates (Result retval, vec<AudioFormat> formats);
131
132    /**
133     * Sets the audio format of the stream. Calling this method is equivalent to
134     * setting AUDIO_PARAMETER_STREAM_FORMAT on the legacy HAL.
135     * Optional method
136     *
137     * @param format audio format.
138     * @return retval operation completion status.
139     */
140    setFormat(AudioFormat format) generates (Result retval);
141
142    /**
143     * Convenience method for retrieving several stream parameters in
144     * one transaction.
145     *
146     * @return sampleRateHz sample rate in Hz.
147     * @return mask channel mask.
148     * @return format audio format.
149     */
150    getAudioProperties() generates (
151            uint32_t sampleRateHz, bitfield<AudioChannelMask> mask, AudioFormat format);
152
153    /**
154     * Applies audio effect to the stream.
155     *
156     * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of
157     *                 the effect to apply.
158     * @return retval operation completion status.
159     */
160    addEffect(uint64_t effectId) generates (Result retval);
161
162    /**
163     * Stops application of the effect to the stream.
164     *
165     * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of
166     *                 the effect to remove.
167     * @return retval operation completion status.
168     */
169    removeEffect(uint64_t effectId) generates (Result retval);
170
171    /**
172     * Put the audio hardware input/output into standby mode.
173     * Driver must exit from standby mode at the next I/O operation.
174     *
175     * @return retval operation completion status.
176     */
177    standby() generates (Result retval);
178
179    /**
180     * Return the set of devices which this stream is connected to.
181     * Optional method
182     *
183     * @return retval operation completion status: OK or NOT_SUPPORTED.
184     * @return device set of devices which this stream is connected to.
185     */
186    getDevices() generates (Result retval, vec<DeviceAddress> devices);
187
188    /**
189     * Connects the stream to one or multiple devices.
190     *
191     * This method must only be used for HALs that do not support
192     * 'IDevice.createAudioPatch' method. Calling this method is
193     * equivalent to setting AUDIO_PARAMETER_STREAM_ROUTING preceded
194     * with a device address in the legacy HAL interface.
195     *
196     * @param address device to connect the stream to.
197     * @return retval operation completion status.
198     */
199    setDevices(vec<DeviceAddress> devices) generates (Result retval);
200
201    /**
202     * Sets the HW synchronization source. Calling this method is equivalent to
203     * setting AUDIO_PARAMETER_STREAM_HW_AV_SYNC on the legacy HAL.
204     * Optional method
205     *
206     * @param hwAvSync HW synchronization source
207     * @return retval operation completion status.
208     */
209    setHwAvSync(AudioHwSync hwAvSync) generates (Result retval);
210
211    /**
212     * Generic method for retrieving vendor-specific parameter values.
213     * The framework does not interpret the parameters, they are passed
214     * in an opaque manner between a vendor application and HAL.
215     *
216     * Multiple parameters can be retrieved at the same time.
217     * The implementation should return as many requested parameters
218     * as possible, even if one or more is not supported
219     *
220     * @param context provides more information about the request
221     * @param keys keys of the requested parameters
222     * @return retval operation completion status.
223     *         OK must be returned if keys is empty.
224     *         NOT_SUPPORTED must be returned if at least one key is unknown.
225     * @return parameters parameter key value pairs.
226     *         Must contain the value of all requested keys if retval == OK
227     */
228    getParameters(vec<ParameterValue> context, vec<string> keys)
229            generates (Result retval, vec<ParameterValue> parameters);
230
231    /**
232     * Generic method for setting vendor-specific parameter values.
233     * The framework does not interpret the parameters, they are passed
234     * in an opaque manner between a vendor application and HAL.
235     *
236     * Multiple parameters can be set at the same time though this is
237     * discouraged as it make failure analysis harder.
238     *
239     * If possible, a failed setParameters should not impact the platform state.
240     *
241     * @param context provides more information about the request
242     * @param parameters parameter key value pairs.
243     * @return retval operation completion status.
244     *         All parameters must be successfully set for OK to be returned
245     */
246    setParameters(vec<ParameterValue> context, vec<ParameterValue> parameters)
247            generates (Result retval);
248
249    /**
250     * Called by the framework to start a stream operating in mmap mode.
251     * createMmapBuffer() must be called before calling start().
252     * Function only implemented by streams operating in mmap mode.
253     *
254     * @return retval OK in case the success.
255     *                NOT_SUPPORTED on non mmap mode streams
256     *                INVALID_STATE if called out of sequence
257     */
258    start() generates (Result retval);
259
260    /**
261     * Called by the framework to stop a stream operating in mmap mode.
262     * Function only implemented by streams operating in mmap mode.
263     *
264     * @return retval OK in case the success.
265     *                NOT_SUPPORTED on non mmap mode streams
266     *                INVALID_STATE if called out of sequence
267     */
268    stop() generates (Result retval) ;
269
270    /**
271     * Called by the framework to retrieve information on the mmap buffer used for audio
272     * samples transfer.
273     * Function only implemented by streams operating in mmap mode.
274     *
275     * @param minSizeFrames minimum buffer size requested. The actual buffer
276     *                     size returned in struct MmapBufferInfo can be larger.
277     *                     The size must be a positive value.
278     * @return retval OK in case the success.
279     *                NOT_SUPPORTED on non mmap mode streams
280     *                NOT_INITIALIZED in case of memory allocation error
281     *                INVALID_ARGUMENTS if the requested buffer size is invalid
282     *                INVALID_STATE if called out of sequence
283     * @return info    a MmapBufferInfo struct containing information on the MMMAP buffer created.
284     */
285    createMmapBuffer(int32_t minSizeFrames)
286            generates (Result retval, MmapBufferInfo info);
287
288    /**
289     * Called by the framework to read current read/write position in the mmap buffer
290     * with associated time stamp.
291     * Function only implemented by streams operating in mmap mode.
292     *
293     * @return retval OK in case the success.
294     *                NOT_SUPPORTED on non mmap mode streams
295     *                INVALID_STATE if called out of sequence
296     * @return position a MmapPosition struct containing current HW read/write position in frames
297     *                  with associated time stamp.
298     */
299    getMmapPosition()
300            generates (Result retval, MmapPosition position);
301
302    /**
303     * Called by the framework to deinitialize the stream and free up
304     * all currently allocated resources. It is recommended to close
305     * the stream on the client side as soon as it is becomes unused.
306     *
307     * The client must ensure that this function is not called while
308     * audio data is being transferred through the stream's message queues.
309     *
310     * @return retval OK in case the success.
311     *                NOT_SUPPORTED if called on IStream instead of input or
312     *                              output stream interface.
313     *                INVALID_STATE if the stream was already closed.
314     */
315    @exit
316    close() generates (Result retval);
317};
318