hal_power_doc: Update overview of HAL power API

Update the HAL power API overview in the documentation for HAL ACR.

Change-Id: I973cd0513438252cdac6352237339e713ef2598c
Signed-off-by: Unsung Lee <unsung.lee@samsung.com>

diff --git a/doc/hal_power_doc.h b/doc/hal_power_doc.h
new file mode 100644 (file)
index 0000000..961c7d5
--- /dev/null
+++ b/doc/hal_power_doc.h
@@ -0,0 +1,95 @@
+/*
+ * 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_POWER_DOC_H__
+#define __TIZEN_HAL_POWER_DOC_H__
+
+
+/**
+ * @file hal_power_doc.h
+ * @brief This file contains high level documentation of the HAL Power.
+ */
+
+/**
+ * @defgroup HALAPI_HAL_POWER_MODULE Power
+ * @brief The @ref CAPI_HAL_POWER_MODULE provides functions for getting and setting hardware information.
+ *
+ * @section HALAPI_HAL_POWER_MODULE_HEADER Required Header
+ *   \#include <hal-power.h>
+ *
+ * @section HALAPI_HAL_POWER_MODULE_OVERVIEW Overview
+ * The Power provides functions to get and set hardware information.
+ *
+ * The type of hardware information includes:
+ * - DVFS (Dynamic Voltage Frequency Scaling)
+ * - CPU Hotplug
+ * - Thermal
+ * - Memory
+ *
+ * The hardware operations provided by DVFS involve getting or setting information related to CPU frequency. \n
+ * This information includes governor, available governor, current frequency, minimum/maximum frequency, available minimum/maximum frequency, up threshold, and load table.
+ *
+ * The Power functions of DVFS includes:
+ * - hal_power_dvfs_get_curr_governor
+ * - hal_power_dvfs_set_curr_governor
+ * - hal_power_dvfs_get_avail_governor
+ * - hal_power_dvfs_get_curr_freq
+ * - hal_power_dvfs_get_min_freq
+ * - hal_power_dvfs_set_min_freq
+ * - hal_power_dvfs_get_max_freq
+ * - hal_power_dvfs_set_max_freq
+ * - hal_power_dvfs_get_available_min_freq
+ * - hal_power_dvfs_get_available_max_freq
+ * - hal_power_dvfs_get_up_threshold
+ * - hal_power_dvfs_set_up_threshold
+ * - hal_power_dvfs_get_load_table
+ *
+ * The hardware operations provided by CPU hotplug involve getting or setting information related to online CPU. \n
+ * This information includes online CPU list and the number of minimum/maximun online CPU.
+ *
+ * The Power functions of CPU hotplug includes:
+ * - hal_power_hotplug_get_online_state
+ * - hal_power_hotplug_set_online_state
+ * - hal_power_hotplug_get_online_min_num
+ * - hal_power_hotplug_set_online_min_num
+ * - hal_power_hotplug_get_online_max_num
+ * - hal_power_hotplug_set_online_max_num
+ *
+ * The hardware operations provided by thermal involve getting or setting information related to temperature, cooling device, and battery. \n
+ * This information includes current temperature, policy of thermal management unit, state and maximum state of thermal cooling device, and state of battery charging and current.
+ *
+ * The Power functions of thermal includes:
+ * - hal_power_thermal_get_temp
+ * - hal_power_thermal_get_policy
+ * - hal_power_thermal_set_cooling_device_state
+ * - hal_power_thermal_get_cooling_device_state
+ * - hal_power_thermal_get_cooling_device_max_state
+ * - hal_power_battery_set_charging_status
+ * - hal_power_battery_get_charging_status
+ * - hal_power_battery_set_charging_current
+ * - hal_power_battery_get_charging_current
+ *
+ * The hardware operations provided by memory involve getting or setting information related to fault around bytes. \n
+ * This information includes the number of bytes read in after a page fault.
+ *
+ * The Power functions of memory includes:
+ * - hal_power_memory_get_fault_around_bytes
+ * - hal_power_memory_set_fault_around_bytes
+ *
+ * For more information on the Power features and the macros, see HAL Power programming guides and tutorials.
+ */
+
+#endif /* __TIZEN_HAL_POWER_DOC_H__ */

diff --git a/include/hal-power-interface-1.h b/include/hal-power-interface-1.h
index 072f727db204edb76168713096fda6be82bbbe28..5f3a295f0cb83ef2316e168fbe12df5a5bc703ee 100644 (file)
--- a/include/hal-power-interface-1.h
+++ b/include/hal-power-interface-1.h
@@ -25,6 +25,16 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup HALAPI_HAL_POWER_MODULE
+ * @{
+ */
+
+/**
+ * @brief Structure for power functions.
+ * @since HAL_MODULE_POWER 1.0
+ */
+
 /*
  * Define the ops (operations) structure which are used on specific resource.
  */
@@ -188,6 +198,10 @@ typedef struct _hal_backend_power_funcs {
        struct pass_resource_nonstandard *nonstandard;
 } hal_backend_power_funcs;
 
+/**
+ * @}
+ */
+
 #ifdef __cplusplus
 }
 #endif