diff --git a/docs/doc/kernel/imagesrc/tmr_config.png b/docs/doc/kernel/imagesrc/tmr_config.png new file mode 100644 index 0000000..c98920c Binary files /dev/null and b/docs/doc/kernel/imagesrc/tmr_config.png differ diff --git a/docs/doc/kernel/imagesrc/tmr_process.png b/docs/doc/kernel/imagesrc/tmr_process.png new file mode 100644 index 0000000..74b85cc Binary files /dev/null and b/docs/doc/kernel/imagesrc/tmr_process.png differ diff --git a/docs/doc/kernel/tmr.md b/docs/doc/kernel/tmr.md index ba6f687..ed148f9 100644 --- a/docs/doc/kernel/tmr.md +++ b/docs/doc/kernel/tmr.md @@ -1 +1,149 @@ -# 节拍机制 \ No newline at end of file +# 节拍机制 + +## 简介 +每一个操作系统都需要一个时钟计数,提供“心跳”计数,该时钟可以提供系统处理所有和时钟相关的事件。 +XiUOS的“心跳”通过芯片提供的硬件定时器产生的周期性中断进行计数,XiUOS可以在menuconfig界面进行配置,配置单位为毫秒。 +配置界面如下 + + + +界面中的数值将配置给变量XS_TICK_PER_SECOND,该变量解释为每秒钟支持的节拍数(tick)。例如,XS_TICK_PER_SECOND +配置为100,则tick节拍表示10毫秒,即一个时间片(timeslice)为10毫秒。 +当节拍配置成功后,系统支持的调度算法、软件定时器等依赖于该时钟周期服务的事件就可以正常工作了。例如,在XiUOS支持 +的时间片轮转算法当中,每进行的一次线程切换为一个tick(10ms)。 + +节拍计数执行流程如下图所示 + + + +在每一个定时器中断到来时,进行常规的中断执行流,定时器按照每一个tick单位进行触发中断,在中断服务程序当中进行自增,并对当前运行线程的时间片进行计算;同步可处理定时器的计数时间。 + +## 函数接口 + +```c +xs_ticks_x xs_CalculteTickFromTimeMs(xs_uint32 time_ms); +``` +该函数用于获取毫秒时间转化成节拍数。 + +| 参数 | 描述 | +| --- | --- | +| time_ms | 毫秒时间 | +```c +xs_uint32 xs_CalculteTimeMsFromTick(xs_ticks_x ticks); +``` +该函数用于获取节拍数转换成毫秒时间。 + +| 参数 | 描述 | +| --- | --- | +| ticks | 节拍数 | +```c +xs_uint32 xs_CurrentTicksGain(void); +``` +该函数用于获取当前的时钟节拍数。 + +## 定时器机制 +软件定时器模块根据系统的节拍心跳(tick)提供软件定时服务,用户可以设定固定的超时时间, +当系统运行的节拍数到达用户设定的超时时间时,便执行用户定义的超时回调函数进行业务处理。 +软件定时器的存在可以解决硬件定时器数量不足的问题。 + +### 软件定时器结构定义 +```c +#define TRIGGE_WAY_ONCE (1 << 0) +#define TRIGGE_WAY_PERIODIC (1 << 1) + +struct xs_Timer +{ + xs_uint8 id; ///< 定时器的ID + xs_uint8 trigge_mode; ///< 单次触发还是周期触发 + void (*func_callback)(void *param); ///< 定时器回调函数 + void *param; ///< 定时器回调函数的参数 + xs_tick_x origin_timeslice; ///< 超时时间 + xs_tick_x deadline_timeslice; ///< 截止时间 + XS_DOUBLE_LINKLIST link; ///< 管理链表 + XS_DOUBLE_LINKLIST levels[XS_TIMER_SKIP_LIST_LEVEL]; ///< 查询链表 +}; +typedef struct xs_Timer *xs_timer_x; +``` +| 成员 | 描述 | +| --- | --- | +| id | 软件定时器ID,用于唯一标识一个软件定时器 | +| trigge_mode | 定时器的触发模式,包含单次触发和周期触发两种方式 | +| func_callback | 定时器超时回调函数 | +| param | 定时器超时回调函数的参数 | +| origin_timeslice | 初始化的超时时间 | +| deadline_timeslice | 截止时间 | +| link | 系统中所有定时器构成的链表 | +| levels | 查询链表 | + +### 软件定时器接口 +定时器用户操作结构体定义如下: + +```c +#define TRIGGE_WAY_ONCE (1 << 0) +#define TRIGGE_WAY_PERIODIC (1 << 1) + +struct xs_utimer +{ + xs_uint8 trigge_way; ///< 触发方式,包括单次触发和周期触发方式 + void (*func_callback)(void *param); ///< 超时回调函数 + void *func_param; ///< 回调函数的参数 + xs_tick_x ticks; ///< 定时时间,单位为 tick +}; +typedef struct xs_utimer xs_utimer_x; +``` +| 成员 | 描述 | +| --- | --- | +| trigge_way | 触发方式,可以配置为宏TRIGGE_WAY_ONCE和TRIGGE_WAY_PERIODIC | +| func_callback | 软件定时器回调函数 | +| func_param | 软件定时器回调函数参数 | +| ticks | 配置需要等待的超时时间 | + +```c +xs_int32 xs_UserTimerCreate(xs_utimer_x* timer); +``` +该函数用于创建一个软件定时器,并返回创建成功的软件定时器的ID,ID默认范围0-255,可配置。 + +| 参数 | 描述 | +| --- | --- | +| timer | 软件定时器初始化结构体 | + +```c +void xs_UserTimerDelete(xs_uint16 id); +``` +该函数用于删除一个软件定时器。 + +| 参数 | 描述 | +| --- | --- | +| id | 待删除的软件定时器ID | + +```c +xs_int32 xs_UserTimerStartRun(xs_uint16 id); +``` +该函数用于启动一个软件定时器。 + +| 参数 | 描述 | +| --- | --- | +| id | 已创建且待运行的软件定时器ID | + +```c +xs_int32 xs_UserTimerQuitRun(xs_uint16 id); +``` +该函数用于停止一个软件定时器。 + +| 参数 | 描述 | +| --- | --- | +| id | 待停止运行的软件定时器ID | + +```c +xs_int32 xs_UserTimerModify(xs_uint16 id, xs_tick_x ticks); +``` +该函数用于修改一个软件定时器的超时时间。 + +| 参数 | 描述 | +| --- | --- | +| id | 待修改超时时间的软件定时器ID | +| ticks | 超时时间 | + +```c +struct xs_Timer* xs_UserTimerSearch(xs_uint16 id); +```