LPCOpen Platform  v1.03
LPCOpen Platform for NXP LPC Microcontrollers
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
os_mutex.c
Go to the documentation of this file.
1 /*
2 ************************************************************************************************************************
3 * uC/OS-III
4 * The Real-Time Kernel
5 *
6 * (c) Copyright 2009-2012; Micrium, Inc.; Weston, FL
7 * All rights reserved. Protected by international copyright laws.
8 *
9 * MUTEX MANAGEMENT
10 *
11 * File : OS_MUTEX.C
12 * By : JJL
13 * Version : V3.03.00
14 *
15 * LICENSING TERMS:
16 * ---------------
17 * uC/OS-III is provided in source form for FREE short-term evaluation, for educational use or
18 * for peaceful research. If you plan or intend to use uC/OS-III in a commercial application/
19 * product then, you need to contact Micrium to properly license uC/OS-III for its use in your
20 * application/product. We provide ALL the source code for your convenience and to help you
21 * experience uC/OS-III. The fact that the source is provided does NOT mean that you can use
22 * it commercially without paying a licensing fee.
23 *
24 * Knowledge of the source code may NOT be used to develop a similar product.
25 *
26 * Please help us continue to provide the embedded community with the finest software available.
27 * Your honesty is greatly appreciated.
28 *
29 * You can contact us at www.micrium.com, or by phone at +1 (954) 217-2036.
30 ************************************************************************************************************************
31 */
32 
33 #define MICRIUM_SOURCE
34 #include <os.h>
35 
36 #ifdef VSC_INCLUDE_SOURCE_FILE_NAMES
37 const CPU_CHAR *os_mutex__c = "$Id: $";
38 #endif
39 
40 
41 #if OS_CFG_MUTEX_EN > 0u
42 /*
43 ************************************************************************************************************************
44 * CREATE A MUTEX
45 *
46 * Description: This function creates a mutex.
47 *
48 * Arguments : p_mutex is a pointer to the mutex to initialize. Your application is responsible for allocating
49 * storage for the mutex.
50 *
51 * p_name is a pointer to the name you would like to give the mutex.
52 *
53 * p_err is a pointer to a variable that will contain an error code returned by this function.
54 *
55 * OS_ERR_NONE if the call was successful
56 * OS_ERR_CREATE_ISR if you called this function from an ISR
57 * OS_ERR_ILLEGAL_CREATE_RUN_TIME if you are trying to create the Mutex after you called
58 * OSSafetyCriticalStart().
59 * OS_ERR_NAME if 'p_name' is a NULL pointer
60 * OS_ERR_OBJ_CREATED if the mutex has already been created
61 * OS_ERR_OBJ_PTR_NULL if 'p_mutex' is a NULL pointer
62 *
63 * Returns : none
64 ************************************************************************************************************************
65 */
66 
67 void OSMutexCreate (OS_MUTEX *p_mutex,
68  CPU_CHAR *p_name,
69  OS_ERR *p_err)
70 {
71  CPU_SR_ALLOC();
72 
73 
74 
75 #ifdef OS_SAFETY_CRITICAL
76  if (p_err == (OS_ERR *)0) {
77  OS_SAFETY_CRITICAL_EXCEPTION();
78  return;
79  }
80 #endif
81 
82 #ifdef OS_SAFETY_CRITICAL_IEC61508
83  if (OSSafetyCriticalStartFlag == DEF_TRUE) {
84  *p_err = OS_ERR_ILLEGAL_CREATE_RUN_TIME;
85  return;
86  }
87 #endif
88 
89 #if OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u
90  if (OSIntNestingCtr > (OS_NESTING_CTR)0) { /* Not allowed to be called from an ISR */
91  *p_err = OS_ERR_CREATE_ISR;
92  return;
93  }
94 #endif
95 
96 #if OS_CFG_ARG_CHK_EN > 0u
97  if (p_mutex == (OS_MUTEX *)0) { /* Validate 'p_mutex' */
98  *p_err = OS_ERR_OBJ_PTR_NULL;
99  return;
100  }
101 #endif
102 
103  OS_CRITICAL_ENTER();
104  p_mutex->Type = OS_OBJ_TYPE_MUTEX; /* Mark the data structure as a mutex */
105  p_mutex->NamePtr = p_name;
106  p_mutex->OwnerTCBPtr = (OS_TCB *)0;
107  p_mutex->OwnerNestingCtr = (OS_NESTING_CTR)0; /* Mutex is available */
108  p_mutex->TS = (CPU_TS )0;
109  p_mutex->OwnerOriginalPrio = OS_CFG_PRIO_MAX;
110  OS_PendListInit(&p_mutex->PendList); /* Initialize the waiting list */
111 
112 #if OS_CFG_DBG_EN > 0u
113  OS_MutexDbgListAdd(p_mutex);
114 #endif
115  OSMutexQty++;
116 
117  OS_CRITICAL_EXIT_NO_SCHED();
118  *p_err = OS_ERR_NONE;
119 }
120 
121 /*$PAGE*/
122 /*
123 ************************************************************************************************************************
124 * DELETE A MUTEX
125 *
126 * Description: This function deletes a mutex and readies all tasks pending on the mutex.
127 *
128 * Arguments : p_mutex is a pointer to the mutex to delete
129 *
130 * opt determines delete options as follows:
131 *
132 * OS_OPT_DEL_NO_PEND Delete mutex ONLY if no task pending
133 * OS_OPT_DEL_ALWAYS Deletes the mutex even if tasks are waiting.
134 * In this case, all the tasks pending will be readied.
135 *
136 * p_err is a pointer to a variable that will contain an error code returned by this function.
137 *
138 * OS_ERR_NONE The call was successful and the mutex was deleted
139 * OS_ERR_DEL_ISR If you attempted to delete the mutex from an ISR
140 * OS_ERR_OBJ_PTR_NULL If 'p_mutex' is a NULL pointer.
141 * OS_ERR_OBJ_TYPE If 'p_mutex' is not pointing to a mutex
142 * OS_ERR_OPT_INVALID An invalid option was specified
143 * OS_ERR_STATE_INVALID Task is in an invalid state
144 * OS_ERR_TASK_WAITING One or more tasks were waiting on the mutex
145 *
146 * Returns : == 0 if no tasks were waiting on the mutex, or upon error.
147 * > 0 if one or more tasks waiting on the mutex are now readied and informed.
148 *
149 * Note(s) : 1) This function must be used with care. Tasks that would normally expect the presence of the mutex MUST
150 * check the return code of OSMutexPend().
151 *
152 * 2) OSMutexAccept() callers will not know that the intended mutex has been deleted.
153 *
154 * 3) Because ALL tasks pending on the mutex will be readied, you MUST be careful in applications where the
155 * mutex is used for mutual exclusion because the resource(s) will no longer be guarded by the mutex.
156 ************************************************************************************************************************
157 */
158 
159 #if OS_CFG_MUTEX_DEL_EN > 0u
160 OS_OBJ_QTY OSMutexDel (OS_MUTEX *p_mutex,
161  OS_OPT opt,
162  OS_ERR *p_err)
163 {
164  OS_OBJ_QTY cnt;
165  OS_OBJ_QTY nbr_tasks;
166  OS_PEND_DATA *p_pend_data;
167  OS_PEND_LIST *p_pend_list;
168  OS_TCB *p_tcb;
169  OS_TCB *p_tcb_owner;
170  CPU_TS ts;
171  CPU_SR_ALLOC();
172 
173 
174 
175 #ifdef OS_SAFETY_CRITICAL
176  if (p_err == (OS_ERR *)0) {
177  OS_SAFETY_CRITICAL_EXCEPTION();
178  return ((OS_OBJ_QTY)0);
179  }
180 #endif
181 
182 #if OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u
183  if (OSIntNestingCtr > (OS_NESTING_CTR)0) { /* Not allowed to delete a mutex from an ISR */
184  *p_err = OS_ERR_DEL_ISR;
185  return ((OS_OBJ_QTY)0);
186  }
187 #endif
188 
189 #if OS_CFG_ARG_CHK_EN > 0u
190  if (p_mutex == (OS_MUTEX *)0) { /* Validate 'p_mutex' */
191  *p_err = OS_ERR_OBJ_PTR_NULL;
192  return ((OS_OBJ_QTY)0);
193  }
194  switch (opt) { /* Validate 'opt' */
195  case OS_OPT_DEL_NO_PEND:
196  case OS_OPT_DEL_ALWAYS:
197  break;
198 
199  default:
200  *p_err = OS_ERR_OPT_INVALID;
201  return ((OS_OBJ_QTY)0);
202  }
203 #endif
204 
205 #if OS_CFG_OBJ_TYPE_CHK_EN > 0u
206  if (p_mutex->Type != OS_OBJ_TYPE_MUTEX) { /* Make sure mutex was created */
207  *p_err = OS_ERR_OBJ_TYPE;
208  return ((OS_OBJ_QTY)0);
209  }
210 #endif
211 
212  OS_CRITICAL_ENTER();
213  p_pend_list = &p_mutex->PendList;
214  cnt = p_pend_list->NbrEntries;
215  nbr_tasks = cnt;
216  switch (opt) {
217  case OS_OPT_DEL_NO_PEND: /* Delete mutex only if no task waiting */
218  if (nbr_tasks == (OS_OBJ_QTY)0) {
219 #if OS_CFG_DBG_EN > 0u
220  OS_MutexDbgListRemove(p_mutex);
221 #endif
222  OSMutexQty--;
223  OS_MutexClr(p_mutex);
224  OS_CRITICAL_EXIT();
225  *p_err = OS_ERR_NONE;
226  } else {
227  OS_CRITICAL_EXIT();
228  *p_err = OS_ERR_TASK_WAITING;
229  }
230  break;
231 
232  case OS_OPT_DEL_ALWAYS: /* Always delete the mutex */
233  p_tcb_owner = p_mutex->OwnerTCBPtr; /* Did we had to change the prio of owner? */
234  if ((p_tcb_owner != (OS_TCB *)0) &&
235  (p_tcb_owner->Prio != p_mutex->OwnerOriginalPrio)) {
236  switch (p_tcb_owner->TaskState) { /* yes */
237  case OS_TASK_STATE_RDY:
238  OS_RdyListRemove(p_tcb_owner);
239  p_tcb_owner->Prio = p_mutex->OwnerOriginalPrio; /* Lower owner's prio back */
240  OS_PrioInsert(p_tcb_owner->Prio);
241  OS_RdyListInsertTail(p_tcb_owner); /* Insert owner in ready list at new prio */
242  break;
243 
244  case OS_TASK_STATE_DLY:
245  case OS_TASK_STATE_SUSPENDED:
246  case OS_TASK_STATE_DLY_SUSPENDED:
247  p_tcb_owner->Prio = p_mutex->OwnerOriginalPrio; /* Not in any pend list, change the prio */
248  break;
249 
250  case OS_TASK_STATE_PEND:
251  case OS_TASK_STATE_PEND_TIMEOUT:
252  case OS_TASK_STATE_PEND_SUSPENDED:
253  case OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED:
254  OS_PendListChangePrio(p_tcb_owner, /* Owner is pending on another object */
255  p_mutex->OwnerOriginalPrio);
256  break;
257 
258  default:
259  OS_CRITICAL_EXIT();
260  *p_err = OS_ERR_STATE_INVALID;
261  return ((OS_OBJ_QTY)0);
262  }
263  }
264 
265  ts = OS_TS_GET(); /* Get timestamp */
266  while (cnt > 0u) { /* Remove all tasks from the pend list */
267  p_pend_data = p_pend_list->HeadPtr;
268  p_tcb = p_pend_data->TCBPtr;
269  OS_PendObjDel((OS_PEND_OBJ *)((void *)p_mutex),
270  p_tcb,
271  ts);
272  cnt--;
273  }
274 #if OS_CFG_DBG_EN > 0u
275  OS_MutexDbgListRemove(p_mutex);
276 #endif
277  OSMutexQty--;
278  OS_MutexClr(p_mutex);
279  OS_CRITICAL_EXIT_NO_SCHED();
280  OSSched(); /* Find highest priority task ready to run */
281  *p_err = OS_ERR_NONE;
282  break;
283 
284  default:
285  OS_CRITICAL_EXIT();
286  *p_err = OS_ERR_OPT_INVALID;
287  break;
288  }
289  return (nbr_tasks);
290 }
291 #endif
292 
293 /*$PAGE*/
294 /*
295 ************************************************************************************************************************
296 * PEND ON MUTEX
297 *
298 * Description: This function waits for a mutex.
299 *
300 * Arguments : p_mutex is a pointer to the mutex
301 *
302 * timeout is an optional timeout period (in clock ticks). If non-zero, your task will wait for the
303 * resource up to the amount of time (in 'ticks') specified by this argument. If you specify
304 * 0, however, your task will wait forever at the specified mutex or, until the resource
305 * becomes available.
306 *
307 * opt determines whether the user wants to block if the mutex is not available or not:
308 *
309 * OS_OPT_PEND_BLOCKING
310 * OS_OPT_PEND_NON_BLOCKING
311 *
312 * p_ts is a pointer to a variable that will receive the timestamp of when the mutex was posted or
313 * pend aborted or the mutex deleted. If you pass a NULL pointer (i.e. (CPU_TS *)0) then you
314 * will not get the timestamp. In other words, passing a NULL pointer is valid and indicates
315 * that you don't need the timestamp.
316 *
317 * p_err is a pointer to a variable that will contain an error code returned by this function.
318 *
319 * OS_ERR_NONE The call was successful and your task owns the resource
320 * OS_ERR_MUTEX_OWNER If calling task already owns the mutex
321 * OS_ERR_OBJ_DEL If 'p_mutex' was deleted
322 * OS_ERR_OBJ_PTR_NULL If 'p_mutex' is a NULL pointer.
323 * OS_ERR_OBJ_TYPE If 'p_mutex' is not pointing at a mutex
324 * OS_ERR_OPT_INVALID If you didn't specify a valid option
325 * OS_ERR_PEND_ABORT If the pend was aborted by another task
326 * OS_ERR_PEND_ISR If you called this function from an ISR and the result
327 * would lead to a suspension.
328 * OS_ERR_PEND_WOULD_BLOCK If you specified non-blocking but the mutex was not
329 * available.
330 * OS_ERR_SCHED_LOCKED If you called this function when the scheduler is locked
331 * OS_ERR_STATE_INVALID If the task is in an invalid state
332 * OS_ERR_STATUS_INVALID If the pend status has an invalid value
333 * OS_ERR_TIMEOUT The mutex was not received within the specified timeout.
334 *
335 * Returns : none
336 ************************************************************************************************************************
337 */
338 
339 void OSMutexPend (OS_MUTEX *p_mutex,
340  OS_TICK timeout,
341  OS_OPT opt,
342  CPU_TS *p_ts,
343  OS_ERR *p_err)
344 {
345  OS_PEND_DATA pend_data;
346  OS_TCB *p_tcb;
347  CPU_SR_ALLOC();
348 
349 
350 
351 #ifdef OS_SAFETY_CRITICAL
352  if (p_err == (OS_ERR *)0) {
353  OS_SAFETY_CRITICAL_EXCEPTION();
354  return;
355  }
356 #endif
357 
358 #if OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u
359  if (OSIntNestingCtr > (OS_NESTING_CTR)0) { /* Not allowed to call from an ISR */
360  *p_err = OS_ERR_PEND_ISR;
361  return;
362  }
363 #endif
364 
365 #if OS_CFG_ARG_CHK_EN > 0u
366  if (p_mutex == (OS_MUTEX *)0) { /* Validate arguments */
367  *p_err = OS_ERR_OBJ_PTR_NULL;
368  return;
369  }
370  switch (opt) { /* Validate 'opt' */
371  case OS_OPT_PEND_BLOCKING:
372  case OS_OPT_PEND_NON_BLOCKING:
373  break;
374 
375  default:
376  *p_err = OS_ERR_OPT_INVALID;
377  return;
378  }
379 #endif
380 
381 #if OS_CFG_OBJ_TYPE_CHK_EN > 0u
382  if (p_mutex->Type != OS_OBJ_TYPE_MUTEX) { /* Make sure mutex was created */
383  *p_err = OS_ERR_OBJ_TYPE;
384  return;
385  }
386 #endif
387 
388  if (p_ts != (CPU_TS *)0) {
389  *p_ts = (CPU_TS )0; /* Initialize the returned timestamp */
390  }
391 
392  CPU_CRITICAL_ENTER();
393  if (p_mutex->OwnerNestingCtr == (OS_NESTING_CTR)0) { /* Resource available? */
394  p_mutex->OwnerTCBPtr = OSTCBCurPtr; /* Yes, caller may proceed */
395  p_mutex->OwnerOriginalPrio = OSTCBCurPtr->Prio;
396  p_mutex->OwnerNestingCtr = (OS_NESTING_CTR)1;
397  if (p_ts != (CPU_TS *)0) {
398  *p_ts = p_mutex->TS;
399  }
400  CPU_CRITICAL_EXIT();
401  *p_err = OS_ERR_NONE;
402  return;
403  }
404 
405  if (OSTCBCurPtr == p_mutex->OwnerTCBPtr) { /* See if current task is already the owner of the mutex */
406  p_mutex->OwnerNestingCtr++;
407  if (p_ts != (CPU_TS *)0) {
408  *p_ts = p_mutex->TS;
409  }
410  CPU_CRITICAL_EXIT();
411  *p_err = OS_ERR_MUTEX_OWNER; /* Indicate that current task already owns the mutex */
412  return;
413  }
414 
415  if ((opt & OS_OPT_PEND_NON_BLOCKING) != (OS_OPT)0) { /* Caller wants to block if not available? */
416  CPU_CRITICAL_EXIT();
417  *p_err = OS_ERR_PEND_WOULD_BLOCK; /* No */
418  return;
419  } else {
420  if (OSSchedLockNestingCtr > (OS_NESTING_CTR)0) { /* Can't pend when the scheduler is locked */
421  CPU_CRITICAL_EXIT();
422  *p_err = OS_ERR_SCHED_LOCKED;
423  return;
424  }
425  }
426 
427  OS_CRITICAL_ENTER_CPU_CRITICAL_EXIT(); /* Lock the scheduler/re-enable interrupts */
428  p_tcb = p_mutex->OwnerTCBPtr; /* Point to the TCB of the Mutex owner */
429  if (p_tcb->Prio > OSTCBCurPtr->Prio) { /* See if mutex owner has a lower priority than current */
430  switch (p_tcb->TaskState) {
431  case OS_TASK_STATE_RDY:
432  OS_RdyListRemove(p_tcb); /* Remove from ready list at current priority */
433  p_tcb->Prio = OSTCBCurPtr->Prio; /* Raise owner's priority */
434  OS_PrioInsert(p_tcb->Prio);
435  OS_RdyListInsertHead(p_tcb); /* Insert in ready list at new priority */
436  break;
437 
438  case OS_TASK_STATE_DLY:
439  case OS_TASK_STATE_DLY_SUSPENDED:
440  case OS_TASK_STATE_SUSPENDED:
441  p_tcb->Prio = OSTCBCurPtr->Prio; /* Only need to raise the owner's priority */
442  break;
443 
444  case OS_TASK_STATE_PEND: /* Change the position of the task in the wait list */
445  case OS_TASK_STATE_PEND_TIMEOUT:
446  case OS_TASK_STATE_PEND_SUSPENDED:
447  case OS_TASK_STATE_PEND_TIMEOUT_SUSPENDED:
448  OS_PendListChangePrio(p_tcb,
449  OSTCBCurPtr->Prio);
450  break;
451 
452  default:
453  OS_CRITICAL_EXIT();
454  *p_err = OS_ERR_STATE_INVALID;
455  return;
456  }
457  }
458 
459  OS_Pend(&pend_data, /* Block task pending on Mutex */
460  (OS_PEND_OBJ *)((void *)p_mutex),
461  OS_TASK_PEND_ON_MUTEX,
462  timeout);
463 
464  OS_CRITICAL_EXIT_NO_SCHED();
465 
466  OSSched(); /* Find the next highest priority task ready to run */
467 
468  CPU_CRITICAL_ENTER();
469  switch (OSTCBCurPtr->PendStatus) {
470  case OS_STATUS_PEND_OK: /* We got the mutex */
471  if (p_ts != (CPU_TS *)0) {
472  *p_ts = OSTCBCurPtr->TS;
473  }
474  *p_err = OS_ERR_NONE;
475  break;
476 
477  case OS_STATUS_PEND_ABORT: /* Indicate that we aborted */
478  if (p_ts != (CPU_TS *)0) {
479  *p_ts = OSTCBCurPtr->TS;
480  }
481  *p_err = OS_ERR_PEND_ABORT;
482  break;
483 
484  case OS_STATUS_PEND_TIMEOUT: /* Indicate that we didn't get mutex within timeout */
485  if (p_ts != (CPU_TS *)0) {
486  *p_ts = (CPU_TS )0;
487  }
488  *p_err = OS_ERR_TIMEOUT;
489  break;
490 
491  case OS_STATUS_PEND_DEL: /* Indicate that object pended on has been deleted */
492  if (p_ts != (CPU_TS *)0) {
493  *p_ts = OSTCBCurPtr->TS;
494  }
495  *p_err = OS_ERR_OBJ_DEL;
496  break;
497 
498  default:
499  *p_err = OS_ERR_STATUS_INVALID;
500  break;
501  }
502  CPU_CRITICAL_EXIT();
503 }
504 
505 /*$PAGE*/
506 /*
507 ************************************************************************************************************************
508 * ABORT WAITING ON A MUTEX
509 *
510 * Description: This function aborts & readies any tasks currently waiting on a mutex. This function should be used
511 * to fault-abort the wait on the mutex, rather than to normally signal the mutex via OSMutexPost().
512 *
513 * Arguments : p_mutex is a pointer to the mutex
514 *
515 * opt determines the type of ABORT performed:
516 *
517 * OS_OPT_PEND_ABORT_1 ABORT wait for a single task (HPT) waiting on the mutex
518 * OS_OPT_PEND_ABORT_ALL ABORT wait for ALL tasks that are waiting on the mutex
519 * OS_OPT_POST_NO_SCHED Do not call the scheduler
520 *
521 * p_err is a pointer to a variable that will contain an error code returned by this function.
522 *
523 * OS_ERR_NONE At least one task waiting on the mutex was readied and
524 * informed of the aborted wait; check return value for the
525 * number of tasks whose wait on the mutex was aborted.
526 * OS_ERR_OBJ_PTR_NULL If 'p_mutex' is a NULL pointer.
527 * OS_ERR_OBJ_TYPE If 'p_mutex' is not pointing at a mutex
528 * OS_ERR_OPT_INVALID If you specified an invalid option
529 * OS_ERR_PEND_ABORT_ISR If you attempted to call this function from an ISR
530 * OS_ERR_PEND_ABORT_NONE No task were pending
531 *
532 * Returns : == 0 if no tasks were waiting on the mutex, or upon error.
533 * > 0 if one or more tasks waiting on the mutex are now readied and informed.
534 ************************************************************************************************************************
535 */
536 
537 #if OS_CFG_MUTEX_PEND_ABORT_EN > 0u
538 OS_OBJ_QTY OSMutexPendAbort (OS_MUTEX *p_mutex,
539  OS_OPT opt,
540  OS_ERR *p_err)
541 {
542  OS_PEND_LIST *p_pend_list;
543  OS_TCB *p_tcb;
544  CPU_TS ts;
545  OS_OBJ_QTY nbr_tasks;
546  CPU_SR_ALLOC();
547 
548 
549 
550 #ifdef OS_SAFETY_CRITICAL
551  if (p_err == (OS_ERR *)0) {
552  OS_SAFETY_CRITICAL_EXCEPTION();
553  return ((OS_OBJ_QTY)0u);
554  }
555 #endif
556 
557 #if OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u
558  if (OSIntNestingCtr > (OS_NESTING_CTR)0u) { /* Not allowed to Pend Abort from an ISR */
559  *p_err = OS_ERR_PEND_ABORT_ISR;
560  return ((OS_OBJ_QTY)0u);
561  }
562 #endif
563 
564 #if OS_CFG_ARG_CHK_EN > 0u
565  if (p_mutex == (OS_MUTEX *)0) { /* Validate 'p_mutex' */
566  *p_err = OS_ERR_OBJ_PTR_NULL;
567  return ((OS_OBJ_QTY)0u);
568  }
569  switch (opt) { /* Validate 'opt' */
570  case OS_OPT_PEND_ABORT_1:
571  case OS_OPT_PEND_ABORT_ALL:
572  case OS_OPT_PEND_ABORT_1 | OS_OPT_POST_NO_SCHED:
573  case OS_OPT_PEND_ABORT_ALL | OS_OPT_POST_NO_SCHED:
574  break;
575 
576  default:
577  *p_err = OS_ERR_OPT_INVALID;
578  return ((OS_OBJ_QTY)0u);
579  }
580 #endif
581 
582 #if OS_CFG_OBJ_TYPE_CHK_EN > 0u
583  if (p_mutex->Type != OS_OBJ_TYPE_MUTEX) { /* Make sure mutex was created */
584  *p_err = OS_ERR_OBJ_TYPE;
585  return ((OS_OBJ_QTY)0u);
586  }
587 #endif
588 
589  CPU_CRITICAL_ENTER();
590  p_pend_list = &p_mutex->PendList;
591  if (p_pend_list->NbrEntries == (OS_OBJ_QTY)0u) { /* Any task waiting on mutex? */
592  CPU_CRITICAL_EXIT(); /* No */
593  *p_err = OS_ERR_PEND_ABORT_NONE;
594  return ((OS_OBJ_QTY)0u);
595  }
596 
597  OS_CRITICAL_ENTER_CPU_CRITICAL_EXIT();
598  nbr_tasks = 0u;
599  ts = OS_TS_GET(); /* Get local time stamp so all tasks get the same time */
600  while (p_pend_list->NbrEntries > (OS_OBJ_QTY)0u) {
601  p_tcb = p_pend_list->HeadPtr->TCBPtr;
602  OS_PendAbort((OS_PEND_OBJ *)((void *)p_mutex),
603  p_tcb,
604  ts);
605  nbr_tasks++;
606  if (opt != OS_OPT_PEND_ABORT_ALL) { /* Pend abort all tasks waiting? */
607  break; /* No */
608  }
609  }
610  OS_CRITICAL_EXIT_NO_SCHED();
611 
612  if ((opt & OS_OPT_POST_NO_SCHED) == (OS_OPT)0u) {
613  OSSched(); /* Run the scheduler */
614  }
615 
616  *p_err = OS_ERR_NONE;
617  return (nbr_tasks);
618 }
619 #endif
620 
621 /*$PAGE*/
622 /*
623 ************************************************************************************************************************
624 * POST TO A MUTEX
625 *
626 * Description: This function signals a mutex
627 *
628 * Arguments : p_mutex is a pointer to the mutex
629 *
630 * opt is an option you can specify to alter the behavior of the post. The choices are:
631 *
632 * OS_OPT_POST_NONE No special option selected
633 * OS_OPT_POST_NO_SCHED If you don't want the scheduler to be called after the post.
634 *
635 * p_err is a pointer to a variable that will contain an error code returned by this function.
636 *
637 * OS_ERR_NONE The call was successful and the mutex was signaled.
638 * OS_ERR_MUTEX_NESTING Mutex owner nested its use of the mutex
639 * OS_ERR_MUTEX_NOT_OWNER If the task posting is not the Mutex owner
640 * OS_ERR_OBJ_PTR_NULL If 'p_mutex' is a NULL pointer.
641 * OS_ERR_OBJ_TYPE If 'p_mutex' is not pointing at a mutex
642 * OS_ERR_POST_ISR If you attempted to post from an ISR
643 *
644 * Returns : none
645 ************************************************************************************************************************
646 */
647 
648 void OSMutexPost (OS_MUTEX *p_mutex,
649  OS_OPT opt,
650  OS_ERR *p_err)
651 {
652  OS_PEND_LIST *p_pend_list;
653  OS_TCB *p_tcb;
654  CPU_TS ts;
655  CPU_SR_ALLOC();
656 
657 
658 
659 #ifdef OS_SAFETY_CRITICAL
660  if (p_err == (OS_ERR *)0) {
661  OS_SAFETY_CRITICAL_EXCEPTION();
662  return;
663  }
664 #endif
665 
666 #if OS_CFG_CALLED_FROM_ISR_CHK_EN > 0u
667  if (OSIntNestingCtr > (OS_NESTING_CTR)0) { /* Not allowed to call from an ISR */
668  *p_err = OS_ERR_POST_ISR;
669  return;
670  }
671 #endif
672 
673 #if OS_CFG_ARG_CHK_EN > 0u
674  if (p_mutex == (OS_MUTEX *)0) { /* Validate 'p_mutex' */
675  *p_err = OS_ERR_OBJ_PTR_NULL;
676  return;
677  }
678  switch (opt) { /* Validate 'opt' */
679  case OS_OPT_POST_NONE:
680  case OS_OPT_POST_NO_SCHED:
681  break;
682 
683  default:
684  *p_err = OS_ERR_OPT_INVALID;
685  return;
686  }
687 #endif
688 
689 #if OS_CFG_OBJ_TYPE_CHK_EN > 0u
690  if (p_mutex->Type != OS_OBJ_TYPE_MUTEX) { /* Make sure mutex was created */
691  *p_err = OS_ERR_OBJ_TYPE;
692  return;
693  }
694 #endif
695 
696  CPU_CRITICAL_ENTER();
697  if (OSTCBCurPtr != p_mutex->OwnerTCBPtr) { /* Make sure the mutex owner is releasing the mutex */
698  CPU_CRITICAL_EXIT();
699  *p_err = OS_ERR_MUTEX_NOT_OWNER;
700  return;
701  }
702 
703  OS_CRITICAL_ENTER_CPU_CRITICAL_EXIT();
704  ts = OS_TS_GET(); /* Get timestamp */
705  p_mutex->TS = ts;
706  p_mutex->OwnerNestingCtr--; /* Decrement owner's nesting counter */
707  if (p_mutex->OwnerNestingCtr > (OS_NESTING_CTR)0) { /* Are we done with all nestings? */
708  OS_CRITICAL_EXIT(); /* No */
709  *p_err = OS_ERR_MUTEX_NESTING;
710  return;
711  }
712 
713  p_pend_list = &p_mutex->PendList;
714  if (p_pend_list->NbrEntries == (OS_OBJ_QTY)0) { /* Any task waiting on mutex? */
715  p_mutex->OwnerTCBPtr = (OS_TCB *)0; /* No */
716  p_mutex->OwnerNestingCtr = (OS_NESTING_CTR)0;
717  OS_CRITICAL_EXIT();
718  *p_err = OS_ERR_NONE;
719  return;
720  }
721  /* Yes */
722  if (OSTCBCurPtr->Prio != p_mutex->OwnerOriginalPrio) {
723  OS_RdyListRemove(OSTCBCurPtr);
724  OSTCBCurPtr->Prio = p_mutex->OwnerOriginalPrio; /* Lower owner's priority back to its original one */
725  OS_PrioInsert(OSTCBCurPtr->Prio);
726  OS_RdyListInsertTail(OSTCBCurPtr); /* Insert owner in ready list at new priority */
727  OSPrioCur = OSTCBCurPtr->Prio;
728  }
729  /* Get TCB from head of pend list */
730  p_tcb = p_pend_list->HeadPtr->TCBPtr;
731  p_mutex->OwnerTCBPtr = p_tcb; /* Give mutex to new owner */
732  p_mutex->OwnerOriginalPrio = p_tcb->Prio;
733  p_mutex->OwnerNestingCtr = (OS_NESTING_CTR)1;
734  /* Post to mutex */
735  OS_Post((OS_PEND_OBJ *)((void *)p_mutex),
736  (OS_TCB *)p_tcb,
737  (void *)0,
738  (OS_MSG_SIZE )0,
739  (CPU_TS )ts);
740 
741  OS_CRITICAL_EXIT_NO_SCHED();
742 
743  if ((opt & OS_OPT_POST_NO_SCHED) == (OS_OPT)0) {
744  OSSched(); /* Run the scheduler */
745  }
746 
747  *p_err = OS_ERR_NONE;
748 }
749 
750 /*$PAGE*/
751 /*
752 ************************************************************************************************************************
753 * CLEAR THE CONTENTS OF A MUTEX
754 *
755 * Description: This function is called by OSMutexDel() to clear the contents of a mutex
756 *
757 
758 * Argument(s): p_mutex is a pointer to the mutex to clear
759 * -------
760 *
761 * Returns : none
762 *
763 * Note(s) : This function is INTERNAL to uC/OS-III and your application should not call it.
764 ************************************************************************************************************************
765 */
766 
767 void OS_MutexClr (OS_MUTEX *p_mutex)
768 {
769  p_mutex->Type = OS_OBJ_TYPE_NONE; /* Mark the data structure as a NONE */
770  p_mutex->NamePtr = (CPU_CHAR *)((void *)"?MUTEX");
771  p_mutex->OwnerTCBPtr = (OS_TCB *)0;
772  p_mutex->OwnerNestingCtr = (OS_NESTING_CTR)0;
773  p_mutex->TS = (CPU_TS )0;
774  p_mutex->OwnerOriginalPrio = OS_CFG_PRIO_MAX;
775  OS_PendListInit(&p_mutex->PendList); /* Initialize the waiting list */
776 }
777 
778 /*$PAGE*/
779 /*
780 ************************************************************************************************************************
781 * ADD/REMOVE MUTEX TO/FROM DEBUG LIST
782 *
783 * Description: These functions are called by uC/OS-III to add or remove a mutex to/from the debug list.
784 *
785 * Arguments : p_mutex is a pointer to the mutex to add/remove
786 *
787 * Returns : none
788 *
789 * Note(s) : These functions are INTERNAL to uC/OS-III and your application should not call it.
790 ************************************************************************************************************************
791 */
792 
793 
794 #if OS_CFG_DBG_EN > 0u
795 void OS_MutexDbgListAdd (OS_MUTEX *p_mutex)
796 {
797  p_mutex->DbgNamePtr = (CPU_CHAR *)((void *)" ");
798  p_mutex->DbgPrevPtr = (OS_MUTEX *)0;
799  if (OSMutexDbgListPtr == (OS_MUTEX *)0) {
800  p_mutex->DbgNextPtr = (OS_MUTEX *)0;
801  } else {
802  p_mutex->DbgNextPtr = OSMutexDbgListPtr;
803  OSMutexDbgListPtr->DbgPrevPtr = p_mutex;
804  }
805  OSMutexDbgListPtr = p_mutex;
806 }
807 
808 
809 
810 void OS_MutexDbgListRemove (OS_MUTEX *p_mutex)
811 {
812  OS_MUTEX *p_mutex_next;
813  OS_MUTEX *p_mutex_prev;
814 
815 
816  p_mutex_prev = p_mutex->DbgPrevPtr;
817  p_mutex_next = p_mutex->DbgNextPtr;
818 
819  if (p_mutex_prev == (OS_MUTEX *)0) {
820  OSMutexDbgListPtr = p_mutex_next;
821  if (p_mutex_next != (OS_MUTEX *)0) {
822  p_mutex_next->DbgPrevPtr = (OS_MUTEX *)0;
823  }
824  p_mutex->DbgNextPtr = (OS_MUTEX *)0;
825 
826  } else if (p_mutex_next == (OS_MUTEX *)0) {
827  p_mutex_prev->DbgNextPtr = (OS_MUTEX *)0;
828  p_mutex->DbgPrevPtr = (OS_MUTEX *)0;
829 
830  } else {
831  p_mutex_prev->DbgNextPtr = p_mutex_next;
832  p_mutex_next->DbgPrevPtr = p_mutex_prev;
833  p_mutex->DbgNextPtr = (OS_MUTEX *)0;
834  p_mutex->DbgPrevPtr = (OS_MUTEX *)0;
835  }
836 }
837 #endif
838 
839 /*$PAGE*/
840 /*
841 ************************************************************************************************************************
842 * MUTEX INITIALIZATION
843 *
844 * Description: This function is called by OSInit() to initialize the mutex management.
845 *
846 
847 * Argument(s): p_err is a pointer to a variable that will contain an error code returned by this function.
848 *
849 * OS_ERR_NONE the call was successful
850 *
851 * Returns : none
852 *
853 * Note(s) : 1) This function is INTERNAL to uC/OS-III and your application MUST NOT call it.
854 ************************************************************************************************************************
855 */
856 
857 void OS_MutexInit (OS_ERR *p_err)
858 {
859 #ifdef OS_SAFETY_CRITICAL
860  if (p_err == (OS_ERR *)0) {
861  OS_SAFETY_CRITICAL_EXCEPTION();
862  return;
863  }
864 #endif
865 
866 #if OS_CFG_DBG_EN > 0u
867  OSMutexDbgListPtr = (OS_MUTEX *)0;
868 #endif
869 
870  OSMutexQty = (OS_OBJ_QTY)0;
871  *p_err = OS_ERR_NONE;
872 }
873 
874 #endif /* OS_CFG_MUTEX_EN */