[docs][clock_time] add clock time documentation

Author: BernardXiong

documentation/6.components/device-driver/clock_time/README.md

@@ -0,0 +1,87 @@
+@page page_device_clock_time Clock Time Subsystem
+
+# Overview
+
+The clock_time subsystem provides a unified, high-resolution time base and
+programmable event scheduling for RT-Thread. It decouples a monotonic counter
+(clock source) from deadline delivery (clock event), so platforms can mix
+hardware counters and timers while the kernel and libc see consistent behavior.
+
+# Architecture
+
+![Clock time architecture](figures/clock_time_arch.svg)
+
+## Layering and Responsibilities
+
+- Upper layers: kernel services (timeouts, delays), POSIX/libc time APIs
+  (clock_gettime, nanosleep), and RTC/soft-RTC consume the monotonic time base
+  and timer events exposed by clock_time.
+- clock_time subsystem: core APIs, clock source/event devices, the hrtimer
+  scheduler, boottime helpers, and the clock_timer adapter.
+- Lower layers: BSP drivers provide hardware counters and timers, which are
+  wrapped as clock_time devices or clock_timer devices.
+
+## Internal Components
+
+- Core API (clock_time_core.c)
+  - Registers clock_time devices, manages default source/event selection, and
+    provides counter <-> nanosecond conversion with fixed-point scaling.
+- Clock source device (rt_clock_time_device + RT_CLOCK_TIME_CAP_SOURCE)
+  - Supplies a free-running counter and frequency for monotonic time reads.
+- Clock event device (rt_clock_time_device + RT_CLOCK_TIME_CAP_EVENT)
+  - Programs the next deadline and calls rt_clock_time_event_isr() on expiry.
+- Clock hrtimer (clock_hrtimer.c)
+  - Schedules high-resolution timeouts, programs the next event, and dispatches
+    callbacks. Falls back to software timer when no hardware event is available.
+- Boottime helpers (clock_boottime.c)
+  - Converts the monotonic counter into timeval/timespec/seconds for upper
+    layers.
+- Clock timer adapter (clock_timer.c)
+  - Exposes a unified hardware timer device (rt_clock_timer) and can register
+    itself as a clock_time event device.
+- Architecture sources (arch/* and clock_time_arm_arch.c)
+  - Provide fast CPU counters or architectural timers and register them as the
+    default clock source when available.
+
+## Data Flow
+
+- Read path
+  - Clock source counter -> scaled resolution -> nanoseconds -> boottime or
+    clock_gettime.
+- Timeout path
+  - HRTimer queue -> next expiry -> set_timeout on event device -> event ISR ->
+    hrtimer processing -> callbacks.
+
+# Configuration
+
+Enable the subsystem in menuconfig:
+
+```
+RT-Thread Components ->
+    Device Drivers ->
+        [*] Clock time subsystem (RT_USING_CLOCK_TIME)
+```
+
+Optional settings:
+
+- CLOCK_TIMER_FREQ (RISC-V): base counter frequency used by the clock source.
+- RT_CLOCK_TIME_ARM_ARCH: enable ARM architected timer integration (DM/OFW).
+
+# BSP Integration Checklist
+
+- Provide a clock source:
+  - Register a rt_clock_time_device with CAP_SOURCE, or use the provided
+    architecture source (AArch64/RISC-V) via rt_clock_time_source_init().
+- Provide a clock event:
+  - Register a rt_clock_time_device with CAP_EVENT and call
+    rt_clock_time_event_isr() in its interrupt handler.
+  - Or register a rt_clock_timer device; it can become the default event
+    device automatically.
+- Keep event ISRs short; heavy work should run in thread context if needed.
+
+# Detailed Documents
+
+- @subpage page_device_clock_time_core
+- @subpage page_device_clock_hrtimer
+- @subpage page_device_clock_boottime
+- @subpage page_device_clock_timer

documentation/6.components/device-driver/clock_time/README_zh.md

@@ -0,0 +1,76 @@
+# Clock Time 子系统概述
+
+clock_time 子系统为 RT-Thread 提供统一的高精度时间基准与事件调度能力。
+它将单调计数（时钟源）与超时事件（时钟事件）解耦，使平台可以组合不同的
+硬件计数器与定时器，同时为内核与 libc 提供一致的时间行为。
+
+# 软件架构
+
+![Clock time architecture](figures/clock_time_arch.svg)
+
+## 分层关系与职责
+
+- 上层：内核超时/延时、POSIX/libc 时间接口（clock_gettime、nanosleep），
+  以及 RTC/软 RTC，直接使用 clock_time 提供的时间与事件能力。
+- clock_time 子系统：核心 API、时钟源/事件设备、高精度定时器调度器、
+  boottime 辅助函数、clock_timer 适配层。
+- 下层：BSP 驱动提供硬件计数器与定时器，并封装为 clock_time 设备或
+  clock_timer 设备。
+
+## 内部组成
+
+- Core API（clock_time_core.c）
+  - 负责设备注册、默认源/事件选择，以及计数 <-> 纳秒的缩放换算。
+- 时钟源设备（rt_clock_time_device + RT_CLOCK_TIME_CAP_SOURCE）
+  - 提供自由运行计数器与频率，作为单调时间基准。
+- 时钟事件设备（rt_clock_time_device + RT_CLOCK_TIME_CAP_EVENT）
+  - 负责下一次超时编程，并在到期时调用 rt_clock_time_event_isr()。
+- 高精度定时器（clock_hrtimer.c）
+  - 维护超时队列、设置下一次事件并分发回调。没有硬件事件时退化为软件定时器。
+- Boottime 辅助（clock_boottime.c）
+  - 将单调计数转换为 timeval/timespec/秒，供上层使用。
+- Clock timer 适配层（clock_timer.c）
+  - 提供统一的硬件定时器设备（rt_clock_timer），并可注册为事件设备。
+- 架构源（arch/* 与 clock_time_arm_arch.c）
+  - 提供 CPU 计数器或架构定时器，并在可用时设置为默认时钟源。
+
+## 数据流
+
+- 读取路径
+  - 时钟源计数 -> 缩放分辨率 -> 纳秒 -> boottime 或 clock_gettime。
+- 超时路径
+  - hrtimer 队列 -> 下一到期 -> 事件设备 set_timeout -> 事件中断 ->
+    hrtimer 处理 -> 回调分发。
+
+# 配置选项
+
+在 menuconfig 中启用：
+
+```
+RT-Thread Components ->
+    Device Drivers ->
+        [*] Clock time subsystem (RT_USING_CLOCK_TIME)
+```
+
+可选配置：
+
+- CLOCK_TIMER_FREQ（RISC-V）：时钟源使用的基础计数频率。
+- RT_CLOCK_TIME_ARM_ARCH：启用 ARM 架构定时器集成（DM/OFW）。
+
+# BSP 集成要点
+
+- 提供时钟源：
+  - 注册带 CAP_SOURCE 的 rt_clock_time_device，或使用
+    rt_clock_time_source_init() 提供的架构源。
+- 提供时钟事件：
+  - 注册带 CAP_EVENT 的 rt_clock_time_device，并在中断中调用
+    rt_clock_time_event_isr()。
+  - 或直接注册 rt_clock_timer 设备，自动成为默认事件设备。
+- 事件中断应保持简短，复杂处理建议转到线程上下文。
+
+# 详细文档
+
+- clock_time_core.md
+- clock_hrtimer.md
+- clock_boottime.md
+- clock_timer.md

documentation/6.components/device-driver/clock_time/clock_boottime.md

@@ -0,0 +1,87 @@
+@page page_device_clock_boottime Clock Boottime Helpers
+
+# Overview
+
+Boottime helpers convert the clock_time monotonic counter into standard time
+formats. The resulting values represent time since boot and do not depend on
+RTC or wall-clock settings.
+
+# API
+
+```c
+rt_err_t rt_clock_boottime_get_us(struct timeval *tv);
+rt_err_t rt_clock_boottime_get_s(time_t *t);
+rt_err_t rt_clock_boottime_get_ns(struct timespec *ts);
+```
+
+All functions return RT_EOK on success or -RT_ERROR if the clock source is
+unavailable. The returned values are monotonic and suitable for measuring
+elapsed time.
+
+## rt_clock_boottime_get_us
+
+```c
+rt_err_t rt_clock_boottime_get_us(struct timeval *tv);
+```
+
+- Purpose: get time since boot as seconds + microseconds.
+- Parameters: `tv` must be a valid pointer to `struct timeval`.
+- Return values:
+  - RT_EOK: data written to `tv`.
+  - -RT_ERROR: no valid clock_time source or conversion failed.
+- Notes:
+  - `tv_usec` is derived from the clock_time resolution and may not be exact
+    microseconds if the underlying counter does not align to 1 us.
+
+## rt_clock_boottime_get_s
+
+```c
+rt_err_t rt_clock_boottime_get_s(time_t *t);
+```
+
+- Purpose: get time since boot in whole seconds.
+- Parameters: `t` must be a valid pointer to `time_t`.
+- Return values:
+  - RT_EOK: `*t` updated.
+  - -RT_ERROR: no valid clock_time source or conversion failed.
+- Notes:
+  - Sub-second precision is discarded; use `rt_clock_boottime_get_us()` or
+    `rt_clock_boottime_get_ns()` if needed.
+
+## rt_clock_boottime_get_ns
+
+```c
+rt_err_t rt_clock_boottime_get_ns(struct timespec *ts);
+```
+
+- Purpose: get time since boot as seconds + nanoseconds.
+- Parameters: `ts` must be a valid pointer to `struct timespec`.
+- Return values:
+  - RT_EOK: data written to `ts`.
+  - -RT_ERROR: no valid clock_time source or conversion failed.
+- Notes:
+  - `tv_nsec` reflects the clock_time resolution; it may not be 1 ns granularity
+    if the counter frequency is lower.
+
+# Example
+
+```c
+#include <drivers/clock_time.h>
+
+static void demo_boottime(void)
+{
+    struct timespec ts;
+
+    if (rt_clock_boottime_get_ns(&ts) == RT_EOK)
+    {
+        rt_kprintf("boottime: %ld.%09ld\n", (long)ts.tv_sec, ts.tv_nsec);
+    }
+}
+```
+
+# Notes
+
+- The boottime helpers are used by the soft RTC implementation to build a
+  stable base time.
+- If no clock_time source is registered, the subsystem falls back to the tick
+  counter and the resolution matches RT_TICK_PER_SECOND.

documentation/6.components/device-driver/clock_time/clock_boottime_zh.md

@@ -0,0 +1,78 @@
+# Clock Boottime 辅助
+
+boottime 辅助函数将 clock_time 的单调计数转换为常见时间格式，返回值表示
+“系统启动以来的时间”，不受 RTC 或墙上时间设置影响。
+
+# API
+
+```c
+rt_err_t rt_clock_boottime_get_us(struct timeval *tv);
+rt_err_t rt_clock_boottime_get_s(time_t *t);
+rt_err_t rt_clock_boottime_get_ns(struct timespec *ts);
+```
+
+成功返回 RT_EOK；若时钟源不可用则返回 -RT_ERROR。返回值单调递增，适合用于
+测量耗时。
+
+## rt_clock_boottime_get_us
+
+```c
+rt_err_t rt_clock_boottime_get_us(struct timeval *tv);
+```
+
+- 作用：获取启动以来的时间，格式为秒 + 微秒。
+- 参数：`tv` 需为有效的 `struct timeval` 指针。
+- 返回值：
+  - RT_EOK：成功写入 `tv`。
+  - -RT_ERROR：无有效时钟源或换算失败。
+- 说明：
+  - `tv_usec` 由 clock_time 分辨率换算而来，不一定严格为 1 us 精度。
+
+## rt_clock_boottime_get_s
+
+```c
+rt_err_t rt_clock_boottime_get_s(time_t *t);
+```
+
+- 作用：获取启动以来的整秒数。
+- 参数：`t` 需为有效的 `time_t` 指针。
+- 返回值：
+  - RT_EOK：成功写入 `*t`。
+  - -RT_ERROR：无有效时钟源或换算失败。
+- 说明：
+  - 该接口仅返回秒，若需亚秒精度请使用其它接口。
+
+## rt_clock_boottime_get_ns
+
+```c
+rt_err_t rt_clock_boottime_get_ns(struct timespec *ts);
+```
+
+- 作用：获取启动以来的时间，格式为秒 + 纳秒。
+- 参数：`ts` 需为有效的 `struct timespec` 指针。
+- 返回值：
+  - RT_EOK：成功写入 `ts`。
+  - -RT_ERROR：无有效时钟源或换算失败。
+- 说明：
+  - `tv_nsec` 的精度取决于计数频率，不一定达到 1 ns。
+
+# 示例
+
+```c
+#include <drivers/clock_time.h>
+
+static void demo_boottime(void)
+{
+    struct timespec ts;
+
+    if (rt_clock_boottime_get_ns(&ts) == RT_EOK)
+    {
+        rt_kprintf("boottime: %ld.%09ld\n", (long)ts.tv_sec, ts.tv_nsec);
+    }
+}
+```
+
+# 注意事项
+
+- 软 RTC 会使用 boottime 作为稳定基准。
+- 未注册时钟源时，系统退化为 tick 计数，分辨率由 RT_TICK_PER_SECOND 决定。