README_zh.md
1# 小凌派-RK2206开发板OpenHarmonyOS内核开发-定时器
2
3## 实验内容
4
5本例程演示如何在小凌派-RK2206开发板上使用鸿蒙LiteOS-M内核接口，进行定时器编程开发。
6
7
8
9## 程序设计
10
11软件定时器，是基于系统Tick时钟中断，由软件来模拟的定时器，当经过设定的Tick时钟计数值后会触发用户定义的回调函数。定时器的精度与系统Tick时钟的周期有关。硬件定时器受硬件的限制，数量上不足以满足用户的实际需求。因此为了满足用户需求，提供更多的定时器，鸿蒙LiteOS操作系统提供软件定时器功能。
12
13软件定时器是系统资源，在模块初始化的时候已经分配了一块连续的内存。软件定时器使用了系统的一个队列和一个任务资源，软件定时器的触发遵循队列规则，先进先出。定时时间短的定时器总是比定时时间长的靠近队列头，满足优先被触发的准则。
14
15### API分析
16
17**头文件：**
18
19/kernel/liteos_m/kernel/include/los_task.h/los_swtmr.h
20
21#### LOS_SwtmrCreate()
22
23```c
24UINT32 LOS_SwtmrCreate(UINT32 interval,
25 UINT8 mode,
26 SWTMR_PROC_FUNC handler,
27 UINT32 *swtmrID,
28 UINT32 arg);
29```
30
31**描述：**
32
33创建定时器
34
35**参数：**
36
37| 名字 | 描述 |
38| :------- | :----------------- |
39| interval | 定时器超时时间 |
40| mode | 定时器模式 |
41| handler | 定时器回调函数 |
42| swtmrID | 定时器ID指针 |
43| arg | 定时器回调函数参数 |
44
45**返回值：**
46
47| 返回值 | 描述 |
48| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--- |
49| LOS_OK | 成功 |
50| LOS_ERRNO_SWTMR_INTERVAL_NOT_SUITED`<br>` LOS_ERRNO_SWTMR_MODE_INVALID `<br>` LOS_ERRNO_SWTMR_PTR_NULL `<br>` LOS_ERRNO_SWTMR_RET_PTR_NULL `<br>` LOS_ERRNO_SWTMR_MAXSIZE | 失败 |
51
52#### LOS_SwtmrDelete()
53
54```c
55UINT32 LOS_SwtmrDelete(UINT32 swtmrID);
56```
57
58**描述：**
59
60删除定时器
61
62**参数：**
63
64| 名字 | 描述 |
65| :------ | :------- |
66| swtmrID | 定时器ID |
67
68**返回值：**
69
70| 返回值 | 描述 |
71| :----------------------------------------------------------------------------------------------------- | :--- |
72| LOS_OK | 成功 |
73| LOS_ERRNO_SWTMR_ID_INVALID`<br>` LOS_ERRNO_SWTMR_NOT_CREATED `<br>` LOS_ERRNO_SWTMR_STATUS_INVALID | 失败 |
74
75#### LOS_SwtmrStart()
76
77```c
78UINT32 LOS_SwtmrStart(UINT32 swtmrID);
79```
80
81**描述：**
82
83启动定时器
84
85**参数：**
86
87| 名字 | 描述 |
88| :------ | :------- |
89| swtmrID | 定时器ID |
90
91**返回值：**
92
93| 返回值 | 描述 |
94| :----------------------------------------------------------------------------------------------------- | :--- |
95| LOS_OK | 成功 |
96| LOS_ERRNO_SWTMR_ID_INVALID`<br>` LOS_ERRNO_SWTMR_NOT_CREATED `<br>` LOS_ERRNO_SWTMR_STATUS_INVALID | 失败 |
97
98#### LOS_SwtmrStop()
99
100```c
101UINT32 LOS_SwtmrStop(UINT32 swtmrID);
102```
103
104**描述：**
105
106停止定时器
107
108**参数：**
109
110| 名字 | 描述 |
111| :------ | :------- |
112| swtmrID | 定时器ID |
113
114**返回值：**
115
116| 返回值 | 描述 |
117| :------------------------------------------------------------------------------------------------------------------------------------------ | :--- |
118| LOS_OK | 成功 |
119| LOS_ERRNO_SWTMR_ID_INVALID`<br>` LOS_ERRNO_SWTMR_NOT_CREATED `<br>` LOS_ERRNO_SWTMR_NOT_STARTED `<br>` LOS_ERRNO_SWTMR_STATUS_INVALID | 失败 |
120
121### 软件设计
122
123**主要代码分析**
124
125在timer_example函数中，通过LOS_SwtmrCreate函数创建定时器1和定时器2，并通过LOS_SwtmrStart函数启动定时器1和定时器2。1S超时后会触发Timer1_Timeout函数并打印日志；2S超时后会触发Timer2_Timeout函数并打印日志。
126
127```c
128void timer_example()
129{
130 unsigned int timer_id1, timer_id2;
131 unsigned int ret;
132
133 ret = LOS_SwtmrCreate(1000, LOS_SWTMR_MODE_PERIOD, timer1_timeout, &timer_id1, NULL);
134 if (ret == LOS_OK)
135 {
136 ret = LOS_SwtmrStart(timer_id1);
137 if (ret != LOS_OK)
138 {
139 printf("start timer1 fail ret:0x%x\n", ret);
140 return;
141 }
142 }
143 else
144 {
145 printf("create timer1 fail ret:0x%x\n", ret);
146 return;
147 }
148
149 ret = LOS_SwtmrCreate(2000, LOS_SWTMR_MODE_PERIOD, timer2_timeout, &timer_id2, NULL);
150 if (ret == LOS_OK)
151 {
152 ret = LOS_SwtmrStart(timer_id2);
153 if (ret != LOS_OK)
154 {
155 printf("start timer2 fail ret:0x%x\n", ret);
156 return;
157 }
158 }
159 else
160 {
161 printf("create timer2 fail ret:0x%x\n"), ret;
162 return;
163 }
164}
165
166void timer1_timeout(void)
167{
168 printf("This is Timer1 Timeout function\n");
169}
170
171void timer2_timeout(void)
172{
173 printf("This is Timer2 Timeout function\n");
174}
175```
176
177## 编译调试
178
179### 修改 BUILD.gn 文件
180
181修改 `vendor/lockzhiner/lingpi/sample` 路径下 BUILD.gn 文件，指定 `a3_kernel_timer` 参与编译。
182
183```r
184"a3_kernel_timer",
185```
186
187在主目录下输入编译命令。
188
189```shell
190hb build -f
191```
192
193### 运行结果
194
195例程代码编译烧写到开发板后，按下开发板的RESET按键，通过串口软件查看日志，Timer1_Timeout函数会1秒打印一次日志，Timer2_Timeout函数会2秒打印一次日志。
196
197```r
198This is Timer1 Timeout function
199This is Timer1 Timeout function
200This is Timer2 Timeout function
201This is Timer1 Timeout function
202This is Timer1 Timeout function
203This is Timer2 Timeout function
204```
205
