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 IStreamIn;
21import IStreamOut;
22
23interface IDevice {
24    /**
25     * Returns whether the audio hardware interface has been initialized.
26     *
27     * @return retval OK on success, NOT_INITIALIZED on failure.
28     */
29    initCheck() generates (Result retval);
30
31    /**
32     * Sets the audio volume for all audio activities other than voice call. If
33     * NOT_SUPPORTED is returned, the software mixer will emulate this
34     * capability.
35     *
36     * @param volume 1.0f means unity, 0.0f is zero.
37     * @return retval operation completion status.
38     */
39    setMasterVolume(float volume) generates (Result retval);
40
41    /**
42     * Get the current master volume value for the HAL, if the HAL supports
43     * master volume control. For example, AudioFlinger will query this value
44     * from the primary audio HAL when the service starts and use the value for
45     * setting the initial master volume across all HALs. HALs which do not
46     * support this method must return NOT_SUPPORTED in 'retval'.
47     *
48     * @return retval operation completion status.
49     * @return volume 1.0f means unity, 0.0f is zero.
50     */
51    getMasterVolume() generates (Result retval, float volume);
52
53    /**
54     * Sets microphone muting state.
55     *
56     * @param mute whether microphone is muted.
57     * @return retval operation completion status.
58     */
59    setMicMute(bool mute) generates (Result retval);
60
61    /**
62     * Gets whether microphone is muted.
63     *
64     * @return retval operation completion status.
65     * @return mute whether microphone is muted.
66     */
67    getMicMute() generates (Result retval, bool mute);
68
69    /**
70     * Set the audio mute status for all audio activities. If the return value
71     * is NOT_SUPPORTED, the software mixer will emulate this capability.
72     *
73     * @param mute whether audio is muted.
74     * @return retval operation completion status.
75     */
76    setMasterMute(bool mute) generates (Result retval);
77
78    /**
79     * Get the current master mute status for the HAL, if the HAL supports
80     * master mute control. AudioFlinger will query this value from the primary
81     * audio HAL when the service starts and use the value for setting the
82     * initial master mute across all HALs. HAL must indicate that the feature
83     * is not supported by returning NOT_SUPPORTED status.
84     *
85     * @return retval operation completion status.
86     * @return mute whether audio is muted.
87     */
88    getMasterMute() generates (Result retval, bool mute);
89
90    /**
91     * Returns audio input buffer size according to parameters passed or
92     * INVALID_ARGUMENTS if one of the parameters is not supported.
93     *
94     * @param config audio configuration.
95     * @return retval operation completion status.
96     * @return bufferSize input buffer size in bytes.
97     */
98    getInputBufferSize(AudioConfig config)
99            generates (Result retval, uint64_t bufferSize);
100
101    /**
102     * This method creates and opens the audio hardware output stream.
103     * If the stream can not be opened with the proposed audio config,
104     * HAL must provide suggested values for the audio config.
105     *
106     * @param ioHandle handle assigned by AudioFlinger.
107     * @param device device type and (if needed) address.
108     * @param config stream configuration.
109     * @param flags additional flags.
110     * @param sourceMetadata Description of the audio that will be played.
111                             May be used by implementations to configure hardware effects.
112     * @return retval operation completion status.
113     * @return outStream created output stream.
114     * @return suggestedConfig in case of invalid parameters, suggested config.
115     */
116    openOutputStream(
117            AudioIoHandle ioHandle,
118            DeviceAddress device,
119            AudioConfig config,
120            bitfield<AudioOutputFlag> flags,
121            SourceMetadata sourceMetadata) generates (
122                    Result retval,
123                    IStreamOut outStream,
124                    AudioConfig suggestedConfig);
125
126    /**
127     * This method creates and opens the audio hardware input stream.
128     * If the stream can not be opened with the proposed audio config,
129     * HAL must provide suggested values for the audio config.
130     *
131     * @param ioHandle handle assigned by AudioFlinger.
132     * @param device device type and (if needed) address.
133     * @param config stream configuration.
134     * @param flags additional flags.
135     * @param sinkMetadata Description of the audio that is suggested by the client.
136     *                     May be used by implementations to configure processing effects.
137     * @return retval operation completion status.
138     * @return inStream in case of success, created input stream.
139     * @return suggestedConfig in case of invalid parameters, suggested config.
140     */
141    openInputStream(
142            AudioIoHandle ioHandle,
143            DeviceAddress device,
144            AudioConfig config,
145            bitfield<AudioInputFlag> flags,
146            SinkMetadata sinkMetadata) generates (
147                    Result retval,
148                    IStreamIn inStream,
149                    AudioConfig suggestedConfig);
150
151    /**
152     * Returns whether HAL supports audio patches. Patch represents a connection
153     * between signal source(s) and signal sink(s). If HAL doesn't support
154     * patches natively (in hardware) then audio system will need to establish
155     * them in software.
156     *
157     * @return supports true if audio patches are supported.
158     */
159    supportsAudioPatches() generates (bool supports);
160
161    /**
162     * Creates an audio patch between several source and sink ports.  The handle
163     * is allocated by the HAL and must be unique for this audio HAL module.
164     *
165     * @param sources patch sources.
166     * @param sinks patch sinks.
167     * @return retval operation completion status.
168     * @return patch created patch handle.
169     */
170    createAudioPatch(vec<AudioPortConfig> sources, vec<AudioPortConfig> sinks)
171            generates (Result retval, AudioPatchHandle patch);
172
173    /**
174     * Updates an audio patch.
175     *
176     * Use of this function is preferred to releasing and re-creating a patch
177     * as the HAL module can figure out a way of switching the route without
178     * causing audio disruption.
179     *
180     * @param previousPatch handle of the previous patch to update.
181     * @param sources new patch sources.
182     * @param sinks new patch sinks.
183     * @return retval operation completion status.
184     * @return patch updated patch handle.
185     */
186    updateAudioPatch(
187            AudioPatchHandle previousPatch,
188            vec<AudioPortConfig> sources,
189            vec<AudioPortConfig> sinks) generates (
190                    Result retval, AudioPatchHandle patch);
191
192    /**
193     * Release an audio patch.
194     *
195     * @param patch patch handle.
196     * @return retval operation completion status.
197     */
198    releaseAudioPatch(AudioPatchHandle patch) generates (Result retval);
199
200    /**
201     * Returns the list of supported attributes for a given audio port.
202     *
203     * As input, 'port' contains the information (type, role, address etc...)
204     * needed by the HAL to identify the port.
205     *
206     * As output, 'resultPort' contains possible attributes (sampling rates,
207     * formats, channel masks, gain controllers...) for this port.
208     *
209     * @param port port identifier.
210     * @return retval operation completion status.
211     * @return resultPort port descriptor with all parameters filled up.
212     */
213    getAudioPort(AudioPort port)
214            generates (Result retval, AudioPort resultPort);
215
216    /**
217     * Set audio port configuration.
218     *
219     * @param config audio port configuration.
220     * @return retval operation completion status.
221     */
222    setAudioPortConfig(AudioPortConfig config) generates (Result retval);
223
224    /**
225     * Gets the HW synchronization source of the device. Calling this method is
226     * equivalent to getting AUDIO_PARAMETER_HW_AV_SYNC on the legacy HAL.
227     * Optional method
228     *
229     * @return retval operation completion status: OK or NOT_SUPPORTED.
230     * @return hwAvSync HW synchronization source
231     */
232    getHwAvSync() generates (Result retval, AudioHwSync hwAvSync);
233
234    /**
235     * Sets whether the screen is on. Calling this method is equivalent to
236     * setting AUDIO_PARAMETER_KEY_SCREEN_STATE on the legacy HAL.
237     * Optional method
238     *
239     * @param turnedOn whether the screen is turned on.
240     * @return retval operation completion status.
241     */
242    setScreenState(bool turnedOn) generates (Result retval);
243
244    /**
245     * Generic method for retrieving vendor-specific parameter values.
246     * The framework does not interpret the parameters, they are passed
247     * in an opaque manner between a vendor application and HAL.
248     *
249     * Multiple parameters can be retrieved at the same time.
250     * The implementation should return as many requested parameters
251     * as possible, even if one or more is not supported
252     *
253     * @param context provides more information about the request
254     * @param keys keys of the requested parameters
255     * @return retval operation completion status.
256     *         OK must be returned if keys is empty.
257     *         NOT_SUPPORTED must be returned if at least one key is unknown.
258     * @return parameters parameter key value pairs.
259     *         Must contain the value of all requested keys if retval == OK
260     */
261    getParameters(vec<ParameterValue> context, vec<string> keys)
262            generates (Result retval, vec<ParameterValue> parameters);
263
264    /**
265     * Generic method for setting vendor-specific parameter values.
266     * The framework does not interpret the parameters, they are passed
267     * in an opaque manner between a vendor application and HAL.
268     *
269     * Multiple parameters can be set at the same time though this is
270     * discouraged as it make failure analysis harder.
271     *
272     * If possible, a failed setParameters should not impact the platform state.
273     *
274     * @param context provides more information about the request
275     * @param parameters parameter key value pairs.
276     * @return retval operation completion status.
277     *         All parameters must be successfully set for OK to be returned
278     */
279    setParameters(vec<ParameterValue> context, vec<ParameterValue> parameters)
280            generates (Result retval);
281
282    /**
283     * Returns an array with available microphones in device.
284     *
285     * @return retval NOT_SUPPORTED if there are no microphones on this device
286     *                INVALID_STATE if the call is not successful,
287     *                OK otherwise.
288     *
289     * @return microphones array with microphones info
290     */
291    getMicrophones()
292         generates(Result retval, vec<MicrophoneInfo> microphones);
293
294    /**
295     * Notifies the device module about the connection state of an input/output
296     * device attached to it. Calling this method is equivalent to setting
297     * AUDIO_PARAMETER_DEVICE_[DIS]CONNECT on the legacy HAL.
298     *
299     * @param address audio device specification.
300     * @param connected whether the device is connected.
301     * @return retval operation completion status.
302     */
303    setConnectedState(DeviceAddress address, bool connected)
304            generates (Result retval);
305
306    /**
307     * Called by the framework to deinitialize the device and free up
308     * all currently allocated resources. It is recommended to close
309     * the device on the client side as soon as it is becomes unused.
310     *
311     * Note that all streams must be closed by the client before
312     * attempting to close the device they belong to.
313     *
314     * @return retval OK in case the success.
315     *                INVALID_STATE if the device was already closed
316     *                or there are streams currently opened.
317     */
318    @exit
319    close() generates (Result retval);
320
321    /**
322     * Applies an audio effect to an audio device. The effect is inserted
323     * according to its insertion preference specified by INSERT_... EffectFlags
324     * in the EffectDescriptor.
325     *
326     * @param device identifies the sink or source device this effect must be applied to.
327     *               "device" is the AudioPortHandle indicated for the device when the audio
328     *                patch connecting that device was created.
329     * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of
330     *                 the effect to add.
331     * @return retval operation completion status.
332     */
333    addDeviceEffect(AudioPortHandle device, uint64_t effectId) generates (Result retval);
334
335    /**
336     * Stops applying an audio effect to an audio device.
337     *
338     * @param device identifies the sink or source device this effect was applied to.
339     *               "device" is the AudioPortHandle indicated for the device when the audio
340     *               patch is created at the audio HAL.
341     * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of
342     *                 the effect.
343     * @return retval operation completion status.
344     */
345    removeDeviceEffect(AudioPortHandle device, uint64_t effectId) generates (Result retval);
346};
347