From: Gilbok Lee Date: Wed, 4 Dec 2024 04:26:43 +0000 (+0900) Subject: Update header and add "doc" directory for documentation X-Git-Tag: accepted/tizen/9.0/unified/20250116.154248~3 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=97a9da03253e867c92d24bc49a2aa2790e016eb8;p=platform%2Fhal%2Fapi%2Fradio.git Update header and add "doc" directory for documentation - Replace "since_tizen" tag by "since" tag. - Add some descriptions Change-Id: I9e4b4e04e74fd33d5c714980b120862e4998325e --- diff --git a/doc/hal_radio_doc.h b/doc/hal_radio_doc.h new file mode 100644 index 0000000..5ecaac2 --- /dev/null +++ b/doc/hal_radio_doc.h @@ -0,0 +1,136 @@ +/* + * 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 + * 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 + *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
FUNCTIONPRE-STATEPOST-STATESYNC TYPE
hal_radio_init() N/A INITIALIZED SYNC
hal_radio_deinit() INITIALIZED N/A SYNC
hal_radio_prepare() INITIALIZED PREPARED SYNC
hal_radio_unprepare() PREPARED INITIALIZED SYNC
hal_radio_open() PREPARED OPENED SYNC
hal_radio_close() OPENED PREPARED SYNC
hal_radio_start() OPENED PLAYING SYNC
hal_radio_stop() PLAYING OPENED SYNC
hal_radio_seek() PLAYING PLAYING SYNC
hal_radio_seek() PLAYING PLAYING SYNC
hal_radio_set_frequency() PLAYING PLAYING SYNC
hal_radio_get_frequency() PLAYING PLAYING SYNC
hal_radio_get_signal_strength() PLAYING PLAYING SYNC
+ * + * 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 diff --git a/doc/images/hal_radio_state_diagram.png b/doc/images/hal_radio_state_diagram.png new file mode 100644 index 0000000..eade66f Binary files /dev/null and b/doc/images/hal_radio_state_diagram.png differ diff --git a/include/hal-radio-interface-1.h b/include/hal-radio-interface-1.h index eee1318..8c59d21 100644 --- a/include/hal-radio-interface-1.h +++ b/include/hal-radio-interface-1.h @@ -1,7 +1,7 @@ /* * 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. @@ -16,60 +16,90 @@ * 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 #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__ */ diff --git a/include/hal-radio.h b/include/hal-radio.h index ee6aa33..1e6fee6 100644 --- a/include/hal-radio.h +++ b/include/hal-radio.h @@ -31,7 +31,7 @@ hal_radio_error_t hal_radio_put_backend(void *hal_radio_handle); /** * @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 @@ -44,7 +44,7 @@ hal_radio_error_t hal_radio_init(void *hal_radio_handle); /** * @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 @@ -55,7 +55,7 @@ hal_radio_error_t hal_radio_deinit(void *hal_radio_handle); /** * @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 @@ -67,7 +67,7 @@ hal_radio_error_t hal_radio_prepare(void *hal_radio_handle); /** * @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 @@ -79,7 +79,7 @@ hal_radio_error_t hal_radio_unprepare(void *hal_radio_handle); /** * @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 @@ -94,7 +94,7 @@ hal_radio_error_t hal_radio_open(void *hal_radio_handle); /** * @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 @@ -107,7 +107,7 @@ hal_radio_error_t hal_radio_close(void *hal_radio_handle); /** * @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 @@ -119,7 +119,7 @@ hal_radio_error_t hal_radio_start(void *hal_radio_handle); /** * @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 @@ -131,7 +131,7 @@ hal_radio_error_t hal_radio_stop(void *hal_radio_handle); /** * @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 @@ -144,7 +144,7 @@ hal_radio_error_t hal_radio_seek(void *hal_radio_handle, hal_radio_seek_directio /** * @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 @@ -156,7 +156,7 @@ hal_radio_error_t hal_radio_get_frequency(void *hal_radio_handle, uint32_t *freq /** * @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 @@ -168,7 +168,7 @@ hal_radio_error_t hal_radio_set_frequency(void *hal_radio_handle, uint32_t frequ /** * @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 diff --git a/tests/radio_hal_test.cpp b/tests/radio_hal_test.cpp index 28cd1ae..3457353 100644 --- a/tests/radio_hal_test.cpp +++ b/tests/radio_hal_test.cpp @@ -82,7 +82,7 @@ class RadioHalTest : public testing::Test /** * @testcase GetPutBackendP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -111,7 +111,7 @@ TEST_F(RadioHalTest, GetPutBackendP) /** * @testcase InitP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -143,7 +143,7 @@ TEST_F(RadioHalTest, InitP) /** * @testcase DeinitP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -177,7 +177,7 @@ TEST_F(RadioHalTest, DeinitP) /** * @testcase PrepareDeviceP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -203,7 +203,7 @@ TEST_F(RadioHalTest, PrepareDeviceP) /** * @testcase PrepareDeviceN - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -227,7 +227,7 @@ TEST_F(RadioHalTest, PrepareDeviceN) /** * @testcase UnprepareDeviceP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -254,7 +254,7 @@ TEST_F(RadioHalTest, UnprepareDeviceP) /** * @testcase UnprepareDeviceN - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -283,7 +283,7 @@ TEST_F(RadioHalTest, UnprepareDeviceN) /** * @testcase OpenDeviceP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -313,7 +313,7 @@ TEST_F(RadioHalTest, OpenDeviceP) /** * @testcase OpenDeviceN - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -342,7 +342,7 @@ TEST_F(RadioHalTest, OpenDeviceN) /** * @testcase CloseDeviceP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -374,7 +374,7 @@ TEST_F(RadioHalTest, CloseDeviceP) /** * @testcase CloseDeviceN - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -408,7 +408,7 @@ TEST_F(RadioHalTest, CloseDeviceN) /** * @testcase StartP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -444,7 +444,7 @@ TEST_F(RadioHalTest, StartP) /** * @testcase StartN1 - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -478,7 +478,7 @@ TEST_F(RadioHalTest, StartN1) /** * @testcase StartN2 - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -502,7 +502,7 @@ TEST_F(RadioHalTest, StartN2) /** * @testcase StopP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -539,7 +539,7 @@ TEST_F(RadioHalTest, StopP) /** * @testcase StopN1 - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -578,7 +578,7 @@ TEST_F(RadioHalTest, StopN1) /** * @testcase StopN2 - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -602,7 +602,7 @@ TEST_F(RadioHalTest, StopN2) /** * @testcase SetFrequencyP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -642,7 +642,7 @@ TEST_F(RadioHalTest, SetFrequencyP) /** * @testcase SetFrequencyN - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -682,13 +682,13 @@ TEST_F(RadioHalTest, SetFrequencyN) /** * @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 @@ -727,7 +727,7 @@ TEST_F(RadioHalTest, GetFrequencyP) /** * @testcase GetFrequencyN - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -766,7 +766,7 @@ TEST_F(RadioHalTest, GetFrequencyN) /** * @testcase SeekUpP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -809,7 +809,7 @@ TEST_F(RadioHalTest, SeekUpP) /** * @testcase SeekUpP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -852,7 +852,7 @@ TEST_F(RadioHalTest, SeekDownP) /** * @testcase SeekN1 - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -891,7 +891,7 @@ TEST_F(RadioHalTest, SeekN1) /** * @testcase SeekN2 - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -915,7 +915,7 @@ TEST_F(RadioHalTest, SeekN2) /** * @testcase GetSignalStrengthP - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto @@ -955,7 +955,7 @@ TEST_F(RadioHalTest, GetSignalStrengthP) /** * @testcase GetSignalStrengthN - * @since_tizen 6.5 + * @since HAL_MODULE_RADIO 1.0 * @author SR(gilbok.lee) * @reviewer SR(eunhae1.choi) * @type auto