fixup! Fix SVACE defects (DEREF_OF_NULL.RET.ALLOC)
[platform/adaptation/spreadtrum/audio-hal-sc7727.git] / tizen-audio.h
1 /*
2  * audio-hal
3  *
4  * Copyright (c) 2015 - 2016 Samsung Electronics Co., Ltd. All rights reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  *
18  */
19
20 #ifndef footizenaudiofoo
21 #define footizenaudiofoo
22
23 #include <stdint.h>
24
25 /**
26  * @file tizen-audio.h
27  * @brief This file contains the Audio Hardware Abstraction Layer Interfaces.
28  */
29
30 /**
31  * @addtogroup TIZEN_AUDIO_HAL_MODULE
32  * @{
33  */
34
35 /**
36  * @brief Enumeration for return codes.
37  * @since_tizen 3.0
38  */
39 typedef enum audio_return {
40     AUDIO_RET_OK                        = 0,
41     AUDIO_ERR_UNDEFINED                 = (int32_t)0x80001000,
42     AUDIO_ERR_RESOURCE                  = (int32_t)0x80001001,
43     AUDIO_ERR_PARAMETER                 = (int32_t)0x80001002,
44     AUDIO_ERR_IOCTL                     = (int32_t)0x80001003,
45     AUDIO_ERR_INVALID_STATE             = (int32_t)0x80001004,
46     AUDIO_ERR_INTERNAL                  = (int32_t)0x80001005,
47     /* add new enemerator here */
48     AUDIO_ERR_NOT_IMPLEMENTED           = (int32_t)0x80001100,
49 } audio_return_t ;
50
51 /**
52  * @brief Enumeration for audio direction.
53  * @since_tizen 3.0
54  */
55 typedef enum audio_direction {
56     AUDIO_DIRECTION_IN,                 /**< Capture */
57     AUDIO_DIRECTION_OUT,                /**< Playback */
58 } audio_direction_t;
59
60 /**
61  * @brief Device information including type, direction and id.
62  * @since_tizen 3.0
63  */
64 typedef struct device_info {
65     const char *type;
66     uint32_t direction;
67     uint32_t id;
68 } device_info_t;
69
70 /**
71  * @brief Volume information including type, gain and direction.
72  * @since_tizen 3.0
73  */
74 typedef struct audio_volume_info {
75     const char *type;
76     const char *gain;
77     uint32_t direction;
78 } audio_volume_info_t ;
79
80 /**
81  * @brief Route information including role and device.
82  * @since_tizen 3.0
83  */
84 typedef struct audio_route_info {
85     const char *role;
86     device_info_t *device_infos;
87     uint32_t num_of_devices;
88 } audio_route_info_t;
89
90 /**
91  * @brief Route option including role, name and value.
92  * @since_tizen 3.0
93  */
94 typedef struct audio_route_option {
95     const char *role;
96     const char *name;
97     int32_t value;
98 } audio_route_option_t;
99
100 /**
101  * @brief Stream information including role, direction and index.
102  * @since_tizen 3.0
103  */
104 typedef struct audio_stream_info {
105     const char *role;
106     uint32_t direction;
107     uint32_t idx;
108 } audio_stream_info_t ;
109
110 /**
111  * @brief Called when audio hal implementation needs to send a message.
112  * @since_tizen 3.0
113  * @param[in] name The message name
114  * @param[in] value The message value
115  * @param[in] user_data The user data passed from the callback registration function
116  *
117  * @see audio_add_message_cb()
118  * @see audio_remove_message_cb()
119  */
120 typedef void (*message_cb)(const char *name, int value, void *user_data);
121
122 /* Overall */
123 typedef struct audio_interface {
124     /* Initialization & de-initialization */
125     audio_return_t (*init)(void **audio_handle);
126     audio_return_t (*deinit)(void *audio_handle);
127     /* Volume */
128     audio_return_t (*get_volume_level_max)(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
129     audio_return_t (*get_volume_level)(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
130     audio_return_t (*set_volume_level)(void *audio_handle, audio_volume_info_t *info, uint32_t level);
131     audio_return_t (*get_volume_value)(void *audio_handle, audio_volume_info_t *info, uint32_t level, double *value);
132     audio_return_t (*get_volume_mute)(void *audio_handle, audio_volume_info_t *info, uint32_t *mute);
133     audio_return_t (*set_volume_mute)(void *audio_handle, audio_volume_info_t *info, uint32_t mute);
134     audio_return_t (*set_volume_ratio)(void *audio_handle, audio_stream_info_t *info, double ratio);
135     /* Routing */
136     audio_return_t (*update_route)(void *audio_handle, audio_route_info_t *info);
137     audio_return_t (*update_route_option)(void *audio_handle, audio_route_option_t *option);
138     /* Stream */
139     audio_return_t (*notify_stream_connection_changed)(void *audio_handle, audio_stream_info_t *info, uint32_t is_connected);
140     /* PCM */
141     audio_return_t (*pcm_open)(void *audio_handle, const char *card, const char *device, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods, void **pcm_handle);
142     audio_return_t (*pcm_start)(void *audio_handle, void *pcm_handle);
143     audio_return_t (*pcm_stop)(void *audio_handle, void *pcm_handle);
144     audio_return_t (*pcm_close)(void *audio_handle, void *pcm_handle);
145     audio_return_t (*pcm_avail)(void *audio_handle, void *pcm_handle, uint32_t *avail);
146     audio_return_t (*pcm_write)(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames);
147     audio_return_t (*pcm_read)(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames);
148     audio_return_t (*pcm_get_fd)(void *audio_handle, void *pcm_handle, int *fd);
149     audio_return_t (*pcm_recover)(void *audio_handle, void *pcm_handle, int revents);
150     audio_return_t (*pcm_get_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void **sample_spec, uint32_t *period_size, uint32_t *periods);
151     audio_return_t (*pcm_set_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods);
152     /* Message callback */
153     audio_return_t (*add_message_cb)(void *audio_handle, message_cb callback, void *user_data);
154     audio_return_t (*remove_message_cb)(void *audio_handle, message_cb callback);
155 } audio_interface_t;
156
157 /**
158  * @brief Initializes audio hal.
159  * @since_tizen 3.0
160  * @param[out] audio_handle The audio hal handle
161  *
162  * @return @c 0 on success,
163  *         otherwise a negative error value
164  * @retval #AUDIO_RET_OK Success
165  * @see audio_deinit()
166  */
167 audio_return_t audio_init(void **audio_handle);
168
169 /**
170  * @brief De-initializes audio hal.
171  * @since_tizen 3.0
172  * @param[in] audio_handle The audio hal handle
173  *
174  * @return @c 0 on success,
175  *         otherwise a negative error value
176  * @retval #AUDIO_RET_OK Success
177  * @see audio_init()
178  */
179 audio_return_t audio_deinit(void *audio_handle);
180
181 /**
182  * @brief Gets the maximum volume level supported for a particular volume information.
183  * @since_tizen 3.0
184  * @param[in] audio_handle The audio hal handle
185  * @param[in] info The audio volume information
186  * @param[out] level The maximum volume level
187  *
188  * @return @c 0 on success,
189  *         otherwise a negative error value
190  * @retval #AUDIO_RET_OK Success
191  * @see audio_set_volume_level()
192  * @see audio_get_volume_level()
193  * @see audio_get_volume_value()
194  */
195 audio_return_t audio_get_volume_level_max(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
196
197 /**
198  * @brief Gets the volume level specified for a particular volume information.
199  * @since_tizen 3.0
200  * @param[in] audio_handle The audio hal handle
201  * @param[in] info The audio volume information
202  * @param[out] level The current volume level
203  *
204  * @return @c 0 on success,
205  *         otherwise a negative error value
206  * @retval #AUDIO_RET_OK Success
207  * @see audio_set_volume_level()
208  * @see audio_get_volume_level_max()
209  * @see audio_get_volume_value()
210  */
211 audio_return_t audio_get_volume_level(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
212
213 /**
214  * @brief Sets the volume level specified for a particular volume information.
215  * @since_tizen 3.0
216  * @param[in] audio_handle The audio hal handle
217  * @param[in] info The audio volume information
218  * @param[in] level The volume level to be set
219  *
220  * @return @c 0 on success,
221  *         otherwise a negative error value
222  * @retval #AUDIO_RET_OK Success
223  * @see audio_get_volume_level()
224  * @see audio_get_volume_level_max()
225  * @see audio_get_volume_value()
226  */
227 audio_return_t audio_set_volume_level(void *audio_handle, audio_volume_info_t *info, uint32_t level);
228
229 /**
230  * @brief Gets the volume value specified for a particular volume information and level.
231  * @since_tizen 3.0
232  * @param[in] audio_handle The audio hal handle
233  * @param[in] info The audio volume information
234  * @param[in] level The volume level
235  * @param[out] value The volume value (range is from 0.0 to 1.0 inclusive, 1.0 = 100%)
236  *
237  * @return @c 0 on success,
238  *         otherwise a negative error value
239  * @retval #AUDIO_RET_OK Success
240  * @see audio_set_volume_level()
241  * @see audio_get_volume_level()
242  * @see audio_get_volume_level_max()
243  */
244 audio_return_t audio_get_volume_value(void *audio_handle, audio_volume_info_t *info, uint32_t level, double *value);
245
246 /**
247  * @brief Gets the volume mute specified for a particular volume information.
248  * @since_tizen 3.0
249  * @param[in] audio_handle The audio hal handle
250  * @param[in] info The audio volume information
251  * @param[out] mute The volume mute state : (@c 0 = unmute, @c 1 = mute)
252  *
253  * @return @c 0 on success,
254  *         otherwise a negative error value
255  * @retval #AUDIO_RET_OK Success
256  * @see audio_set_volume_mute()
257  */
258 audio_return_t audio_get_volume_mute(void *audio_handle, audio_volume_info_t *info, uint32_t *mute);
259
260 /**
261  * @brief Sets the volume mute specified for a particular volume information.
262  * @since_tizen 3.0
263  * @param[in] audio_handle The audio hal handle
264  * @param[in] info The audio volume information
265  * @param[in] mute The volume mute state to be set : (@c 0 = unmute, @c 1 = mute)
266  *
267  * @return @c 0 on success,
268  *         otherwise a negative error value
269  * @retval #AUDIO_RET_OK Success
270  * @see audio_get_volume_mute()
271  */
272 audio_return_t audio_set_volume_mute(void *audio_handle, audio_volume_info_t *info, uint32_t mute);
273
274 /**
275  * @brief Updates the audio routing according to audio route information.
276  * @since_tizen 3.0
277  * @param[in] audio_handle The audio hal handle
278  * @param[in] info The audio route information including role and devices
279  *
280  * @return @c 0 on success,
281  *         otherwise a negative error value
282  * @retval #AUDIO_RET_OK Success
283  * @see audio_update_route_option()
284  */
285 audio_return_t audio_update_route(void *audio_handle, audio_route_info_t *info);
286
287 /**
288  * @brief Updates audio routing option according to audio route option.
289  * @since_tizen 3.0
290  * @param[in] audio_handle The audio hal handle
291  * @param[in] option The option that can be used for audio routing including role, name and value
292  *
293  * @remarks This option can be used for audio routing.\n
294  * It is recommended to apply this option for routing per each role.
295  *
296  * @return @c 0 on success,
297  *         otherwise a negative error value
298  * @retval #AUDIO_RET_OK Success
299  * @see audio_update_route()
300  */
301 audio_return_t audio_update_route_option(void *audio_handle, audio_route_option_t *option);
302
303 /**
304  * @brief Gets notified when a stream is connected and disconnected.
305  * @since_tizen 3.0
306  * @param[in] audio_handle The audio hal handle
307  * @param[in] info The stream information including role, direction, index
308  * @param[in] is_connected The connection state of this stream (@c true = connected, @c false = disconnected)
309  *
310  * @remarks This information can be used for audio routing, volume controls and so on.
311  *
312  * @return @c 0 on success,
313  *         otherwise a negative error value
314  * @retval #AUDIO_RET_OK Success
315  */
316 audio_return_t audio_notify_stream_connection_changed(void *audio_handle, audio_stream_info_t *info, uint32_t is_connected);
317
318 /**
319  * @brief Opens a PCM device.
320  * @since_tizen 3.0
321  * @param[in] audio_handle The audio hal handle
322  * @param[in] card The card of PCM
323  * @param[in] device The device of PCM
324  * @param[in] direction The direction of PCM
325  * @param[in] sample_spec The sample specification
326  * @param[in] period_size The period size
327  * @param[in] periods The periods
328  * @param[out] pcm_handle The PCM handle
329  *
330  * @return @c 0 on success,
331  *         otherwise a negative error value
332  * @retval #AUDIO_RET_OK Success
333  * @see audio_pcm_close()
334  */
335 audio_return_t audio_pcm_open(void *audio_handle, const char *card, const char *device, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods, void **pcm_handle);
336
337 /**
338  * @brief Starts a PCM device.
339  * @since_tizen 3.0
340  * @param[in] audio_handle The audio hal handle
341  * @param[in] pcm_handle The PCM handle to be started
342  *
343  * @return @c 0 on success,
344  *         otherwise a negative error value
345  * @retval #AUDIO_RET_OK Success
346  * @see audio_pcm_avail()
347  * @see audio_pcm_write()
348  * @see audio_pcm_read()
349  * @see audio_pcm_stop()
350  * @see audio_pcm_recover()
351  */
352 audio_return_t audio_pcm_start(void *audio_handle, void *pcm_handle);
353
354 /**
355  * @brief Stops a PCM device.
356  * @since_tizen 3.0
357  * @param[in] audio_handle The audio hal handle
358  * @param[in] pcm_handle The PCM handle to be stopped
359  *
360  * @return @c 0 on success,
361  *         otherwise a negative error value
362  * @retval #AUDIO_RET_OK Success
363  * @see audio_pcm_start()
364  */
365 audio_return_t audio_pcm_stop(void *audio_handle, void *pcm_handle);
366
367 /**
368  * @brief Closes a PCM device.
369  * @since_tizen 3.0
370  * @param[in] audio_handle The audio hal handle
371  * @param[in] pcm_handle The PCM handle to be closed
372  *
373  * @return @c 0 on success,
374  *         otherwise a negative error value
375  * @retval #AUDIO_RET_OK Success
376  * @see audio_pcm_open()
377  */
378 audio_return_t audio_pcm_close(void *audio_handle, void *pcm_handle);
379
380 /**
381  * @brief Gets available number of frames.
382  * @since_tizen 3.0
383  * @param[in] audio_handle The audio hal handle
384  * @param[in] pcm_handle The PCM handle
385  * @param[out] avail The available number of frames
386  *
387  * @return @c 0 on success,
388  *         otherwise a negative error value
389  * @retval #AUDIO_RET_OK Success
390  * @see audio_pcm_write()
391  * @see audio_pcm_read()
392  */
393 audio_return_t audio_pcm_avail(void *audio_handle, void *pcm_handle, uint32_t *avail);
394
395 /**
396  * @brief Writes frames to a PCM device.
397  * @since_tizen 3.0
398  * @param[in] audio_handle The audio hal handle
399  * @param[in] pcm_handle The PCM handle
400  * @param[in] buffer The buffer containing frames
401  * @param[in] frames The number of frames to be written
402  *
403  * @return @c 0 on success,
404  *         otherwise a negative error value
405  * @retval #AUDIO_RET_OK Success
406  * @see audio_pcm_avail()
407  * @see audio_pcm_recover()
408  */
409 audio_return_t audio_pcm_write(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames);
410
411 /**
412  * @brief Reads frames from a PCM device.
413  * @since_tizen 3.0
414  * @param[in] audio_handle The audio hal handle
415  * @param[in] pcm_handle The PCM handle
416  * @param[out] buffer The buffer containing frames
417  * @param[in] frames The number of frames to be read
418  *
419  * @return @c 0 on success,
420  *         otherwise a negative error value
421  * @retval #AUDIO_RET_OK Success
422  * @see audio_pcm_avail()
423  * @see audio_pcm_recover()
424  */
425 audio_return_t audio_pcm_read(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames);
426
427 /**
428  * @brief Gets poll descriptor for a PCM handle.
429  * @since_tizen 3.0
430  * @param[in] audio_handle The audio hal handle
431  * @param[in] pcm_handle The PCM handle
432  * @param[out] fd The poll descriptor
433  *
434  * @return @c 0 on success,
435  *         otherwise a negative error value
436  * @retval #AUDIO_RET_OK Success
437  * @see audio_pcm_open()
438  * @see audio_pcm_recover()
439  */
440 audio_return_t audio_pcm_get_fd(void *audio_handle, void *pcm_handle, int *fd);
441
442 /**
443  * @brief Recovers the PCM state.
444  * @since_tizen 3.0
445  * @param[in] audio_handle The audio hal handle
446  * @param[in] pcm_handle The PCM handle
447  * @param[in] revents The returned event from pollfd
448  *
449  * @return @c 0 on success,
450  *         otherwise a negative error value
451  * @retval #AUDIO_RET_OK Success
452  * @see audio_pcm_start()
453  * @see audio_pcm_write()
454  * @see audio_pcm_read()
455  * @see audio_pcm_get_fd()
456  */
457 audio_return_t audio_pcm_recover(void *audio_handle, void *pcm_handle, int revents);
458
459 /**
460  * @brief Gets parameters of a PCM device.
461  * @since_tizen 3.0
462  * @param[in] audio_handle The audio hal handle
463  * @param[in] pcm_handle The PCM handle
464  * @param[in] direction The direction of PCM
465  * @param[out] sample_spec The sample specification
466  * @param[out] period_size The period size
467  * @param[out] periods The periods
468  *
469  * @return @c 0 on success,
470  *         otherwise a negative error value
471  * @retval #AUDIO_RET_OK Success
472  * @see audio_pcm_set_params()
473  */
474 audio_return_t audio_pcm_get_params(void *audio_handle, void *pcm_handle, uint32_t direction, void **sample_spec, uint32_t *period_size, uint32_t *periods);
475
476 /**
477  * @brief Sets hardware and software parameters of a PCM device.
478  * @since_tizen 3.0
479  * @param[in] audio_handle The audio hal handle
480  * @param[in] pcm_handle The PCM handle
481  * @param[in] direction The direction of PCM
482  * @param[in] sample_spec The sample specification
483  * @param[in] period_size The period size
484  * @param[in] periods The periods
485  *
486  * @return @c 0 on success,
487  *         otherwise a negative error value
488  * @retval #AUDIO_RET_OK Success
489  * @see audio_pcm_set_params()
490  */
491 audio_return_t audio_pcm_set_params(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods);
492
493 /**
494  * @brief Adds the message callback function.
495  * @since_tizen 3.0
496  * @param[in] audio_handle The audio hal handle
497  * @param[in] message_cb The message callback function
498  * @param[in] user_data The user data passed to the callback function
499  *
500  * @see message_cb()
501  * @see audio_remove_message_cb()
502  */
503 audio_return_t audio_add_message_cb(void *audio_handle, message_cb callback, void *user_data);
504
505 /**
506  * @brief Removes the message callback function.
507  * @since_tizen 3.0
508  * @param[in] audio_handle The audio hal handle
509  * @param[in] message_cb The message callback function to be removed
510  *
511  * @see message_cb()
512  * @see audio_add_message_cb()
513  */
514 audio_return_t audio_remove_message_cb(void *audio_handle, message_cb callback);
515
516 /**
517 * @}
518 */
519
520 /**
521 * @}
522 */
523
524 #endif