[clock_time] Add unified clock_time subsystem with documentation

- Created new clock_time subsystem consolidating hwtimer/ktime/cputime
- Implemented clock_time device abstraction with ops structure
- Added high-resolution timer (hrtimer) implementation
- Created compatibility layers for legacy APIs
- Added comprehensive English and Chinese documentation
- Updated Kconfig to mark old subsystems as deprecated

Co-authored-by: BernardXiong <[email protected]>

Author: Copilot

components/drivers/Kconfig

@@ -5,6 +5,7 @@ rsource "ipc/Kconfig"
 
 rsource "serial/Kconfig"
 rsource "can/Kconfig"
+rsource "clock_time/Kconfig"
 rsource "cputime/Kconfig"
 rsource "i2c/Kconfig"
 rsource "phy/Kconfig"

components/drivers/clock_time/Kconfig

@@ -0,0 +1,36 @@
+menuconfig RT_USING_CLOCK_TIME
+    bool "Using unified clock_time subsystem"
+    default n
+    help
+        Enable the unified clock_time subsystem which consolidates
+        hwtimer, ktime, and cputime into a single coherent framework.
+        
+        This subsystem provides:
+        - Clocksource: Free-running counter for timekeeping
+        - Clockevent: Programmable timeout events
+        - High-resolution timers (hrtimer)
+        - POSIX clock support
+        - Boottime tracking
+
+if RT_USING_CLOCK_TIME
+    config RT_CLOCK_TIME_COMPAT_KTIME
+        bool "Enable compatibility layer for ktime APIs"
+        default y
+        help
+            Provides backward compatibility wrappers for legacy ktime APIs.
+            Enable this if existing code uses rt_ktime_* functions.
+
+    config RT_CLOCK_TIME_COMPAT_CPUTIME
+        bool "Enable compatibility layer for cputime APIs"
+        default y
+        help
+            Provides backward compatibility wrappers for legacy cputime APIs.
+            Enable this if existing code uses clock_cpu_* or rt_cputimer_* functions.
+
+    config RT_CLOCK_TIME_COMPAT_HWTIMER
+        bool "Enable compatibility layer for hwtimer device APIs"
+        default y
+        help
+            Provides backward compatibility for legacy hwtimer device APIs.
+            Enable this if BSP drivers use rt_device_hwtimer_* functions.
+endif

components/drivers/clock_time/SConscript

@@ -0,0 +1,28 @@
+from building import *
+
+cwd = GetCurrentDir()
+
+src = Split('''
+src/clock_time.c
+src/hrtimer.c
+src/clock_time_tick.c
+''')
+
+if GetDepend('RT_CLOCK_TIME_COMPAT_KTIME'):
+    src += ['src/ktime_compat.c']
+
+if GetDepend('RT_CLOCK_TIME_COMPAT_CPUTIME'):
+    src += ['src/cputime_compat.c']
+
+CPPPATH = [cwd + '/include', cwd + '/../include']
+
+LOCAL_CCFLAGS = ''
+if rtconfig.PLATFORM in ['gcc', 'armclang']:
+    LOCAL_CCFLAGS += ' -std=gnu99'
+elif rtconfig.PLATFORM in ['armcc']:
+    LOCAL_CCFLAGS += ' --c99 --gnu'
+
+group = DefineGroup('DeviceDrivers', src, depend=['RT_USING_CLOCK_TIME'], 
+                   CPPPATH=CPPPATH, LOCAL_CCFLAGS=LOCAL_CCFLAGS)
+
+Return('group')

components/drivers/clock_time/src/clock_time.c

@@ -0,0 +1,200 @@
+/*
+ * Copyright (c) 2006-2024, RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2024-12-04     RT-Thread    Unified clock_time subsystem - core implementation
+ */
+
+#include <rtdevice.h>
+#include <rthw.h>
+
+#define DBG_TAG "clock_time"
+#define DBG_LVL DBG_INFO
+#include <rtdbg.h>
+
+static struct rt_clock_time_device *_default_clock_time = RT_NULL;
+
+rt_err_t rt_clock_time_device_register(struct rt_clock_time_device *dev, 
+                                       const char *name, 
+                                       rt_uint8_t caps)
+{
+    RT_ASSERT(dev != RT_NULL);
+    RT_ASSERT(dev->ops != RT_NULL);
+    RT_ASSERT(name != RT_NULL);
+    
+    /* Validate capability requirements */
+    if (caps & RT_CLOCK_TIME_CAP_CLOCKSOURCE)
+    {
+        RT_ASSERT(dev->ops->get_freq != RT_NULL);
+        RT_ASSERT(dev->ops->get_counter != RT_NULL);
+    }
+    
+    if (caps & RT_CLOCK_TIME_CAP_CLOCKEVENT)
+    {
+        RT_ASSERT(dev->ops->set_timeout != RT_NULL);
+    }
+    
+    dev->caps = caps;
+    dev->parent.type = RT_Device_Class_Timer;
+    dev->parent.rx_indicate = RT_NULL;
+    dev->parent.tx_complete = RT_NULL;
+    dev->parent.user_data = RT_NULL;
+    
+    /* Calculate resolution scale factor */
+    if (dev->ops->get_freq)
+    {
+        rt_uint64_t freq = dev->ops->get_freq();
+        /* res_scale = RT_CLOCK_TIME_RESMUL for nanosecond precision */
+        dev->res_scale = RT_CLOCK_TIME_RESMUL;
+    }
+    
+    /* Register as a device */
+    rt_err_t result = rt_device_register(&dev->parent, name, 
+                                         RT_DEVICE_FLAG_RDWR | RT_DEVICE_FLAG_STANDALONE);
+    
+    if (result == RT_EOK)
+    {
+        LOG_I("Clock time device '%s' registered (caps: 0x%02x)", name, caps);
+        
+        /* Set as default if none exists */
+        if (_default_clock_time == RT_NULL)
+        {
+            _default_clock_time = dev;
+            LOG_I("Set '%s' as default clock time device", name);
+        }
+    }
+    
+    return result;
+}
+
+rt_err_t rt_clock_time_set_default(struct rt_clock_time_device *dev)
+{
+    RT_ASSERT(dev != RT_NULL);
+    
+    _default_clock_time = dev;
+    LOG_I("Default clock time device set to '%s'", dev->parent.parent.name);
+    
+    return RT_EOK;
+}
+
+struct rt_clock_time_device *rt_clock_time_get_default(void)
+{
+    return _default_clock_time;
+}
+
+/* Clocksource APIs */
+
+rt_uint64_t rt_clock_time_getres(void)
+{
+    if (_default_clock_time == RT_NULL || 
+        !(_default_clock_time->caps & RT_CLOCK_TIME_CAP_CLOCKSOURCE))
+    {
+        /* Fallback to tick-based resolution */
+        return ((1000ULL * 1000 * 1000) * RT_CLOCK_TIME_RESMUL) / RT_TICK_PER_SECOND;
+    }
+    
+    rt_uint64_t freq = _default_clock_time->ops->get_freq();
+    return ((1000ULL * 1000 * 1000) * RT_CLOCK_TIME_RESMUL) / freq;
+}
+
+rt_uint64_t rt_clock_time_getfreq(void)
+{
+    if (_default_clock_time == RT_NULL || 
+        !(_default_clock_time->caps & RT_CLOCK_TIME_CAP_CLOCKSOURCE))
+    {
+        /* Fallback to tick frequency */
+        return RT_TICK_PER_SECOND;
+    }
+    
+    return _default_clock_time->ops->get_freq();
+}
+
+rt_uint64_t rt_clock_time_getcnt(void)
+{
+    if (_default_clock_time == RT_NULL || 
+        !(_default_clock_time->caps & RT_CLOCK_TIME_CAP_CLOCKSOURCE))
+    {
+        /* Fallback to tick counter */
+        return rt_tick_get();
+    }
+    
+    return _default_clock_time->ops->get_counter();
+}
+
+rt_err_t rt_clock_time_boottime_ns(struct timespec *ts)
+{
+    RT_ASSERT(ts != RT_NULL);
+    
+    rt_uint64_t cnt = rt_clock_time_getcnt();
+    rt_uint64_t res = rt_clock_time_getres();
+    rt_uint64_t ns = (cnt * res) / RT_CLOCK_TIME_RESMUL;
+    
+    ts->tv_sec = ns / (1000ULL * 1000 * 1000);
+    ts->tv_nsec = ns % (1000ULL * 1000 * 1000);
+    
+    return RT_EOK;
+}
+
+rt_err_t rt_clock_time_boottime_us(struct timeval *tv)
+{
+    RT_ASSERT(tv != RT_NULL);
+    
+    rt_uint64_t cnt = rt_clock_time_getcnt();
+    rt_uint64_t res = rt_clock_time_getres();
+    rt_uint64_t ns = (cnt * res) / RT_CLOCK_TIME_RESMUL;
+    
+    tv->tv_sec = ns / (1000ULL * 1000 * 1000);
+    tv->tv_usec = (ns % (1000ULL * 1000 * 1000)) / 1000;
+    
+    return RT_EOK;
+}
+
+rt_err_t rt_clock_time_boottime_s(time_t *t)
+{
+    RT_ASSERT(t != RT_NULL);
+    
+    rt_uint64_t cnt = rt_clock_time_getcnt();
+    rt_uint64_t res = rt_clock_time_getres();
+    rt_uint64_t ns = (cnt * res) / RT_CLOCK_TIME_RESMUL;
+    
+    *t = ns / (1000ULL * 1000 * 1000);
+    
+    return RT_EOK;
+}
+
+/* Time conversion functions */
+
+rt_uint64_t rt_clock_time_cnt_to_ns(rt_uint64_t cnt)
+{
+    rt_uint64_t res = rt_clock_time_getres();
+    return (cnt * res) / RT_CLOCK_TIME_RESMUL;
+}
+
+rt_uint64_t rt_clock_time_cnt_to_us(rt_uint64_t cnt)
+{
+    return rt_clock_time_cnt_to_ns(cnt) / 1000;
+}
+
+rt_uint64_t rt_clock_time_cnt_to_ms(rt_uint64_t cnt)
+{
+    return rt_clock_time_cnt_to_ns(cnt) / (1000 * 1000);
+}
+
+rt_uint64_t rt_clock_time_ns_to_cnt(rt_uint64_t ns)
+{
+    rt_uint64_t freq = rt_clock_time_getfreq();
+    return (ns * freq) / (1000ULL * 1000 * 1000);
+}
+
+rt_uint64_t rt_clock_time_us_to_cnt(rt_uint64_t us)
+{
+    return rt_clock_time_ns_to_cnt(us * 1000);
+}
+
+rt_uint64_t rt_clock_time_ms_to_cnt(rt_uint64_t ms)
+{
+    return rt_clock_time_ns_to_cnt(ms * 1000 * 1000);
+}

components/drivers/clock_time/src/clock_time_tick.c

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2006-2024, RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2024-12-04     RT-Thread    Tick-based clock_time adapter (fallback)
+ */
+
+#include <rtdevice.h>
+
+/**
+ * @brief Tick-based fallback clock_time implementation
+ * 
+ * This provides a basic clock_time implementation using RT-Thread's
+ * tick counter. It should be overridden by BSP-specific implementations
+ * that provide higher resolution hardware timers.
+ */
+
+static rt_uint64_t _tick_get_freq(void)
+{
+    return RT_TICK_PER_SECOND;
+}
+
+static rt_uint64_t _tick_get_counter(void)
+{
+    return rt_tick_get();
+}
+
+static const struct rt_clock_time_ops _tick_clock_ops = 
+{
+    .get_freq = _tick_get_freq,
+    .get_counter = _tick_get_counter,
+    .set_timeout = RT_NULL,  /* No hardware timeout support */
+};
+
+static struct rt_clock_time_device _tick_clock_device;
+
+/**
+ * @brief Initialize tick-based clock_time device
+ * 
+ * This is automatically called if no other clock_time device is registered.
+ */
+int rt_clock_time_tick_init(void)
+{
+    _tick_clock_device.ops = &_tick_clock_ops;
+    
+    return rt_clock_time_device_register(&_tick_clock_device, 
+                                        "tick_clock",
+                                        RT_CLOCK_TIME_CAP_CLOCKSOURCE);
+}
+INIT_DEVICE_EXPORT(rt_clock_time_tick_init);