diff --git a/components/drivers/cputime/cputime.c b/components/drivers/cputime/cputime.c index 42298ea98c1..21342d666f5 100644 --- a/components/drivers/cputime/cputime.c +++ b/components/drivers/cputime/cputime.c @@ -1,24 +1,34 @@ /* - * Copyright (c) 2006-2023, RT-Thread Development Team + * Copyright (c) 2006-2025 RT-Thread Development Team * * SPDX-License-Identifier: Apache-2.0 * * Change Logs: * Date Author Notes * 2017-12-23 Bernard first version + * 2025-01-30 wumingzi transform to doxygen comment */ #include #include #include +/** + * @addtogroup Drivers RTTHREAD Driver + * @defgroup cputimer cputimer + * @brief cputimer driver api + * @ingroup Drivers + * @addtogroup cputimer + * @{ + */ + static const struct rt_clock_cputime_ops *_cputime_ops = RT_NULL; /** - * The clock_cpu_getres() function shall return the resolution of CPU time, the + * @brief The clock_cpu_getres() function shall return the resolution of CPU time, the * number of nanosecond per tick. * - * @return the number of nanosecond per tick(x (1000UL * 1000)) + * @return the number of nanosecond per tick(x (1000UL * 1000)) */ uint64_t clock_cpu_getres(void) { @@ -30,9 +40,9 @@ uint64_t clock_cpu_getres(void) } /** - * The clock_cpu_gettime() function shall return the current value of cpu time tick. + * @brief The clock_cpu_gettime() function shall return the current value of cpu time tick. * - * @return the cpu tick + * @return the cpu tick */ uint64_t clock_cpu_gettime(void) { @@ -44,13 +54,14 @@ uint64_t clock_cpu_gettime(void) } /** - * The clock_cpu_settimeout() fucntion set timeout time and timeout callback function + * @brief The clock_cpu_settimeout() fucntion set timeout time and timeout callback function * The timeout callback function will be called when the timeout time is reached * * @param tick the Timeout tick * @param timeout the Timeout function - * @param parameter the Parameters of timeout function + * @param param the Parameters of timeout function * + * @return RT_FALSE or RT_TURE */ int clock_cpu_settimeout(uint64_t tick, void (*timeout)(void *param), void *param) { @@ -61,6 +72,11 @@ int clock_cpu_settimeout(uint64_t tick, void (*timeout)(void *param), void *para return 0; } +/** + * @brief Check if cputimer timeout callback function has been set + * + * @return RT_FALSE or RT_TURE + */ int clock_cpu_issettimeout(void) { if (_cputime_ops) @@ -69,12 +85,12 @@ int clock_cpu_issettimeout(void) } /** - * The clock_cpu_microsecond() fucntion shall return the microsecond according to + * @brief The clock_cpu_microsecond() fucntion shall return the microsecond according to * cpu_tick parameter. * * @param cpu_tick the cpu tick * - * @return the microsecond + * @return the microseconds */ uint64_t clock_cpu_microsecond(uint64_t cpu_tick) { @@ -84,12 +100,12 @@ uint64_t clock_cpu_microsecond(uint64_t cpu_tick) } /** - * The clock_cpu_microsecond() fucntion shall return the millisecond according to + * @brief The clock_cpu_millisecond() fucntion shall return the millisecond according to * cpu_tick parameter. * * @param cpu_tick the cpu tick * - * @return the millisecond + * @return the milliseconds */ uint64_t clock_cpu_millisecond(uint64_t cpu_tick) { @@ -99,9 +115,9 @@ uint64_t clock_cpu_millisecond(uint64_t cpu_tick) } /** - * The clock_cpu_seops() function shall set the ops of cpu time. + * @brief The clock_cpu_seops() function shall set the ops of cpu time. * - * @return always return 0. + * @return always return 0. */ int clock_cpu_setops(const struct rt_clock_cputime_ops *ops) { @@ -114,3 +130,4 @@ int clock_cpu_setops(const struct rt_clock_cputime_ops *ops) return 0; } +/*! @}*/ \ No newline at end of file diff --git a/components/drivers/cputime/cputime_cortexm.c b/components/drivers/cputime/cputime_cortexm.c index 100910a9f9f..4bd28c6c0e0 100644 --- a/components/drivers/cputime/cputime_cortexm.c +++ b/components/drivers/cputime/cputime_cortexm.c @@ -1,5 +1,5 @@ /* - * Copyright (c) 2006-2023, RT-Thread Development Team + * Copyright (c) 2006-2025 RT-Thread Development Team * * SPDX-License-Identifier: Apache-2.0 * @@ -18,7 +18,11 @@ #include #endif -/* Use Cycle counter of Data Watchpoint and Trace Register for CPU time */ +/** + * @brief Get nanoseconds per tick + * + * @return the number of nanoseconds per tick multiplied by 1 000 000 + */ static uint64_t cortexm_cputime_getres(void) { uint64_t ret = 1000UL * 1000 * 1000; @@ -27,6 +31,11 @@ static uint64_t cortexm_cputime_getres(void) return ret; } +/** + * @brief Read time counter + * + * @return value of ticks + */ static uint64_t cortexm_cputime_gettime(void) { #ifdef PKG_USING_PERF_COUNTER @@ -42,7 +51,12 @@ const static struct rt_clock_cputime_ops _cortexm_ops = cortexm_cputime_gettime }; - +/** + * @brief Init cputimer operation of cortex-m architecture by using Cycle + counter of Data Watchpoint and Trace Register for CPU time + * + * @return return 0 forever + */ int cortexm_cputime_init(void) { #ifdef PKG_USING_PERF_COUNTER @@ -66,4 +80,4 @@ int cortexm_cputime_init(void) #endif /* PKG_USING_PERF_COUNTER */ return 0; } -INIT_BOARD_EXPORT(cortexm_cputime_init); +INIT_BOARD_EXPORT(cortexm_cputime_init); \ No newline at end of file diff --git a/components/drivers/cputime/cputime_riscv.c b/components/drivers/cputime/cputime_riscv.c index 597157c226e..7b3f61a84ea 100644 --- a/components/drivers/cputime/cputime_riscv.c +++ b/components/drivers/cputime/cputime_riscv.c @@ -1,11 +1,35 @@ +/* + * Copyright (c) 2006-2025 RT-Thread Development Team + * + * SPDX-License-Identifier: Apache-2.0 + * + * Change Logs: + * Date Author Notes + * 2022-11-23 Guozhanxin first version + * 2023-04-12 xqyjlj fix cpu timer in multithreading + * 2025-01-30 wumingzi add doxygen comment + */ + #include #include #include #include -/* Use Cycle counter of Data Watchpoint and Trace Register for CPU time */ +/** + * @addtogroup Drivers RTTHREAD Driver + * @defgroup cputimer cputimer + * @brief cputimer driver api + * @ingroup Drivers + * @addtogroup cputimer + * @{ + */ +/** + * @brief Get nanoseconds per tick + * + * @return the number of nanoseconds per tick multiplied by 1 000 000 + */ static uint64_t riscv_cputime_getres(void) { uint64_t ret = 1000UL * 1000 * 1000; @@ -14,6 +38,11 @@ static uint64_t riscv_cputime_getres(void) return ret; } +/** + * @brief Read time counter + * + * @return value of ticks + */ static uint64_t riscv_cputime_gettime(void) { uint64_t time_elapsed; @@ -29,9 +58,16 @@ const static struct rt_clock_cputime_ops _riscv_ops = riscv_cputime_gettime }; +/** + * @brief Init cputimer operation of riscv architecture + * + * @return return 0 forever + */ int riscv_cputime_init(void) { clock_cpu_setops(&_riscv_ops); return 0; } INIT_BOARD_EXPORT(riscv_cputime_init); + +/*! @}*/ \ No newline at end of file diff --git a/components/drivers/cputime/cputimer.c b/components/drivers/cputime/cputimer.c index 04318336407..9e61bfa32c8 100644 --- a/components/drivers/cputime/cputimer.c +++ b/components/drivers/cputime/cputimer.c @@ -1,5 +1,5 @@ /* - * Copyright (c) 2006-2023, RT-Thread Development Team + * Copyright (c) 2006-2025 RT-Thread Development Team * * SPDX-License-Identifier: Apache-2.0 * @@ -7,15 +7,31 @@ * Date Author Notes * 2023-02-13 zhkag first version * 2023-04-03 xqyjlj fix cputimer in multithreading + * 2025-01-30 wumingzi add doxygen comment */ #include #include #include +/** + * @addtogroup Drivers RTTHREAD Driver + * @defgroup cputimer cputimer + * @brief cputimer driver api + * @ingroup Drivers + * @addtogroup cputimer + * @{ + */ + static rt_list_t _cputimer_list = RT_LIST_OBJECT_INIT(_cputimer_list); static struct rt_cputimer *_cputimer_nowtimer = RT_NULL; +/** + * @brief When cpu timeout,it will release relative semphore + * + * @param parameter + * + */ static void _cputime_sleep_timeout(void *parameter) { struct rt_semaphore *sem; @@ -23,6 +39,15 @@ static void _cputime_sleep_timeout(void *parameter) rt_sem_release(sem); } +/** + * @brief Set callback function for next timeout cputimer + * + * @param parameter point to struct rt_cputimer where callback + function needs to be set + * @note The function isn't recursively to call callback function, instead + set asynchronously next callback function after executing callback function, function when call current + callback function, + */ static void _cputime_timeout_callback(void *parameter) { struct rt_cputimer *timer; @@ -46,6 +71,10 @@ static void _cputime_timeout_callback(void *parameter) } } +/** + * @brief Set next the earliest timeout cputimer and its callback function + * + */ static void _set_next_timeout() { struct rt_cputimer *t; @@ -74,6 +103,18 @@ static void _set_next_timeout() } } +/** + * @brief Init cputimer + * + * @param timer memeory space of cputimer + * @param name name of cputimer + * @param timeout callback function that is called when timeout + * @param parameter parameter of callback function + * @param tick number of ticks left until next timeout + * @param flag flag of cputimer + * + * @note Config RT_USING_HEAP option will be vital if you want to using this function. + */ void rt_cputimer_init(rt_cputimer_t timer, const char *name, void (*timeout)(void *parameter), @@ -100,6 +141,14 @@ void rt_cputimer_init(rt_cputimer_t timer, rt_sem_init(&(timer->sem), "cputime", 0, RT_IPC_FLAG_PRIO); } +/** + * @brief Delete cputimer object + * + * @param timer deleted cputimer + * + * @note Config RT_USING_HEAP option will be vital if you want to using this function. + * @return return RT_EOK forever + */ rt_err_t rt_cputimer_delete(rt_cputimer_t timer) { rt_base_t level; @@ -123,6 +172,13 @@ rt_err_t rt_cputimer_delete(rt_cputimer_t timer) return RT_EOK; } +/** + * @brief Insert timer to timer list and start it. + * + * @param timer timer to be inserted + * + * @return return RT_EOK forever + */ rt_err_t rt_cputimer_start(rt_cputimer_t timer) { rt_list_t *timer_list; @@ -171,6 +227,13 @@ rt_err_t rt_cputimer_start(rt_cputimer_t timer) return RT_EOK; } +/** + * @brief Stop cputimer + * + * @param timer stopped cputimer + * + * @return return RT_EOK forever + */ rt_err_t rt_cputimer_stop(rt_cputimer_t timer) { rt_base_t level; @@ -199,6 +262,39 @@ rt_err_t rt_cputimer_stop(rt_cputimer_t timer) return RT_EOK; } +/** + * @brief Control cputimer by cmd + * + * @param timer controlled cputimer + * @param cmd the command of cputimer. It can be one of: + | Options | Description | + |------------------------------------|---------------------------------------------------| + | `RT_TIMER_CTRL_GET_TIME`: | Get number of init ticks. | + | `RT_TIMER_CTRL_SET_TIME`: | Set number of init ticks. | + | `RT_TIMER_CTRL_SET_ONESHOT`: | Set flag of timer to ONESHOT. | + | `RT_TIMER_CTRL_SET_PERIODIC`: | Set flag of timer to PERIODIC. | + | `RT_TIMER_CTRL_GET_STATE`: | Get state of timer. | + | `RT_TIMER_CTRL_GET_REMAIN_TIME`: | Get number of ticks left. | + | `RT_TIMER_CTRL_GET_FUNC`: | Get of timeout callback function. | + | `RT_TIMER_CTRL_SET_FUNC`: | Set of timeout callback function. | + | `RT_TIMER_CTRL_GET_PARM`: | Get parameters of callback function. | + | `RT_TIMER_CTRL_SET_PARM`: | Set parameters of callback function. | + * @param arg point to user data. It will depands on vary of cmd parameter: + | Cmd options | Description | + |------------------------------------|---------------------------------------------------| + | `RT_TIMER_CTRL_GET_TIME`: | Arg will be a pointer to rt_uint64_t type. | + | `RT_TIMER_CTRL_SET_TIME`: | Arg shall be a pointer to rt_uint64_t type. | + | `RT_TIMER_CTRL_SET_ONESHOT`: | Arg is useless parameter. | + | `RT_TIMER_CTRL_SET_PERIODIC`: | Arg is useless parameter. | + | `RT_TIMER_CTRL_GET_STATE`: | Arg shall be a pointer to rt_uint32_t type. | + | `RT_TIMER_CTRL_GET_REMAIN_TIME`: | Arg shall be a pointer to rt_uint64_t type.. | + | `RT_TIMER_CTRL_GET_FUNC`: | Arg will be a pointer to void (*)(void*) type. | + | `RT_TIMER_CTRL_SET_FUNC`: | Arg shall be a pointer to void (*)(void*) type. | + | `RT_TIMER_CTRL_GET_PARM`: | Arg will be a pointer to void* type. | + | `RT_TIMER_CTRL_SET_PARM`: | Arg shall be a pointer to void* type. | + * + * @return rt_err_t return RT_EOK forever + */ rt_err_t rt_cputimer_control(rt_cputimer_t timer, int cmd, void *arg) { rt_base_t level; @@ -268,6 +364,13 @@ rt_err_t rt_cputimer_control(rt_cputimer_t timer, int cmd, void *arg) return RT_EOK; } +/** + * @brief Detach cputimer + * + * @param timer deteched cputimer + * + * @return rt_err_t return RT_EOK forever + */ rt_err_t rt_cputimer_detach(rt_cputimer_t timer) { rt_base_t level; @@ -292,6 +395,14 @@ rt_err_t rt_cputimer_detach(rt_cputimer_t timer) return RT_EOK; } +/** + * @brief Let cpu to sleep a number of ticks + * + * @param tick number of ticks to sleep + * + * @return rt_err_t returns RT_EOK if the delay is successful; + otherwise, returns a value indicating failure. + */ rt_err_t rt_cputime_sleep(rt_uint64_t tick) { rt_base_t level; @@ -322,18 +433,43 @@ rt_err_t rt_cputime_sleep(rt_uint64_t tick) return RT_EOK; } +/** + * @brief Let cpu to sleep a number of nanosecond + * + * @param ns time of sleep + * + * @return rt_err_t returns RT_EOK if the delay is successful; + otherwise, returns a value indicating failure. + */ rt_err_t rt_cputime_ndelay(rt_uint64_t ns) { uint64_t unit = clock_cpu_getres(); return rt_cputime_sleep(ns * (1000UL * 1000) / unit); } +/** + * @brief Let cpu to sleep a number of microsecond + * + * @param us time of sleep + * + * @return rt_err_t returns RT_EOK if the delay is successful; + otherwise, returns a value indicating failure. + */ rt_err_t rt_cputime_udelay(rt_uint64_t us) { return rt_cputime_ndelay(us * 1000); } +/** + * @brief Let cpu to sleep a number of millisecond + * + * @param ms time of sleep + * + * @return rt_err_t returns RT_EOK if the delay is successful; + otherwise, returns a value indicating failure. + */ rt_err_t rt_cputime_mdelay(rt_uint64_t ms) { return rt_cputime_ndelay(ms * 1000000); } +/*! @}*/ \ No newline at end of file diff --git a/components/drivers/include/drivers/cputime.h b/components/drivers/include/drivers/cputime.h index 478ccfd0199..4603a53c2a7 100644 --- a/components/drivers/include/drivers/cputime.h +++ b/components/drivers/include/drivers/cputime.h @@ -1,11 +1,12 @@ /* - * Copyright (c) 2006-2023, RT-Thread Development Team + * Copyright (c) 2006-2025 RT-Thread Development Team * * SPDX-License-Identifier: Apache-2.0 * * Change Logs: * Date Author Notes * 2017-12-23 Bernard first version + * 2025-01-30 wumingzi add doxygen comment */ #ifndef CPUTIME_H__ @@ -14,6 +15,15 @@ #include #include "cputimer.h" +/** + * @addtogroup Drivers RTTHREAD Driver + * @defgroup cputimer cputimer + * @brief cputimer driver api + * @ingroup Drivers + * @addtogroup cputimer + * @{ + */ + struct rt_clock_cputime_ops { uint64_t (*cputime_getres)(void); @@ -36,3 +46,4 @@ int riscv_cputime_init(void); #endif /* RT_USING_CPUTIME_RISCV */ #endif +/*! @}*/ \ No newline at end of file diff --git a/components/drivers/include/drivers/cputimer.h b/components/drivers/include/drivers/cputimer.h index 371992a41e1..90cf045b1ef 100644 --- a/components/drivers/include/drivers/cputimer.h +++ b/components/drivers/include/drivers/cputimer.h @@ -1,11 +1,12 @@ /* - * Copyright (c) 2006-2023, RT-Thread Development Team + * Copyright (c) 2006-2025 RT-Thread Development Team * * SPDX-License-Identifier: Apache-2.0 * * Change Logs: * Date Author Notes * 2023-02-13 zhkag first version + * 2025-01-30 wumingzi add doxygen comment */ #ifndef CPUTIMER_H__ @@ -13,6 +14,134 @@ #include +/** + * @addtogroup Drivers RTTHREAD Driver + * @defgroup cputimer cputimer + * @brief cputimer driver api + * @ingroup Drivers + * @addtogroup cputimer + * + * @note Cputimer, a highly precise hardware clock, is essential to implement in + the BSP if you intend to use it in your application. + * + * Example for implementing driver + * + * @code + * + * #include + * #include + * #include + * + * #include + * + * #define HWTIMER_DEV_NAME "timer7" + * + * rt_uint64_t count = 0; + * + * rt_uint64_t timeout_tick = 0; + * + * void (*hwtimer_timeout)(void *param); + * void *parameter = RT_NULL; + * + * static double cortexm_cputime_getres(void) + * { + * return 10000; + * } + * + * static uint64_t cortexm_cputime_gettime(void) + * { + * return count; + * } + * + * static int cortexm_cputime_settimeout(uint64_t tick, void (*timeout)(void *param), void *param) + * { + * timeout_tick = tick; + * hwtimer_timeout = timeout; + * parameter = param; + * return 0; + * } + * + * const static struct rt_clock_cputime_ops _cortexm_ops = + * { + * cortexm_cputime_getres, + * cortexm_cputime_gettime, + * cortexm_cputime_settimeout + * }; + * + * int cortexm_cputime_init(void) + * { + * clock_cpu_setops(&_cortexm_ops); + * return 0; + * } + * INIT_BOARD_EXPORT(cortexm_cputime_init); + * + * static rt_err_t timeout_cb(rt_device_t dev, rt_size_t size) + * { + * count++; + * if(count == timeout_tick) + * { + * timeout_tick = 0; + * if(hwtimer_timeout != RT_NULL) + * hwtimer_timeout(parameter); + * } + * return 0; + * } + * + * static int hwtimer_init() + * { + * rt_err_t ret = RT_EOK; + * rt_hwtimerval_t timeout_s; + * rt_device_t hw_dev = RT_NULL; + * rt_hwtimer_mode_t mode; + * rt_uint32_t freq = 1000000; + * + * hw_dev = rt_device_find(HWTIMER_DEV_NAME); + * if (hw_dev == RT_NULL) + * { + * _cortexm_ops.cputime_settimeout = RT_NULL; + * rt_kprintf("hwtimer sample run failed! can't find %s device!\n", HWTIMER_DEV_NAME); + * return -RT_ERROR; + * } + * + * ret = rt_device_open(hw_dev, RT_DEVICE_OFLAG_RDWR); + * if (ret != RT_EOK) + * { + * _cortexm_ops.cputime_settimeout = RT_NULL; + * rt_kprintf("open %s device failed!\n", HWTIMER_DEV_NAME); + * return ret; + * } + * rt_device_set_rx_indicate(hw_dev, timeout_cb); + * + * rt_device_control(hw_dev, HWTIMER_CTRL_FREQ_SET, &freq); + * mode = HWTIMER_MODE_PERIOD; + * ret = rt_device_control(hw_dev, HWTIMER_CTRL_MODE_SET, &mode); + * if (ret != RT_EOK) + * { + * _cortexm_ops.cputime_settimeout = RT_NULL; + * rt_kprintf("set mode failed! ret is :%d\n", ret); + * return ret; + * } + * timeout_s.sec = 0; + * timeout_s.usec = 10; + * + * if (rt_device_write(hw_dev, 0, &timeout_s, sizeof(timeout_s)) != sizeof(timeout_s)) + * { + * _cortexm_ops.cputime_settimeout = RT_NULL; + * rt_kprintf("set timeout value failed\n"); + * return -RT_ERROR; + * } + * return ret; + * } + * INIT_APP_EXPORT(hwtimer_init); + * @endcode + * + * @{ + */ + +/** + * @brief Cputimer structure + * + */ struct rt_cputimer { struct rt_object parent; /**< inherit from rt_object */ @@ -46,3 +175,4 @@ rt_err_t rt_cputime_udelay(rt_uint64_t us); rt_err_t rt_cputime_mdelay(rt_uint64_t ms); #endif +/*! @}*/ \ No newline at end of file diff --git a/documentation/Doxyfile b/documentation/Doxyfile index a3b98424d67..72c888eaa45 100644 --- a/documentation/Doxyfile +++ b/documentation/Doxyfile @@ -870,6 +870,7 @@ INPUT = . \ ../components/finsh \ ../components/drivers/include/drivers \ ../components/drivers/clk \ + ../components/drivers/cputime\ ../components/dfs/dfs_v2/src \ ../components/dfs/dfs_v2/include