Add hal documentation

[Version] 0.0.22
[Issue Type] Update

Change-Id: I40f46befd11c71df6173295a0003bdb559387b94
Signed-off-by: Jaechul Lee <jcsing.lee@samsung.com>

diff --git a/doc/hal_audio_doc.h b/doc/hal_audio_doc.h
new file mode 100644 (file)
index 0000000..b87b3e5
--- /dev/null
+++ b/doc/hal_audio_doc.h
@@ -0,0 +1,107 @@
+/*
+ * Copyright (c) 2024 Samsung Electronics Co., Ltd All Rights Reserved
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an AS IS BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __TIZEN_HAL_AUDIO_DOC_H__
+#define __TIZEN_HAL_AUDIO_DOC_H__
+
+/**
+ * @file hal_audio_doc.h
+ * @brief This file contains high level documentation of the HAL Audio.
+ */
+
+/**
+ * @defgroup HALAPI_HAL_AUDIO_MODULE Audio
+ * @brief The @ref HALAPI_HAL_AUDIO_MODULE provides functions for audio devices.
+ *
+ * @section HALAPI_HAL_AUDIO_MODULE_HEADER Required Header
+ *   \#include <hal-audio.h>
+ *
+ * @section HALAPI_HAL_AUDIO_MODULE_OVERVIEW Overview
+ * The Audio module in the HAL provides functions to manage audio playback and capture.
+ *
+ * Key functionalities include:
+ * - Initializing and deinitializing the audio hardware.
+ * - Opening and configuring PCM audio streams.
+ * - Starting and stopping audio operations.
+ * - Recovering from audio errors.
+ * - Closing audio streams to free resources.
+ *
+ * @subsection HALAPI_HAL_AUDIO_MODULE_STATE_DIAGRAM State Diagram
+ * @image html hal_audio_state_diagram.png
+ *
+ * @subsection HALAPI_HAL_AUDIO_MODULE_STATE_TRANSITIONS State Transitions
+ * <div><table class="doxtable" >
+ * <tr>
+ *    <th><b>FUNCTION</b></th>
+ *    <th><b>PRE-STATE</b></th>
+ *    <th><b>POST-STATE</b></th>
+ *    <th><b>SYNC TYPE</b></th>
+ * </tr>
+ * <tr>
+ *    <td> hal_audio_init() </td>
+ *    <td> N/A </td>
+ *    <td> CLOSE </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_audio_deinit() </td>
+ *    <td> CLOSE </td>
+ *    <td> N/A </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_audio_pcm_open() </td>
+ *    <td> CLOSE </td>
+ *    <td> OPEN </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_audio_pcm_set_params() </td>
+ *    <td> OPEN </td>
+ *    <td> SETUP </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_audio_pcm_start() </td>
+ *    <td> SETUP </td>
+ *    <td> RUNNING </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_audio_pcm_stop() </td>
+ *    <td> RUNNING </td>
+ *    <td> STOP </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_audio_pcm_close() </td>
+ *    <td> STOP </td>
+ *    <td> CLOSE </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * <tr>
+ *    <td> hal_audio_pcm_recover() </td>
+ *    <td> XRUN </td>
+ *    <td> RUNNING </td>
+ *    <td> SYNC </td>
+ * </tr>
+ * </table></div>
+ *
+ * For more information on the Audio features and the macros, see HAL Audio programming guides and tutorials.
+ */
+
+#endif /* __TIZEN_HAL_AUDIO_DOC_H__ */
+

diff --git a/doc/images/hal_audio_state_diagram.png b/doc/images/hal_audio_state_diagram.png
new file mode 100644 (file)
index 0000000..6625200
Binary files /dev/null and b/doc/images/hal_audio_state_diagram.png differ

diff --git a/include/hal-audio-interface-1.h b/include/hal-audio-interface-1.h
index 354f954a9e8785c289824b55763da34e5c7de517..137d3f2a5144521842b0b09730e1341b2b7bdb7c 100644 (file)
--- a/include/hal-audio-interface-1.h
+++ b/include/hal-audio-interface-1.h
@@ -26,34 +26,35 @@ extern "C" {
 #endif
 
 /**
- * @file hal-audio.h
+ * @file hal-audio-interface-1.h
  * @brief This file contains the Audio Hardware Abstraction Layer Interfaces.
+ * @since HAL_MODULE_AUDIO 1.0
  */
 
 /**
- * @addtogroup TIZEN_AUDIO_HAL_MODULE
+ * @addtogroup HALAPI_HAL_AUDIO_MODULE
  * @{
  */
 
 /**
  * @brief Enumeration for return codes.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  */
 typedef enum audio_return {
-    AUDIO_RET_OK                        = 0,
-    AUDIO_ERR_UNDEFINED                 = (int32_t)0x80001000,
-    AUDIO_ERR_RESOURCE                  = (int32_t)0x80001001,
-    AUDIO_ERR_PARAMETER                 = (int32_t)0x80001002,
-    AUDIO_ERR_IOCTL                     = (int32_t)0x80001003,
-    AUDIO_ERR_INVALID_STATE             = (int32_t)0x80001004,
-    AUDIO_ERR_INTERNAL                  = (int32_t)0x80001005,
+    AUDIO_RET_OK                        = 0,                        /**< Error none */
+    AUDIO_ERR_UNDEFINED                 = (int32_t)0x80001000,      /**< Undefined error */
+    AUDIO_ERR_RESOURCE                  = (int32_t)0x80001001,      /**< Resource error */
+    AUDIO_ERR_PARAMETER                 = (int32_t)0x80001002,      /**< Invalid parameters */
+    AUDIO_ERR_IOCTL                     = (int32_t)0x80001003,      /**< ioctl error */
+    AUDIO_ERR_INVALID_STATE             = (int32_t)0x80001004,      /**< Invalid state */
+    AUDIO_ERR_INTERNAL                  = (int32_t)0x80001005,      /**< Internal error */
     /* add new enumerator here */
-    AUDIO_ERR_NOT_IMPLEMENTED           = (int32_t)0x80001100,
+    AUDIO_ERR_NOT_IMPLEMENTED           = (int32_t)0x80001100,      /**< Not Implemented */
 } audio_return_e;
 
 /**
  * @brief Enumeration for audio direction.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  */
 typedef enum audio_direction {
     AUDIO_DIRECTION_IN,                 /**< Capture */
@@ -62,131 +63,163 @@ typedef enum audio_direction {
 
 /**
  * @brief Enumeration for audio state.
- * @since_tizen 9.0
+ * @since HAL_MODULE_AUDIO 1.0
  */
 typedef enum audio_state {
-    AUDIO_STATE_OPEN,
-    AUDIO_STATE_SETUP,
-    AUDIO_STATE_PREPARED,
-    AUDIO_STATE_RUNNING,
-    AUDIO_STATE_XRUN,                   /* playback:underrun, capture:overrun */
-    AUDIO_STATE_DRAINING,
-    AUDIO_STATE_PAUSED,
-    AUDIO_STATE_SUSPENDED,
-    AUDIO_STATE_DISCONNECTED,
-    AUDIO_STATE_UNKNOWN,
+    AUDIO_STATE_OPEN,                   /**< Open state */
+    AUDIO_STATE_SETUP,                  /**< Setup state */
+    AUDIO_STATE_PREPARED,               /**< Prepared state */
+    AUDIO_STATE_RUNNING,                /**< Running state */
+    AUDIO_STATE_XRUN,                   /**< Playback:underrun, Capture:overrun */
+    AUDIO_STATE_DRAINING,               /**< Drain state */
+    AUDIO_STATE_PAUSED,                 /**< Pause state */
+    AUDIO_STATE_SUSPENDED,              /**< Suspend state */
+    AUDIO_STATE_DISCONNECTED,           /**< Disconnected state */
+    AUDIO_STATE_UNKNOWN,                /**< Unknown state */
 } audio_state_e;
 
 /**
  * @brief Device information including type, direction and id.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  */
 typedef struct device_info {
-    const char *type;
-    uint32_t direction;
-    uint32_t id;
+    const char *type;                   /**< device type */
+    uint32_t direction;                 /**< playback or capture */
+    uint32_t id;                        /**< device id */
 } device_info_s;
 
 /**
  * @brief Volume information including type, gain and direction.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  */
 typedef struct audio_volume_info {
-    const char *type;
-    const char *gain;
-    uint32_t direction;
+    const char *type;                   /**< volume type */
+    const char *gain;                   /**< volume gain */
+    uint32_t direction;                 /**< playback or capture */
 } audio_volume_info_s;
 
 /**
  * @brief Route information including role and device.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  */
 typedef struct audio_route_info {
-    const char *role;
-    device_info_s *device_infos;
-    uint32_t num_of_devices;
+    const char *role;                   /**< stream role */
+    device_info_s *device_infos;        /**< device info */
+    uint32_t num_of_devices;            /**< number of devices */
 } audio_route_info_s;
 
 /**
  * @brief Route option including role, name and value.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  */
 typedef struct audio_route_option {
-    const char *role;
-    const char *name;
-    int32_t value;
+    const char *role;                   /**< stream role */
+    const char *name;                   /**< key */
+    int32_t value;                      /**< value */
 } audio_route_option_s;
 
 /**
  * @brief Stream information including role, direction and index.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  */
 typedef struct audio_stream_info {
-    const char *role;
-    uint32_t direction;
-    uint32_t idx;
+    const char *role;                   /**< stream role */
+    uint32_t direction;                 /**< playback or capture */
+    uint32_t idx;                       /**< stream index */
 } audio_stream_info_s;
 
 /**
  * @brief Ducking information including target role, duration and ratio.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  */
 typedef struct audio_ducking_info {
-    const char *target_role;
-    uint32_t duration;
-    double ratio;
+    const char *target_role;            /**< ducking target role */
+    uint32_t duration;                  /**< ducking duration */
+    double ratio;                       /**< volume ratio */
 } audio_ducking_info_s;
 
 /**
  * @brief Called when audio hal implementation needs to send a message.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] name The message name
  * @param[in] value The message value
  * @param[in] user_data The user data passed from the callback registration function
  *
- * @see audio_add_message_cb()
- * @see audio_remove_message_cb()
+ * @see add_message_cb()
+ * @see remove_message_cb()
  */
 typedef void (*message_cb)(const char *name, int value, void *user_data);
 
+/**
+ * @brief The structure type of the audio HAL functions.
+ * @since HAL_MODULE_AUDIO 1.0
+ */
 typedef struct _hal_backend_media_audio_funcs {
-    /* Initialization & de-initialization */
+    /**< Initialize HAL backend */
     audio_return_e (*init)(void **audio_handle);
+    /**< Deinitialize HAL backend */
     audio_return_e (*deinit)(void *audio_handle);
-    /* Volume */
+
+    /**< Get volume max level */
     audio_return_e (*get_volume_level_max)(void *audio_handle, audio_volume_info_s *info, uint32_t *level);
+    /**< Get volume level */
     audio_return_e (*get_volume_level)(void *audio_handle, audio_volume_info_s *info, uint32_t *level);
+    /**< Set volume level */
     audio_return_e (*set_volume_level)(void *audio_handle, audio_volume_info_s *info, uint32_t level);
+    /**< Set volume value */
     audio_return_e (*get_volume_value)(void *audio_handle, audio_volume_info_s *info, uint32_t level, double *value);
+    /**< Get volume mute */
     audio_return_e (*get_volume_mute)(void *audio_handle, audio_volume_info_s *info, uint32_t *mute);
+    /**< Set volume mute */
     audio_return_e (*set_volume_mute)(void *audio_handle, audio_volume_info_s *info, uint32_t mute);
+    /**< Set volume ratio */
     audio_return_e (*set_volume_ratio)(void *audio_handle, audio_stream_info_s *info, double ratio);
-    audio_return_e (*notify_ducking_activation_changed)(void *audio_handle, audio_ducking_info_s *info, uint32_t is_activated); /* optional */
-    /* Routing */
+    /**< Notify ducking activation */
+    audio_return_e (*notify_ducking_activation_changed)(void *audio_handle, audio_ducking_info_s *info, uint32_t is_activated);
+
+    /**< Update route */
     audio_return_e (*update_route)(void *audio_handle, audio_route_info_s *info);
+    /**< Update route with option */
     audio_return_e (*update_route_option)(void *audio_handle, audio_route_option_s *option);
-    /* Stream */
+
+    /**< Notify stream connection */
     audio_return_e (*notify_stream_connection_changed)(void *audio_handle, audio_stream_info_s *info, uint32_t is_connected);
-    /* PCM */
+
+    /**< Open device */
     audio_return_e (*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);
+    /**< Start device */
     audio_return_e (*pcm_start)(void *audio_handle, void *pcm_handle);
+    /**< Stop device */
     audio_return_e (*pcm_stop)(void *audio_handle, void *pcm_handle);
+    /**< Close device */
     audio_return_e (*pcm_close)(void *audio_handle, void *pcm_handle);
+    /**< Get available size */
     audio_return_e (*pcm_avail)(void *audio_handle, void *pcm_handle, uint32_t *avail);
+    /**< Write data */
     audio_return_e (*pcm_write)(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames);
+    /**< Read data */
     audio_return_e (*pcm_read)(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames);
+    /**< Get file descriptor */
     audio_return_e (*pcm_get_fd)(void *audio_handle, void *pcm_handle, int *fd);
+    /**< Try recovering device */
     audio_return_e (*pcm_recover)(void *audio_handle, void *pcm_handle, int revents);
+    /**< Get device params */
     audio_return_e (*pcm_get_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t *period_size, uint32_t *periods);
+    /**< Set device params */
     audio_return_e (*pcm_set_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods);
 
+    /**< Get delay and latency both */
     audio_return_e (*pcm_avail_delay)(void *audio_handle, void *pcm_handle, int32_t *avail, int32_t *delay);
+    /**< Start mmap */
     audio_return_e (*pcm_mmap_begin)(void *audio_handle, void *pcm_handle, void **areas, uint32_t *offset, uint32_t *frames, void **ptr);
+    /**< Commit mmap */
     audio_return_e (*pcm_mmap_commit)(void *audio_handle, void *pcm_handle, uint32_t offset, uint32_t frames);
+    /**< Get state */
     audio_return_e (*pcm_get_state)(void *audio_handle, void *pcm_handle, audio_state_e *state);
 
-    /* Message callback */
+    /**< Add message callback */
     audio_return_e (*add_message_cb)(void *audio_handle, message_cb callback, void *user_data);
+    /**< Remove message callback */
     audio_return_e (*remove_message_cb)(void *audio_handle, message_cb callback);
 } hal_backend_audio_funcs;
 

diff --git a/include/hal-audio.h b/include/hal-audio.h
index f09a6063eff78f753a0cc3bdb9db76a8f5dd03ac..6b357870c92e717633ef251503b89e09b856e72d 100644 (file)
--- a/include/hal-audio.h
+++ b/include/hal-audio.h
@@ -25,9 +25,20 @@
 extern "C" {
 #endif
 
+/**
+ * @file hal-audio.h
+ * @brief This file contains the Audio Hardware Abstraction Layer Interfaces.
+ * @since HAL_MODULE_AUDIO 1.0
+ */
+
+/**
+ * @addtogroup HAL_AUDIO_MODULE
+ * @{
+ */
+
 /**
  * @brief Initializes audio hal.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[out] audio_handle The audio hal handle
  *
  * @return @c 0 on success,
@@ -39,7 +50,7 @@ audio_return_e hal_audio_init(void **audio_handle);
 
 /**
  * @brief De-initializes audio hal.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  *
  * @return @c 0 on success,
@@ -51,7 +62,7 @@ audio_return_e hal_audio_deinit(void *audio_handle);
 
 /**
  * @brief Gets the maximum volume level supported for a particular volume information.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The audio volume information
  * @param[out] level The maximum volume level
@@ -67,7 +78,7 @@ audio_return_e hal_audio_get_volume_level_max(void *audio_handle, audio_volume_i
 
 /**
  * @brief Gets the volume level specified for a particular volume information.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The audio volume information
  * @param[out] level The current volume level
@@ -83,7 +94,7 @@ audio_return_e hal_audio_get_volume_level(void *audio_handle, audio_volume_info_
 
 /**
  * @brief Sets the volume level specified for a particular volume information.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The audio volume information
  * @param[in] level The volume level to be set
@@ -99,7 +110,7 @@ audio_return_e hal_audio_set_volume_level(void *audio_handle, audio_volume_info_
 
 /**
  * @brief Gets the volume value specified for a particular volume information and level.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The audio volume information
  * @param[in] level The volume level
@@ -116,7 +127,7 @@ audio_return_e hal_audio_get_volume_value(void *audio_handle, audio_volume_info_
 
 /**
  * @brief Gets the volume mute specified for a particular volume information.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The audio volume information
  * @param[out] mute The volume mute state : (@c 0 = unmute, @c 1 = mute)
@@ -130,7 +141,7 @@ audio_return_e hal_audio_get_volume_mute(void *audio_handle, audio_volume_info_s
 
 /**
  * @brief Sets the volume mute specified for a particular volume information.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The audio volume information
  * @param[in] mute The volume mute state to be set : (@c 0 = unmute, @c 1 = mute)
@@ -144,7 +155,7 @@ audio_return_e hal_audio_set_volume_mute(void *audio_handle, audio_volume_info_s
 
 /**
  * @brief Sets the volume level ratio
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The audio volume information
  * @param[in] ratio
@@ -158,7 +169,7 @@ audio_return_e hal_audio_set_volume_ratio(void *audio_handle, audio_stream_info_
 
 /**
  * @brief Gets notified when a ducking is activated and deactivated. (optional)
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The ducking information including target role, duration and ratio
  * @param[in] is_activated The activation state (@c true = activated, @c false = deactivated)
@@ -173,7 +184,7 @@ audio_return_e hal_audio_notify_ducking_activation_changed(void *audio_handle, a
 
 /**
  * @brief Updates the audio routing according to audio route information.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The audio route information including role and devices
  *
@@ -186,7 +197,7 @@ audio_return_e hal_audio_update_route(void *audio_handle, audio_route_info_s *in
 
 /**
  * @brief Updates audio routing option according to audio route option.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] option The option that can be used for audio routing including role, name and value
  *
@@ -202,7 +213,7 @@ audio_return_e hal_audio_update_route_option(void *audio_handle, audio_route_opt
 
 /**
  * @brief Gets notified when a stream is connected and disconnected.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] info The stream information including role, direction, index
  * @param[in] is_connected The connection state of this stream (@c true = connected, @c false = disconnected)
@@ -217,7 +228,7 @@ audio_return_e hal_audio_notify_stream_connection_changed(void *audio_handle, au
 
 /**
  * @brief Opens a PCM device.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] card The card of PCM
  * @param[in] device The device of PCM
@@ -236,7 +247,7 @@ audio_return_e hal_audio_pcm_open(void *audio_handle, const char *card, const ch
 
 /**
  * @brief Starts a PCM device.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle to be started
  *
@@ -253,7 +264,7 @@ audio_return_e hal_audio_pcm_start(void *audio_handle, void *pcm_handle);
 
 /**
  * @brief Stops a PCM device.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle to be stopped
  *
@@ -266,7 +277,7 @@ audio_return_e hal_audio_pcm_stop(void *audio_handle, void *pcm_handle);
 
 /**
  * @brief Closes a PCM device.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle to be closed
  *
@@ -279,7 +290,7 @@ audio_return_e hal_audio_pcm_close(void *audio_handle, void *pcm_handle);
 
 /**
  * @brief Gets available number of frames.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[out] avail The available number of frames
@@ -294,7 +305,7 @@ audio_return_e hal_audio_pcm_avail(void *audio_handle, void *pcm_handle, uint32_
 
 /**
  * @brief Writes frames to a PCM device.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[in] buffer The buffer containing frames
@@ -310,7 +321,7 @@ audio_return_e hal_audio_pcm_write(void *audio_handle, void *pcm_handle, const v
 
 /**
  * @brief Reads frames from a PCM device.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[out] buffer The buffer containing frames
@@ -326,7 +337,7 @@ audio_return_e hal_audio_pcm_read(void *audio_handle, void *pcm_handle, void *bu
 
 /**
  * @brief Gets poll descriptor for a PCM handle.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[out] fd The poll descriptor
@@ -341,7 +352,7 @@ audio_return_e hal_audio_pcm_get_fd(void *audio_handle, void *pcm_handle, int *f
 
 /**
  * @brief Recovers the PCM state.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[in] revents The returned event from pollfd
@@ -358,7 +369,7 @@ audio_return_e hal_audio_pcm_recover(void *audio_handle, void *pcm_handle, int r
 
 /**
  * @brief Gets parameters of a PCM device.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[in] direction The direction of PCM
@@ -375,7 +386,7 @@ audio_return_e hal_audio_pcm_get_params(void *audio_handle, void *pcm_handle, ui
 
 /**
  * @brief Sets hardware and software parameters of a PCM device.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[in] direction The direction of PCM
@@ -392,7 +403,7 @@ audio_return_e hal_audio_pcm_set_params(void *audio_handle, void *pcm_handle, ui
 
 /**
  * @brief Gets available and delay frames of a PCM device.
- * @since_tizen 9.0
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[out] avail avail frames
@@ -406,7 +417,7 @@ audio_return_e hal_audio_pcm_avail_delay(void *audio_handle, void *pcm_handle, i
 
 /**
  * @brief Gets mmap address of a PCM device.
- * @since_tizen 9.0
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[in] areas mmap address information
@@ -423,7 +434,7 @@ audio_return_e hal_audio_pcm_mmap_begin(void *audio_handle, void *pcm_handle, vo
 
 /**
  * @brief Commits mmap address of a PCM device.
- * @since_tizen 9.0
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[in] offset The offset of memory mapped address
@@ -438,7 +449,7 @@ audio_return_e hal_audio_pcm_mmap_commit(void *audio_handle, void *pcm_handle, u
 
 /**
  * @brief Gets the state of a PCM device.
- * @since_tizen 9.0
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] pcm_handle The PCM handle
  * @param[out] state The state from a pcm handle
@@ -451,7 +462,7 @@ audio_return_e hal_audio_pcm_get_state(void *audio_handle, void *pcm_handle, aud
 
 /**
  * @brief Adds the message callback function.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] message_cb The message callback function
  * @param[in] user_data The user data passed to the callback function
@@ -463,7 +474,7 @@ audio_return_e hal_audio_add_message_cb(void *audio_handle, message_cb callback,
 
 /**
  * @brief Removes the message callback function.
- * @since_tizen 6.5
+ * @since HAL_MODULE_AUDIO 1.0
  * @param[in] audio_handle The audio hal handle
  * @param[in] message_cb The message callback function to be removed
  *
@@ -472,6 +483,10 @@ audio_return_e hal_audio_add_message_cb(void *audio_handle, message_cb callback,
  */
 audio_return_e hal_audio_remove_message_cb(void *audio_handle, message_cb callback);
 
+/**
+ * @}
+ */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/packaging/hal-api-audio.spec b/packaging/hal-api-audio.spec
index 6b1a752e38ec0c0a94b2bf2bcb3a9407c9612b50..ca09205b6ebadc6234e66b89b3f7e3bc21cfcd67 100644 (file)
--- a/packaging/hal-api-audio.spec
+++ b/packaging/hal-api-audio.spec
@@ -1,6 +1,6 @@
 Name:       hal-api-audio
 Summary:    TIZEN Audio HAL
-Version:    0.0.21
+Version:    0.0.22
 Release:    0
 Group:      System/Libraries
 License:    Apache-2.0

diff --git a/testcase/audio_haltests.cpp b/testcase/audio_haltests.cpp
index 80b10c27dd1f910830643fce435860ee5ab2372a..ba8257159a8639c69677893532ef94aa742e6142 100644 (file)
--- a/testcase/audio_haltests.cpp
+++ b/testcase/audio_haltests.cpp
@@ -302,7 +302,7 @@ void AudioHalTest::HalMessageCallback(const char *name, int value, void *user_da
 
 /**
  * @testcase           InitP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -327,7 +327,7 @@ TEST(AudioHalPreTest, InitP)
 
 /**
  * @testcase           InitN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -346,7 +346,7 @@ TEST(AudioHalPreTest, InitN)
 
 /**
  * @testcase           DeinitP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -371,7 +371,7 @@ TEST(AudioHalPreTest, DeinitP)
 
 /**
  * @testcase           GetVolumeLevelMaxP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -399,7 +399,7 @@ TEST_F(AudioHalTest, GetVolumeLevelMaxP)
 
 /**
  * @testcase           GetVolumeLevelMaxN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -421,7 +421,7 @@ TEST_F(AudioHalTest, GetVolumeLevelMaxN)
 
 /**
  * @testcase           GetVolumeLevelP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -450,7 +450,7 @@ TEST_F(AudioHalTest, GetVolumeLevelP)
 
 /**
  * @testcase           GetVolumeLevelN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -472,7 +472,7 @@ TEST_F(AudioHalTest, GetVolumeLevelN)
 
 /**
  * @testcase           SetVolumeLevelP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -500,7 +500,7 @@ TEST_F(AudioHalTest, SetVolumeLevelP)
 
 /**
  * @testcase           SetVolumeLevelN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -523,7 +523,7 @@ TEST_F(AudioHalTest, SetVolumeLevelN)
 
 /**
  * @testcase           GetVolumeValueP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -559,7 +559,7 @@ TEST_F(AudioHalTest, GetVolumeValueP)
 
 /**
  * @testcase           GetVolumeValueN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -581,7 +581,7 @@ TEST_F(AudioHalTest, GetVolumeValueN)
 
 /**
  * @testcase           GetVolumeMuteP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -610,7 +610,7 @@ TEST_F(AudioHalTest, GetVolumeMuteP)
 
 /**
  * @testcase           GetVolumeMuteN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -632,7 +632,7 @@ TEST_F(AudioHalTest, GetVolumeMuteN)
 
 /**
  * @testcase           SetVolumeMuteP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -665,7 +665,7 @@ TEST_F(AudioHalTest, SetVolumeMuteN)
 
 /**
  * @testcase           UpdateRouteP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -691,7 +691,7 @@ TEST_F(AudioHalTest, UpdateRouteP)
 
 /**
  * @testcase           UpdateRouteN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -716,7 +716,7 @@ TEST_F(AudioHalTest, UpdateRouteN)
 
 /**
  * @testcase           UpdateRouteOptionP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -738,7 +738,7 @@ TEST_F(AudioHalTest, UpdateRouteOptionP)
 
 /**
  * @testcase           UpdateRouteOptionN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -757,7 +757,7 @@ TEST_F(AudioHalTest, UpdateRouteOptionN)
 
 /**
  * @testcase           NotifyStreamConnectionChangedP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -780,7 +780,7 @@ TEST_F(AudioHalTest, NotifyStreamConnectionChangedP)
 
 /**
  * @testcase           NotifyStreamConnectionChangedN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -807,7 +807,7 @@ TEST_F(AudioHalTest, NotifyStreamConnectionChangedN)
 
 /**
  * @testcase           MessageCallbackP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -829,7 +829,7 @@ TEST_F(AudioHalTest, MessageCallbackP)
 
 /**
  * @testcase           MessageCallbackN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -852,7 +852,7 @@ TEST_F(AudioHalTest, MessageCallbackN)
 
 /**
  * @testcase           PcmGetFdP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -902,7 +902,7 @@ TEST_F(AudioHalTest, PcmGetFdP)
 
 /**
  * @testcase           PcmGetFdN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -947,7 +947,7 @@ TEST_F(AudioHalTest, PcmGetFdN)
 
 /**
  * @testcase           PcmOpenWriteCloseP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -1002,7 +1002,7 @@ TEST_F(AudioHalTest, PcmOpenWriteCloseP)
 
 /**
  * @testcase           PcmOpenReadCloseP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -1052,7 +1052,7 @@ TEST_F(AudioHalTest, PcmOpenReadCloseP)
 
 /**
  * @testcase           PcmRecoverN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -1071,7 +1071,7 @@ TEST_F(AudioHalTest, PcmRecoverN)
 
 /**
  * @testcase           PcmSetParamP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -1111,7 +1111,7 @@ TEST_F(AudioHalTest, PcmSetParamP)
 
 /**
  * @testcase           PcmSetParamN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -1150,7 +1150,7 @@ TEST_F(AudioHalTest, PcmSetParamN)
 
 /**
  * @testcase           PcmGetParamP
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto
@@ -1201,7 +1201,7 @@ TEST_F(AudioHalTest, PcmGetParamP)
 
 /**
  * @testcase           PcmGetParamN
- * @since_tizen                6.5
+ * @since              HAL_MODULE_AUDIO 1.0
  * @author                     SR(seungbae.shin)
  * @reviewer           SR(sc11.lee, jcsing.lee)
  * @type                       auto