From 6481633ec641620dcf98e0f3255cfc8f61fd818d Mon Sep 17 00:00:00 2001 From: wumingzi <62127946+1078249029@users.noreply.github.com> Date: Mon, 27 Jan 2025 15:54:13 +0800 Subject: [doxygen] add doxygen comment for clk.c and clk.h (#9950) Accroding to #9947 and #9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <1078249029@qq.com> --- components/drivers/include/drivers/clk.h | 62 ++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 18 deletions(-) (limited to 'components/drivers/include') diff --git a/components/drivers/include/drivers/clk.h b/components/drivers/include/drivers/clk.h index 97491bf8be..9ecf4c3bdf 100644 --- a/components/drivers/include/drivers/clk.h +++ b/components/drivers/include/drivers/clk.h @@ -1,11 +1,12 @@ /* - * Copyright (c) 2006-2022, RT-Thread Development Team + * Copyright (c) 2006-2025 RT-Thread Development Team * * SPDX-License-Identifier: Apache-2.0 * * Change Logs: * Date Author Notes * 2022-11-26 GuEe-GUI first version + * 2025-01-24 wumingzi add doxygen comment */ #ifndef __CLK_H__ @@ -16,29 +17,40 @@ #include #include +/** + * @addtogroup Drivers RTTHREAD Driver + * @defgroup clk clk + * @brief clk driver api + * @ingroup Drivers + * @addtogroup clk + * @{ + */ + #define RT_CLK_NODE_OBJ_NAME "CLKNP" struct rt_clk_ops; struct rt_reset_control_node; +/** + * @brief Clk node, it is a pat of clk source or controller + * @note Defined as the array like this if the CLK have multi out clocks: + * @code{.c} + * struct XYZ_single_clk + * { + * struct rt_clk_node parent; + * ... + * }; + * + * struct XYZ_multi_clk + * { + * struct rt_clk_node parent[N]; + * ... + * }; + * @endcode + * We assume the 'N' is the max value of element in 'clock-indices' if OFW. + */ struct rt_clk_node { - /* - * Defined as the array like this if if the CLK have multi out clocks: - * - * struct XYZ_single_clk - * { - * struct rt_clk_node parent; - * ... - * }; - * - * struct XYZ_multi_clk - * { - * struct rt_clk_node parent[N]; - * ... - * }; - * We assume the 'N' is the max value of element in 'clock-indices' if OFW. - */ struct rt_object rt_parent; rt_list_t list; @@ -62,6 +74,9 @@ struct rt_clk_node rt_size_t multi_clk; }; +/** + * @brief Constant rate clk + */ struct rt_clk_fixed_rate { struct rt_clk_node clk; @@ -70,6 +85,9 @@ struct rt_clk_fixed_rate rt_ubase_t fixed_accuracy; }; +/** + * @brief Clk object, it can be clk source or controller + */ struct rt_clk { struct rt_clk_node *clk_np; @@ -85,6 +103,9 @@ struct rt_clk void *priv; }; +/** + * @brief Clk array + */ struct rt_clk_array { rt_size_t count; @@ -118,6 +139,9 @@ struct rt_clk_notifier; typedef rt_err_t (*rt_clk_notifier_callback)(struct rt_clk_notifier *notifier, rt_ubase_t msg, rt_ubase_t old_rate, rt_ubase_t new_rate); +/** + * @brief Clock notifier, it containers of clock list and callback function + */ struct rt_clk_notifier { rt_list_t list; @@ -192,4 +216,6 @@ rt_inline rt_ssize_t rt_ofw_count_of_clk(struct rt_ofw_node *clk_ofw_np) } #endif /* RT_USING_OFW */ -#endif /* __CLK_H__ */ +/*! @}*/ + +#endif /* __CLK_H__ */ \ No newline at end of file -- cgit v1.3.1