1/*
2 * Copyright (C) 2020 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@7.0;
18
19import android.hardware.audio.common@7.0;
20import android.hardware.audio.effect@7.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 supported audio profiles for this particular stream. This method
48     * is normally called for streams opened on devices that use dynamic
49     * profiles, e.g. HDMI and USB interfaces. Please note that supported
50     * profiles of the stream may differ from the capabilities of the connected
51     * physical device.
52     *
53     * For devices with fixed configurations, e.g. built-in audio devices, all
54     * the profiles are specified in the audio_policy_configuration.xml
55     * file. For such devices, this method must return the configuration from
56     * the config file, or NOT_SUPPORTED retval.
57     *
58     * @return retval operation completion status.
59     * @return formats supported audio profiles.
60     *                 Must be non empty if retval is OK.
61     */
62    getSupportedProfiles()
63            generates (Result retval, vec<AudioProfile> profiles);
64
65    /**
66     * Retrieves basic stream configuration: sample rate, audio format,
67     * channel mask.
68     *
69     * @return retval operation completion status.
70     * @return config basic stream configuration.
71     */
72    getAudioProperties() generates (Result retval, AudioConfigBase config);
73
74    /**
75     * Sets stream parameters. Only sets parameters that are specified.
76     *
77     * Optional method. If implemented, only called on a stopped stream.
78     *
79     * @param config basic stream configuration.
80     * @return retval operation completion status.
81     */
82    setAudioProperties(AudioConfigBaseOptional config)
83            generates (Result retval);
84
85    /**
86     * Applies audio effect to the stream.
87     *
88     * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of
89     *                 the effect to apply.
90     * @return retval operation completion status.
91     */
92    addEffect(uint64_t effectId) generates (Result retval);
93
94    /**
95     * Stops application of the effect to the stream.
96     *
97     * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of
98     *                 the effect to remove.
99     * @return retval operation completion status.
100     */
101    removeEffect(uint64_t effectId) generates (Result retval);
102
103    /**
104     * Put the audio hardware input/output into standby mode.
105     * Driver must exit from standby mode at the next I/O operation.
106     *
107     * @return retval operation completion status.
108     */
109    standby() generates (Result retval);
110
111    /**
112     * Return the set of devices which this stream is connected to.
113     *
114     * Optional method
115     *
116     * @return retval operation completion status: OK or NOT_SUPPORTED.
117     * @return device set of devices which this stream is connected to.
118     */
119    getDevices() generates (Result retval, vec<DeviceAddress> devices);
120
121    /**
122     * Connects the stream to one or multiple devices.
123     *
124     * This method must only be used for HALs that do not support
125     * 'IDevice.createAudioPatch' method. Calling this method is
126     * equivalent to setting AUDIO_PARAMETER_STREAM_ROUTING preceded
127     * with a device address in the legacy HAL interface.
128     *
129     * @param address device to connect the stream to.
130     * @return retval operation completion status.
131     */
132    setDevices(vec<DeviceAddress> devices) generates (Result retval);
133
134    /**
135     * Sets the HW synchronization source. Calling this method is equivalent to
136     * setting AUDIO_PARAMETER_STREAM_HW_AV_SYNC on the legacy HAL.
137     *
138     * Optional method
139     *
140     * @param hwAvSync HW synchronization source
141     * @return retval operation completion status.
142     */
143    setHwAvSync(AudioHwSync hwAvSync) generates (Result retval);
144
145    /**
146     * Generic method for retrieving vendor-specific parameter values.
147     * The framework does not interpret the parameters, they are passed
148     * in an opaque manner between a vendor application and HAL.
149     *
150     * Multiple parameters can be retrieved at the same time.
151     * The implementation should return as many requested parameters
152     * as possible, even if one or more is not supported
153     *
154     * @param context provides more information about the request
155     * @param keys keys of the requested parameters
156     * @return retval operation completion status.
157     *         OK must be returned if keys is empty.
158     *         NOT_SUPPORTED must be returned if at least one key is unknown.
159     * @return parameters parameter key value pairs.
160     *         Must contain the value of all requested keys if retval == OK
161     */
162    getParameters(vec<ParameterValue> context, vec<string> keys)
163            generates (Result retval, vec<ParameterValue> parameters);
164
165    /**
166     * Generic method for setting vendor-specific parameter values.
167     * The framework does not interpret the parameters, they are passed
168     * in an opaque manner between a vendor application and HAL.
169     *
170     * Multiple parameters can be set at the same time though this is
171     * discouraged as it make failure analysis harder.
172     *
173     * If possible, a failed setParameters should not impact the platform state.
174     *
175     * @param context provides more information about the request
176     * @param parameters parameter key value pairs.
177     * @return retval operation completion status.
178     *         All parameters must be successfully set for OK to be returned
179     */
180    setParameters(vec<ParameterValue> context, vec<ParameterValue> parameters)
181            generates (Result retval);
182
183    /**
184     * Called by the framework to start a stream operating in mmap mode.
185     * createMmapBuffer() must be called before calling start().
186     * Function only implemented by streams operating in mmap mode.
187     *
188     * @return retval OK in case the success.
189     *                NOT_SUPPORTED on non mmap mode streams
190     *                INVALID_STATE if called out of sequence
191     */
192    start() generates (Result retval);
193
194    /**
195     * Called by the framework to stop a stream operating in mmap mode.
196     * Function only implemented by streams operating in mmap mode.
197     *
198     * @return retval OK in case the success.
199     *                NOT_SUPPORTED on non mmap mode streams
200     *                INVALID_STATE if called out of sequence
201     */
202    stop() generates (Result retval) ;
203
204    /**
205     * Called by the framework to retrieve information on the mmap buffer used for audio
206     * samples transfer.
207     * Function only implemented by streams operating in mmap mode.
208     *
209     * @param minSizeFrames minimum buffer size requested. The actual buffer
210     *                     size returned in struct MmapBufferInfo can be larger.
211     *                     The size must be a positive value.
212     * @return retval OK in case the success.
213     *                NOT_SUPPORTED on non mmap mode streams
214     *                NOT_INITIALIZED in case of memory allocation error
215     *                INVALID_ARGUMENTS if the requested buffer size is invalid
216     *                INVALID_STATE if called out of sequence
217     * @return info    a MmapBufferInfo struct containing information on the MMMAP buffer created.
218     */
219    createMmapBuffer(int32_t minSizeFrames)
220            generates (Result retval, MmapBufferInfo info);
221
222    /**
223     * Called by the framework to read current read/write position in the mmap buffer
224     * with associated time stamp.
225     * Function only implemented by streams operating in mmap mode.
226     *
227     * @return retval OK in case the success.
228     *                NOT_SUPPORTED on non mmap mode streams
229     *                INVALID_STATE if called out of sequence
230     * @return position a MmapPosition struct containing current HW read/write position in frames
231     *                  with associated time stamp.
232     */
233    getMmapPosition()
234            generates (Result retval, MmapPosition position);
235
236    /**
237     * Called by the framework to deinitialize the stream and free up
238     * all currently allocated resources. It is recommended to close
239     * the stream on the client side as soon as it is becomes unused.
240     *
241     * The client must ensure that this function is not called while
242     * audio data is being transferred through the stream's message queues.
243     *
244     * @return retval OK in case the success.
245     *                NOT_SUPPORTED if called on IStream instead of input or
246     *                              output stream interface.
247     *                INVALID_STATE if the stream was already closed.
248     */
249    close() generates (Result retval);
250};
251