|
|
@@ -0,0 +1,206 @@
|
|
|
+# Clock Time Subsystem
|
|
|
+
|
|
|
+## Overview
|
|
|
+
|
|
|
+The `clock_time` subsystem is a unified framework for time management in RT-Thread, replacing the legacy `hwtimer`, `ktime`, and `cputime` subsystems with a single, coherent API.
|
|
|
+
|
|
|
+## Background
|
|
|
+
|
|
|
+Previously, RT-Thread had three separate time-related subsystems:
|
|
|
+
|
|
|
+1. **hwtimer**: Device abstraction for hardware timers with read/write interfaces
|
|
|
+2. **cputime**: CPU time tracking with ops structure for high-resolution counters
|
|
|
+3. **ktime**: Kernel time with boottime tracking and high-resolution timers (hrtimer)
|
|
|
+
|
|
|
+These subsystems had overlapping functionality, inconsistent APIs, and no clear separation of concerns, leading to:
|
|
|
+- Confusion about which subsystem to use
|
|
|
+- Duplicated code in BSP drivers
|
|
|
+- Difficulty maintaining compatibility
|
|
|
+- Scattered documentation
|
|
|
+
|
|
|
+## Design Goals
|
|
|
+
|
|
|
+The `clock_time` subsystem addresses these issues by:
|
|
|
+
|
|
|
+1. **Unification**: Single device abstraction (`rt_clock_time_device`) for all timer hardware
|
|
|
+2. **Clarity**: Clear separation between clocksource (counter) and clockevent (timeout) capabilities
|
|
|
+3. **Compatibility**: Backward compatibility layers for all legacy APIs
|
|
|
+4. **Simplicity**: Fewer concepts to learn, easier BSP integration
|
|
|
+5. **Flexibility**: Works with both MCU (tick-based fallback) and MPU (high-res timers) platforms
|
|
|
+
|
|
|
+## Architecture
|
|
|
+
|
|
|
+```
|
|
|
+┌─────────────────────────────────────────────┐
|
|
|
+│ Application / POSIX APIs │
|
|
|
+└───────────────────┬─────────────────────────┘
|
|
|
+ │
|
|
|
+┌───────────────────▼─────────────────────────┐
|
|
|
+│ Unified clock_time API │
|
|
|
+│ - Clocksource (counter, boottime) │
|
|
|
+│ - Clockevent (timeout, hrtimer) │
|
|
|
+│ - Time conversion utilities │
|
|
|
+└───────────────────┬─────────────────────────┘
|
|
|
+ │
|
|
|
+┌───────────────────▼─────────────────────────┐
|
|
|
+│ rt_clock_time_device + ops │
|
|
|
+│ Capability flags: CLOCKSOURCE | CLOCKEVENT │
|
|
|
+└───────────────────┬─────────────────────────┘
|
|
|
+ │
|
|
|
+┌───────────────────▼─────────────────────────┐
|
|
|
+│ BSP Hardware Timer Driver │
|
|
|
+│ (SysTick, ARM Timer, RISC-V Timer, etc.) │
|
|
|
+└─────────────────────────────────────────────┘
|
|
|
+```
|
|
|
+
|
|
|
+## Key Components
|
|
|
+
|
|
|
+### 1. Clock Time Device
|
|
|
+
|
|
|
+The `rt_clock_time_device` structure encapsulates a hardware timer with:
|
|
|
+- **ops**: Operations structure (`rt_clock_time_ops`)
|
|
|
+- **caps**: Capability flags indicating supported features
|
|
|
+- **res_scale**: Resolution scaling factor
|
|
|
+
|
|
|
+### 2. Operations Structure
|
|
|
+
|
|
|
+```c
|
|
|
+struct rt_clock_time_ops
|
|
|
+{
|
|
|
+ rt_uint64_t (*get_freq)(void); /* Get frequency in Hz */
|
|
|
+ rt_uint64_t (*get_counter)(void); /* Get current counter */
|
|
|
+ rt_err_t (*set_timeout)(rt_uint64_t delta); /* Set timeout, 0 to cancel */
|
|
|
+};
|
|
|
+```
|
|
|
+
|
|
|
+### 3. Capabilities
|
|
|
+
|
|
|
+- `RT_CLOCK_TIME_CAP_CLOCKSOURCE`: Provides free-running counter for timekeeping
|
|
|
+- `RT_CLOCK_TIME_CAP_CLOCKEVENT`: Supports programmable timeout events
|
|
|
+
|
|
|
+### 4. High-Resolution Timers
|
|
|
+
|
|
|
+The `rt_clock_hrtimer` provides:
|
|
|
+- One-shot and periodic timers
|
|
|
+- Sorted linked-list scheduling
|
|
|
+- SMP-safe spinlock protection
|
|
|
+- Fallback to software timers when hardware timeout is unavailable
|
|
|
+
|
|
|
+## Migration Guide
|
|
|
+
|
|
|
+### For BSP Developers
|
|
|
+
|
|
|
+**Old hwtimer approach:**
|
|
|
+```c
|
|
|
+static const struct rt_hwtimer_ops my_ops = { ... };
|
|
|
+static struct rt_hwtimer_device my_device;
|
|
|
+rt_device_hwtimer_register(&my_device, "timer0", RT_NULL);
|
|
|
+```
|
|
|
+
|
|
|
+**New clock_time approach:**
|
|
|
+```c
|
|
|
+static const struct rt_clock_time_ops my_ops = {
|
|
|
+ .get_freq = my_get_freq,
|
|
|
+ .get_counter = my_get_counter,
|
|
|
+ .set_timeout = my_set_timeout,
|
|
|
+};
|
|
|
+static struct rt_clock_time_device my_device;
|
|
|
+my_device.ops = &my_ops;
|
|
|
+rt_clock_time_device_register(&my_device, "timer0",
|
|
|
+ RT_CLOCK_TIME_CAP_CLOCKSOURCE | RT_CLOCK_TIME_CAP_CLOCKEVENT);
|
|
|
+```
|
|
|
+
|
|
|
+### For Application Developers
|
|
|
+
|
|
|
+**Old cputime/ktime APIs** still work when compatibility layers are enabled:
|
|
|
+- `clock_cpu_gettime()` → `rt_clock_time_getcnt()`
|
|
|
+- `rt_ktime_boottime_get_ns()` → `rt_clock_time_boottime_ns()`
|
|
|
+- `rt_ktime_hrtimer_start()` → `rt_clock_hrtimer_start()`
|
|
|
+
|
|
|
+**Recommended new APIs:**
|
|
|
+```c
|
|
|
+/* Get time information */
|
|
|
+rt_uint64_t freq = rt_clock_time_getfreq();
|
|
|
+rt_uint64_t cnt = rt_clock_time_getcnt();
|
|
|
+
|
|
|
+/* High-precision delays */
|
|
|
+rt_clock_udelay(100); /* 100 microseconds */
|
|
|
+rt_clock_mdelay(10); /* 10 milliseconds */
|
|
|
+
|
|
|
+/* High-resolution timers */
|
|
|
+struct rt_clock_hrtimer timer;
|
|
|
+rt_clock_hrtimer_init(&timer, "my_timer", RT_TIMER_FLAG_ONE_SHOT,
|
|
|
+ callback, param);
|
|
|
+rt_clock_hrtimer_start(&timer, delay_cnt);
|
|
|
+```
|
|
|
+
|
|
|
+## Compatibility Layers
|
|
|
+
|
|
|
+Three compatibility layers are provided via Kconfig:
|
|
|
+
|
|
|
+1. **RT_CLOCK_TIME_COMPAT_KTIME**: Enables ktime API compatibility
|
|
|
+2. **RT_CLOCK_TIME_COMPAT_CPUTIME**: Enables cputime API compatibility
|
|
|
+3. **RT_CLOCK_TIME_COMPAT_HWTIMER**: Enables hwtimer device API compatibility
|
|
|
+
|
|
|
+These allow gradual migration without breaking existing code.
|
|
|
+
|
|
|
+## File Structure
|
|
|
+
|
|
|
+```
|
|
|
+components/drivers/clock_time/
|
|
|
+├── Kconfig # Configuration options
|
|
|
+├── SConscript # Build script
|
|
|
+├── src/
|
|
|
+│ ├── clock_time.c # Core device management
|
|
|
+│ ├── hrtimer.c # High-resolution timer implementation
|
|
|
+│ ├── clock_time_tick.c # Tick-based fallback adapter
|
|
|
+│ ├── ktime_compat.c # ktime compatibility layer
|
|
|
+│ └── cputime_compat.c # cputime compatibility layer
|
|
|
+└── include/drivers/
|
|
|
+ └── clock_time.h # Public API header
|
|
|
+```
|
|
|
+
|
|
|
+## Testing Status
|
|
|
+
|
|
|
+- [x] Basic compilation verified
|
|
|
+- [ ] BSP integration examples created
|
|
|
+- [ ] QEMU runtime testing
|
|
|
+- [ ] CI build verification
|
|
|
+- [ ] Performance benchmarking
|
|
|
+
|
|
|
+## Known Limitations
|
|
|
+
|
|
|
+1. **Type width**: `unsigned long` is used for counter values to maintain ktime compatibility. On 32-bit systems, this limits maximum counter values. For very high-frequency timers (>4GHz), consider using 64-bit platforms or prescaling.
|
|
|
+
|
|
|
+2. **Fallback mode**: When no hardware clockevent is available, the system falls back to software timers (tick-based). This provides lower precision but ensures functionality.
|
|
|
+
|
|
|
+3. **Migration timeline**: The old subsystems are marked as deprecated but not removed to allow time for migration.
|
|
|
+
|
|
|
+## Future Work
|
|
|
+
|
|
|
+1. **Architecture-specific optimizations**: Add optimized adapters for common architectures (ARM Generic Timer, RISC-V timer, etc.)
|
|
|
+2. **Power management integration**: Better support for low-power modes with clock gating
|
|
|
+3. **Advanced scheduling**: Consider red-black tree for timer scheduling in scenarios with many concurrent timers
|
|
|
+4. **Complete migration**: Remove deprecated subsystems after all BSPs migrate
|
|
|
+
|
|
|
+## Documentation
|
|
|
+
|
|
|
+- [English Documentation](../../documentation/6.components/device-driver/clock_time.md)
|
|
|
+- [Chinese Documentation](../../documentation/6.components/device-driver/clock_time_zh.md)
|
|
|
+
|
|
|
+## Contributing
|
|
|
+
|
|
|
+When contributing to clock_time:
|
|
|
+
|
|
|
+1. Maintain backward compatibility with existing APIs
|
|
|
+2. Add tests for new functionality
|
|
|
+3. Update documentation
|
|
|
+4. Follow RT-Thread coding style
|
|
|
+5. Consider both MCU and MPU use cases
|
|
|
+
|
|
|
+## References
|
|
|
+
|
|
|
+- Issue: [Feature] 对 hwtimer/ktime/cputime 进行整体重构
|
|
|
+- Design discussion in issue comments
|
|
|
+- POSIX clock APIs: clock_gettime(2), clock_settime(2)
|
|
|
+- Linux clocksource/clockevent framework
|