README.md
1# BearPi-HM_Nano开发板OpenHarmony内核编程开发——互斥锁
2本示例将演示如何在BearPi-HM_Nano开发板上使用cmsis 2.0 接口使用互斥来同步任务。
3
4
5## Mutex API分析
6
7
8### osMutexNew()
9
10```c
11osMutexId_t osMutexNew(const osMutexAttr_t *attr)
12```
13**描述：**
14
15函数osMutexNew创建并初始化一个新的互斥锁对象，并返回指向互斥锁对象标识符的指针，如果出现错误则返回NULL可以在RTOS启动(调用 osKernelStart)之前安全地调用该函数，但不能在内核初始化 (调用 osKernelInitialize)之前调用该函数。
16> **注意** :不能在中断服务调用该函数。
17
18
19**参数：**
20
21|参数名|描述|
22|:--|:------|
23| attr |互斥对象的属性。 |
24
25### osMutexAcquire()
26
27```c
28osStatus_t osMutexAcquire(osMutexId_t mutex_id,uint32_t timeout)
29```
30**描述：**
31函数osMutexAcquire一直等待，直到参数mutex_id指定的互斥对象可用为止。如果没有其余线程获得互斥锁，该函数立即返回并阻塞互斥锁对象。
32
33> **注意** :不能在中断服务调用该函数。
34
35
36**参数：**
37
38|参数名|描述|
39|:--|:------|
40| mutex_id | 通过osMutexNew获得互斥锁ID。 |
41| timeout | 超时值。 |
42
43### osMutexRelease()
44
45```c
46osStatus_t osMutexRelease(osMutexId_t mutex_id)
47```
48**描述：**
49函数osMutexRelease释放一个由参数mutex_id指定的互斥量。当前等待这个互斥锁的其余线程将被置于就绪状态。
50
51> **注意** :不能从中断服务例程调用此函数。
52
53
54**参数：**
55
56|参数名|描述|
57|:--|:------|
58| mutex_id | 通过osMutexNew获得互斥锁ID。 |
59
60
61## 软件设计
62
63**主要代码分析**
64
65在MutexExample函数中，通过osMutexNew()函数创建了互斥锁ID，并创建的三个不同优先级的任务，在第一秒，高优先级和中优先级线程被延迟。因此，低优先级线程可以启动自己的工作，获得互斥锁并在持有它时延迟。在第一秒之后，高优先级和中优先级线程就准备好了。因此高优先级线程获得优先级并尝试获取互斥锁。因为互斥锁已经被低优先级线程所拥有，所以高优先级线程被阻塞，中间优先级线程被执行，并开始执行许多非阻塞的工作，3S后低优先级释放互斥锁，高优先级线程准备就绪并立即被调度。
66
67```c
68void HighPrioThread(void)
69{
70 // wait 1s until start actual work
71 osDelay(THREAD_DELAY_1S);
72
73 while (1) {
74 // try to acquire mutex
75 osMutexAcquire(g_mutexId, osWaitForever);
76
77 printf("HighPrioThread is running.\n");
78 osDelay(THREAD_DELAY_3S);
79 osMutexRelease(g_mutexId);
80 }
81}
82
83void MidPrioThread(void)
84{
85 // wait 1s until start actual work
86 osDelay(THREAD_DELAY_1S);
87
88 while (1) {
89 printf("MidPrioThread is running.\n");
90 osDelay(THREAD_DELAY_1S);
91 }
92}
93
94void LowPrioThread(void)
95{
96 while (1) {
97 osMutexAcquire(g_mutexId, osWaitForever);
98 printf("LowPrioThread is running.\n");
99
100 // block mutex for 3s
101 osDelay(THREAD_DELAY_3S);
102 osMutexRelease(g_mutexId);
103 }
104}
105
106/**
107 * @brief Main Entry of the Mutex Example
108 *
109 */
110void MutexExample(void)
111{
112 osThreadAttr_t attr;
113
114 attr.attr_bits = 0U;
115 attr.cb_mem = NULL;
116 attr.cb_size = 0U;
117 attr.stack_mem = NULL;
118 attr.stack_size = THREAD_STACK_SIZE;
119
120 attr.name = "HighPrioThread";
121 attr.priority = HIGH_THREAD_PRIO;
122 if (osThreadNew((osThreadFunc_t)HighPrioThread, NULL, &attr) == NULL) {
123 printf("Failed to create HighPrioThread!\n");
124 }
125
126 attr.name = "MidPrioThread";
127 attr.priority = MID_THREAD_PRIO;
128 if (osThreadNew((osThreadFunc_t)MidPrioThread, NULL, &attr) == NULL) {
129 printf("Failed to create MidPrioThread!\n");
130 }
131
132 attr.name = "LowPrioThread";
133 attr.priority = LOW_THREAD_PRIO;
134 if (osThreadNew((osThreadFunc_t)LowPrioThread, NULL, &attr) == NULL) {
135 printf("Failed to create LowPrioThread!\n");
136 }
137
138 g_mutexId = osMutexNew(NULL);
139 if (g_mutexId == NULL) {
140 printf("Failed to create Mutex!\n");
141 }
142}
143```
144
145## 编译调试
146
147### 修改 BUILD.gn 文件
148
149修改 `device\bearpi\bearpi_hm_nano\app`路径下 BUILD.gn 文件，指定 `mutex_example` 参与编译。
150
151```r
152#"A1_kernal_thread:thread_example",
153#"A2_kernel_timer:timer_example",
154#"A3_kernel_event:event_example",
155"A4_kernel_mutex:mutex_example",
156#"A5_kernel_semaphore:semaphore_example",
157#"A6_kernel_message:message_example",
158```
159
160
161
162### 运行结果
163
164示例代码编译烧录代码后，按下开发板的RESET按键，通过串口助手查看日志，中优先级任务一直正常运行，而高优先级和低优先级的任务因为互相抢占互斥锁，交替运行。
165```c
166LowPrioThread is runing.
167MidPrioThread is runing.
168MidPrioThread is runing.
169MidPrioThread is runing.
170HighPrioThread is runing.
171MidPrioThread is runing.
172MidPrioThread is runing.
173MidPrioThread is runing.
174LowPrioThread is runing.
175MidPrioThread is runing.
176MidPrioThread is runing.
177MidPrioThread is runing.
178HighPrioThread is runing.
179MidPrioThread is runing.
180MidPrioThread is runing.
181MidPrioThread is runing
182```
183