Initialize ACR docs and elaborate descriptions

Add documentation for ACR and added description.

Change-Id: I25ebd6e3de41866551c64078de1f67f3ce8e9235
Signed-off-by: Youngjae Cho <y0.cho@samsung.com>

diff --git a/doc/hal_common_doc.h b/doc/hal_common_doc.h
new file mode 100644 (file)
index 0000000..3224a3e
--- /dev/null
+++ b/doc/hal_common_doc.h
@@ -0,0 +1,116 @@
+/*
+ * Copyright (c) 2025 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_COMMON_DOC_H__
+#define __TIZEN_HAL_COMMON_DOC_H__
+
+/**
+ * @file hal_common_doc.h
+ * @brief This file contains high level documentation of the HAL Common.
+ */
+
+/**
+ * @defgroup HALAPI_HAL_COMMON_MODULE Common
+ * @brief The @ref HALAPI_HAL_COMMON_MODULE is a special module providing functions for implementing other hal modules.
+ *
+ * @section HALAPI_HAL_COMMON_MODULE_HEADER Required Header
+ *   \#include <hal-common.h>
+ *
+ * @section HALAPI_HAL_COMMON_MODULE_OVERVIEW Overview
+ * The Common module is a special HAL module. It encapsulates loading and unloading of the hal backend.
+ * And it provides methods to get metadata of the hal backend such as name, vendor, version.
+ *
+ * The Common module defines common interface #hal_backend that associates platform hal module and hal backend.
+ * On top of the interface #hal_backend, it provides functions for loading and unloading hal backend.
+ * The #hal_common_get_backend family functions internally invoke #hal_backend.init which has been defined and
+ * registered by hal backend provider, and likewise #hal_common_put_backend family function invokes #hal_backend.exit.
+ *
+ * The Common module provides functions to load or unload the HAL backend.
+ * - hal_common_get_backend
+ * - hal_common_put_backend
+ * - hal_common_get_backend_with_library_name
+ * - hal_common_put_backend_with_library_name
+ * - hal_common_get_backend_v2
+ * - hal_common_put_backend_v2
+ * - hal_common_get_backend_with_library_name_v2
+ * - hal_common_put_backend_with_library_name_v2
+ *
+ * @code
+ * #include <hal-common.h>
+ *
+ * static hal_backend_foo_funcs *g_foo_funcs = NULL; // module interface defined by the hal module foo
+ *
+ * int hal_foo_get_backend(void)
+ * {
+ *     int ret;
+ *
+ *     g_foo_funcs = calloc(1, sizeof(hal_backend_foo_funcs));
+ *     if (!g_foo_funcs)
+ *         return -ENOMEM;
+ *
+ *     ret = hal_common_get_backend(HAL_MODULE_FOO, &g_foo_funcs); // calls hal_backend.init(&g_foo_funcs) at the hal backend
+ *     if (ret < 0)
+ *         return -ENOTSUP;
+ *
+ *     return 0;
+ * }
+ *
+ * int hal_foo_put_backend(void)
+ * {
+ *     int ret;
+ *
+ *     ret = hal_common_put_backend(HAL_MODULE_FOO, g_foo_funcs); // calls hal_backend.exit(g_foo_funcs) at the hal backend
+ *     if (ret < 0)
+ *         return ret;
+ *
+ *     free(g_foo_funcs);
+ *     g_foo_funcs = NULL;
+ *
+ *     return 0;
+ * }
+ *
+ * int hal_foo_do_something(int data)
+ * {
+ *     int ret;
+ *
+ *     if (!hal_device_foo_funcs) {
+ *         ret = hal_foo_get_backend();
+ *         if (ret < 0)
+ *             return ret;
+ *     }
+ *
+ *     if (!hal_device_foo_funcs || !hal_device_foo_funcs->do_something)
+ *         return -ENOTSUP;
+ *
+*     return hal_device_foo_funcs->do_something(data);
+ * }
+ * @endcode
+ *
+ * And the Common module provides functions to get metadata of the HAL backend.
+ * - hal_common_get_backend_library_name
+ * - hal_common_get_backend_module_name
+ * - hal_common_get_backend_version
+ * - hal_common_get_backend_name
+ * - hal_common_get_backend_vendor
+ * - hal_common_get_backend_count
+ * - hal_common_get_backend_library_names
+ * - hal_common_check_backend_compatibility
+ * - hal_common_get_supported_interface_versions
+ *
+ * For more information on the Common features and the macros, see HAL Common programming guides and tutorials.
+ */
+
+#endif  /* __TIZEN_HAL_COMMON_DOC_H__ */

diff --git a/include/hal-common-interface.h b/include/hal-common-interface.h
index cb867706e10f58a6c43aebbead21348d40fb2ad8..76b9fcada3a29bcfe34569f849e72a2df0eccd0f 100644 (file)
--- a/include/hal-common-interface.h
+++ b/include/hal-common-interface.h
@@ -23,15 +23,33 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup HALAPI_HAL_COMMON_MODULE
+ * @{
+ */
+
+/**
+ * @brief Structure for HAL module backend.
+ * @since HAL_MODULE_COMMON 1.0
+ */
 typedef struct __hal_backend {
+       /** Name of HAL Backend */
        const char *name;
+       /** Vendor name of HAL Backend */
        const char *vendor;
+       /** Function for initializing HAL Backend */
        int (*init) (void **data);
+       /** Function for deinitializing HAL Backend */
        int (*exit) (void *data);
+       /** Major version of HAL interface */
        const unsigned int major_version;
+       /** Minor version of HAL interface */
        const unsigned int minor_version;
 } hal_backend;
 
+/**
+ * @}
+ */
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/hal-common.h b/include/hal-common.h
index 108d22dac7c9cdfa3f06de19cbfadeb6801c1112..5d6608a646d46a19983768673d6149a47ac9beb7 100644 (file)
--- a/include/hal-common.h
+++ b/include/hal-common.h
@@ -25,6 +25,15 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup HALAPI_HAL_COMMON_MODULE
+ * @{
+ */
+
+/**
+ * @brief Enumeration for representing hal module.
+ */
+
 enum hal_module {
        HAL_MODULE_UNKNOWN = 0,
 
@@ -290,6 +299,9 @@ int hal_common_check_backend_compatibility(enum hal_module module,
 int hal_common_get_supported_interface_versions(enum hal_module module,
        unsigned int **major_versions, unsigned int **minor_versions, int *num_versions);
 
+/**
+ * @}
+ */
 #ifdef __cplusplus
 }
 #endif