- Replace "since_tizen" tag by "since" tag.
- Add some descriptions
Change-Id: I9e4b4e04e74fd33d5c714980b120862e4998325e
--- /dev/null
+/*
+ * HAL (Hardware Abstract Layer) Radio API
+ *
+ * Copyright (c) 2024 Samsung Electronics Co., Ltd.
+ *
+ * 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_RADIO_DOC_H__
+#define __TIZEN_HAL_RADIO_DOC_H__
+
+/**
+ * @file hal_radio_doc.h
+ * @brief This file contains documentation for HAL (Hardware Abstract Layer) Radio API.
+ */
+
+/**
+ * @defgroup HALAPI_HAL_RADIO_MODULE Radio
+ * @brief The @ref HALAPI_HAL_RADIO_MODULE provides functions for radio devices.
+ *
+ * @section HALAPI_HAL_RADIO_MODULE_HEADER Required Header
+ * \#include <hal-radio.h>
+ * The radio devices have various specifications, so it's hard to control them using single code.
+ * The radio HAL provides common abstraction interfaces to control radio devices which are different.
+ *
+ * The radio HAL allows creation of components required in listening to the radio including:
+ * - Starting radio devices (initializing, preparing, opening and closing)
+ * - Finding radio station (seeking up/down)
+ * - Setting/Getting the radio frequencies
+ * - Getting radio signal strength
+ *
+ * @subsection HALAPI_HAL_radio_MODULE_STATE_DIAGRAM State Diagram
+ * @image html hal_radio_state_diagram.png
+ *
+ * @subsection HALAPI_HAL_RADIO_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_radio_init() </td>
+ * <td> N/A </td>
+ * <td> INITIALIZED </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_deinit() </td>
+ * <td> INITIALIZED </td>
+ * <td> N/A </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_prepare() </td>
+ * <td> INITIALIZED </td>
+ * <td> PREPARED </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_unprepare() </td>
+ * <td> PREPARED </td>
+ * <td> INITIALIZED </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_open() </td>
+ * <td> PREPARED </td>
+ * <td> OPENED </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_close() </td>
+ * <td> OPENED </td>
+ * <td> PREPARED </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_start() </td>
+ * <td> OPENED </td>
+ * <td> PLAYING </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_stop() </td>
+ * <td> PLAYING </td>
+ * <td> OPENED </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_seek() </td>
+ * <td> PLAYING </td>
+ * <td> PLAYING </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_seek() </td>
+ * <td> PLAYING </td>
+ * <td> PLAYING </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_set_frequency() </td>
+ * <td> PLAYING </td>
+ * <td> PLAYING </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_get_frequency() </td>
+ * <td> PLAYING </td>
+ * <td> PLAYING </td>
+ * <td> SYNC </td>
+ * </tr>
+ * <tr>
+ * <td> hal_radio_get_signal_strength() </td>
+ * <td> PLAYING </td>
+ * <td> PLAYING </td>
+ * <td> SYNC </td>
+ * </tr>
+ * </table></div>
+ *
+ * For more information on the radio features and the macros, see HAL radio programming guides and tutorials.
+ */
+
+#endif __TIZEN_HAL_RADIO_DOC_H__
\ No newline at end of file
/*
* HAL (Hardware Abstract Layer) Radio API
*
- * Copyright (c) 2021 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2024 Samsung Electronics Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the License);
* you may not use this file except in compliance with the License.
* limitations under the License.
*/
-#ifndef __HAL_RADIO_INTERFACE_1__
-#define __HAL_RADIO_INTERFACE_1__
+#ifndef __TIZEN_HAL_RADIO_INTERFACE_1__
+#define __TIZEN_HAL_RADIO_INTERFACE_1__
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
+/**
+ * @file hal-radio-interface-1.h
+ * @brief This file contains the Tizen radio HAL interface API, related structures and enumerations.
+ * @since HAL_MODULE_RADIO 1.0
+ */
+
+/**
+ * @addtogroup HALAPI_HAL_RADIO_MODULE
+ * @{
+ */
+
/**
* @brief Enumeration for the radio error.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
*/
typedef enum hal_radio_error {
- HAL_RADIO_ERROR_NONE,
- HAL_RADIO_ERROR_INVALID_PARAMETER,
- HAL_RADIO_ERROR_INVALID_OPERATION,
- HAL_RADIO_ERROR_PERMISSION_DENIED,
- HAL_RADIO_ERROR_NOT_SUPPORTED,
- HAL_RADIO_ERROR_OUT_OF_MEMORY,
- HAL_RADIO_ERROR_DEVICE_NOT_PREPARED,
- HAL_RADIO_ERROR_DEVICE_NOT_OPENED,
- HAL_RADIO_ERROR_DEVICE_NOT_FOUND,
- HAL_RADIO_ERROR_NO_ANTENNA,
- HAL_RADIO_ERROR_INTERNAL,
- HAL_RADIO_ERROR_NOT_IMPLEMENTED,
- HAL_RADIO_ERROR_UNKNOWN
+ HAL_RADIO_ERROR_NONE, /**< Error none */
+ HAL_RADIO_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
+ HAL_RADIO_ERROR_INVALID_OPERATION, /**< Invalid operation */
+ HAL_RADIO_ERROR_PERMISSION_DENIED, /**< Permission denied */
+ HAL_RADIO_ERROR_NOT_SUPPORTED, /**< Not supported */
+ HAL_RADIO_ERROR_OUT_OF_MEMORY, /**< Out of memory */
+ HAL_RADIO_ERROR_DEVICE_NOT_PREPARED, /**< Device is not prepared */
+ HAL_RADIO_ERROR_DEVICE_NOT_OPENED, /**< Device is not opened */
+ HAL_RADIO_ERROR_DEVICE_NOT_FOUND, /**< Device not found */
+ HAL_RADIO_ERROR_NO_ANTENNA, /**< No antenna error */
+ HAL_RADIO_ERROR_INTERNAL, /**< Internal error */
+ HAL_RADIO_ERROR_NOT_IMPLEMENTED, /**< Not implemented */
+ HAL_RADIO_ERROR_UNKNOWN /**< Unknown */
} hal_radio_error_t;
/**
* @brief Enumeration for the radio seek direction.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
*/
typedef enum hal_radio_seek_direction_type {
- RADIO_SEEK_DIRECTION_UP, /**< Seek upward */
- RADIO_SEEK_DIRECTION_DOWN, /**< Seek downward */
- RADIO_SEEK_NUM
+ RADIO_SEEK_DIRECTION_UP, /**< Seek upward */
+ RADIO_SEEK_DIRECTION_DOWN /**< Seek downward */
} hal_radio_seek_direction_type_t;
+/**
+ * @brief The structure type of the radio HAL functions.
+ * @since HAL_MODULE_RADIO 1.0
+ */
typedef struct _hal_backend_radio_funcs {
+ /**< Initialize HAL backend handle */
hal_radio_error_t (*init)(void **radio_handle);
+ /**< Initialize HAL backend handle */
hal_radio_error_t (*deinit)(void *radio_handle);
+ /**< Prepare the device of radio */
hal_radio_error_t (*prepare)(void *radio_handle);
+ /**< Unprepare the device of radio */
hal_radio_error_t (*unprepare)(void *radio_handle);
+ /**< Opens the device of radio */
hal_radio_error_t (*open)(void *radio_handle);
+ /**< Closes the device of radio */
hal_radio_error_t (*close)(void *radio_handle);
+ /**< Starts the device of radio */
hal_radio_error_t (*start)(void *radio_handle);
+ /**< Stops the device of radio */
hal_radio_error_t (*stop)(void *radio_handle);
+ /**< Seeks (up or down) the effective frequency of the radio */
hal_radio_error_t (*seek)(void *radio_handle, hal_radio_seek_direction_type_t direction);
+ /**< Gets the radio frequency (khz) */
hal_radio_error_t (*get_frequency)(void *radio_handle, uint32_t *frequency);
+ /**< Sets the radio frequency (khz) */
hal_radio_error_t (*set_frequency)(void *radio_handle, uint32_t frequency);
+ /**< Gets the current signal strength of the radio (dBm) */
hal_radio_error_t (*get_signal_strength)(void *radio_handle, int32_t *strength);
} hal_backend_radio_funcs;
+/**
+ * @}
+ */
+
#ifdef __cplusplus
}
#endif
-#endif /* __HAL_RADIO_INTERFACE_1__ */
+#endif /* __TIZEN_HAL_RADIO_INTERFACE_1__ */
/**
* @brief Initializes new handle of radio HAL.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[out] hal_radio_handle A newly returned the radio HAL handle
* @return @c 0 on success, otherwise a negative error value
* @retval #HAL_RADIO_ERROR_NONE Successful
/**
* @brief Deinitializes handle of radio HAL.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @return @c 0 on success, otherwise a negative error value
* @retval #HAL_RADIO_ERROR_NONE Successful
/**
* @brief Prepare the device of radio.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @return @c 0 on success, otherwise a negative error value
* @retval #HAL_RADIO_ERROR_NONE Successful
/**
* @brief Unprepare the device of radio.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @return @c 0 on success, otherwise a negative error value
* @retval #HAL_RADIO_ERROR_NONE Successful
/**
* @brief Opens the device of radio.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @return @c 0 on success, otherwise a negative error value
* @retval #HAL_RADIO_ERROR_NONE Successful
/**
* @brief Closes the device of radio.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @return @c 0 on success, otherwise a negative error value
* @retval #HAL_RADIO_ERROR_NONE Successful
/**
* @brief Starts the device of radio.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @return @c 0 on success, otherwise a negative error value
* @retval #HAL_RADIO_ERROR_NONE Successful
/**
* @brief Stops the device of radio.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @return @c 0 on success, otherwise a negative error value
* @retval #HAL_RADIO_ERROR_NONE Successful
/**
* @brief Seeks (up or down) the effective frequency of the radio.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @param[in] direction The seek direction type (up or down)
* @return @c 0 on success, otherwise a negative error value
/**
* @brief Gets the radio frequency.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @param[out] frequency The current frequency (khz)
* @return @c 0 on success, otherwise a negative error value
/**
* @brief Sets the radio frequency.
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @param[in] frequency The frequency to set (khz)
* @return @c 0 on success, otherwise a negative error value
/**
* @brief Gets the current signal strength of the radio
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @param[in] hal_radio_handle The radio HAL handle
* @param[out] strength The current signal strength (dBm)
* @return @c 0 on success, otherwise a negative error value
/**
* @testcase GetPutBackendP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase InitP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase DeinitP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase PrepareDeviceP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase PrepareDeviceN
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase UnprepareDeviceP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase UnprepareDeviceN
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase OpenDeviceP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase OpenDeviceN
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase CloseDeviceP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase CloseDeviceN
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase StartP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase StartN1
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase StartN2
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase StopP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase StopN1
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase StopN2
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase SetFrequencyP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase SetFrequencyN
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase GetFrequencyP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
* @description Positive, Gets radio frequency
* @apicovered hal_radio_prepare, hal_radio_open, hal_radio_start, hal_radio_stop, hal_radio_set_frequency, hal_radio_get_frequency
- * @passcase when hal_radio_get_frequency returns HAL_RADIO_ERROR_NONE and result is same with previous set frequecny
+ * @passcase when hal_radio_get_frequency returns HAL_RADIO_ERROR_NONE and result is same with previous set frequency
* @failcase when hal_radio_get_frequency does not return HAL_RADIO_ERROR_NONE
* @precondition None
* @postcondition None
/**
* @testcase GetFrequencyN
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase SeekUpP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase SeekUpP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase SeekN1
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase SeekN2
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase GetSignalStrengthP
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto
/**
* @testcase GetSignalStrengthN
- * @since_tizen 6.5
+ * @since HAL_MODULE_RADIO 1.0
* @author SR(gilbok.lee)
* @reviewer SR(eunhae1.choi)
* @type auto