/***********************************************************************************************************                                                uC/OS-II*                                          The Real-Time Kernel*                                  MUTUAL EXCLUSION SEMAPHORE MANAGEMENT**                          (c) Copyright 1992-2001, Jean J. Labrosse, Weston, FL*                                           All Rights Reserved** File : OS_MUTEX.C* By   : Jean J. Labrosse**********************************************************************************************************/#ifndef  OS_MASTER_FILE#include "includes.h"#endif/***********************************************************************************************************                                            LOCAL CONSTANTS**********************************************************************************************************/#define  OS_MUTEX_KEEP_LOWER_8   0x00FF#define  OS_MUTEX_KEEP_UPPER_8   0xFF00#define  OS_MUTEX_AVAILABLE      0x00FF#if OS_MUTEX_EN > 0/***********************************************************************************************************                                   ACCEPT MUTUAL EXCLUSION SEMAPHORE** Description: This  function checks the mutual exclusion semaphore to see if a resource is available.*              Unlike OSMutexPend(), OSMutexAccept() does not suspend the calling task if the resource is*              not available or the event did not occur.** Arguments  : pevent     is a pointer to the event control block**              err        is a pointer to an error code which will be returned to your application:*                            OS_NO_ERR          if the call was successful.*                            OS_ERR_EVENT_TYPE  if 'pevent' is not a pointer to a mutex*                            OS_ERR_PEVENT_NULL 'pevent' is a NULL pointer*                            OS_ERR_PEND_ISR     if you called this function from an ISR** Returns    : == 1       if the resource is available, the mutual exclusion semaphore is acquired*              == 0       a) if the resource is not available*                         b) you didn't pass a pointer to a mutual exclusion semaphore*                         c) you called this function from an ISR** Warning(s) : This function CANNOT be called from an ISR because mutual exclusion semaphores are*              intended to be used by tasks only.**********************************************************************************************************/#if OS_MUTEX_ACCEPT_EN > 0INT8U  OSMutexAccept (OS_EVENT *pevent, INT8U *err){#if OS_CRITICAL_METHOD == 3                            /* Allocate storage for CPU status register     */    OS_CPU_SR  cpu_sr;#endif                if (OSIntNesting > 0) {                            /* Make sure it's not called from an ISR        */        *err = OS_ERR_PEND_ISR;        return (0);    }#if OS_ARG_CHK_EN > 0    if (pevent == (OS_EVENT *)0) {                     /* Validate 'pevent'                            */        *err = OS_ERR_PEVENT_NULL;        return (0);    }    if (pevent->OSEventType != OS_EVENT_TYPE_MUTEX) {  /* Validate event block type                    */        *err = OS_ERR_EVENT_TYPE;        return (0);    }#endif                                                         OS_ENTER_CRITICAL();							   /* Get value (0 or 1) of Mutex                  */    if ((pevent->OSEventCnt & OS_MUTEX_KEEP_LOWER_8) == OS_MUTEX_AVAILABLE) {             pevent->OSEventCnt &= OS_MUTEX_KEEP_UPPER_8;   /*      Mask off LSByte (Acquire Mutex)         */        pevent->OSEventCnt |= OSTCBCur->OSTCBPrio;     /*      Save current task priority in LSByte    */        pevent->OSEventPtr  = (void *)OSTCBCur;        /*      Link TCB of task owning Mutex           */        OS_EXIT_CRITICAL();        *err = OS_NO_ERR;        return (1);    }    OS_EXIT_CRITICAL();    *err = OS_NO_ERR;    return (0);}#endif                                                     /*$PAGE*//***********************************************************************************************************                                  CREATE A MUTUAL EXCLUSION SEMAPHORE** Description: This function creates a mutual exclusion semaphore.** Arguments  : prio          is the priority to use when accessing the mutual exclusion semaphore.  In*                            other words, when the semaphore is acquired and a higher priority task*                            attempts to obtain the semaphore then the priority of the task owning the*                            semaphore is raised to this priority.  It is assumed that you will specify*                            a priority that is LOWER in value than ANY of the tasks competing for the*                            mutex.**              err           is a pointer to an error code which will be returned to your application:*                               OS_NO_ERR           if the call was successful.*                               OS_ERR_CREATE_ISR   if you attempted to create a MUTEX from an ISR*                               OS_PRIO_EXIST       if a task at the priority inheritance priority*                                                   already exist.*                               OS_ERR_PEVENT_NULL  No more event control blocks available.*                               OS_PRIO_INVALID     if the priority you specify is higher that the *                                                   maximum allowed (i.e. > OS_LOWEST_PRIO)** Returns    : != (void *)0  is a pointer to the event control clock (OS_EVENT) associated with the*                            created mutex.*              == (void *)0  if an error is detected.** Note(s)    : 1) The LEAST significant 8 bits of '.OSEventCnt' are used to hold the priority number*                 of the task owning the mutex or 0xFF if no task owns the mutex.*              2) The MOST  significant 8 bits of '.OSEventCnt' are used to hold the priority number*                 to use to reduce priority inversion.**********************************************************************************************************/OS_EVENT  *OSMutexCreate (INT8U prio, INT8U *err){#if OS_CRITICAL_METHOD == 3                                /* Allocate storage for CPU status register */    OS_CPU_SR  cpu_sr;#endif        OS_EVENT  *pevent;    if (OSIntNesting > 0) {                                /* See if called from ISR ...               */        *err = OS_ERR_CREATE_ISR;                          /* ... can't CREATE mutex from an ISR       */        return ((OS_EVENT *)0);    }#if OS_ARG_CHK_EN > 0    if (prio >= OS_LOWEST_PRIO) {                          /* Validate PIP                             */        *err = OS_PRIO_INVALID;        return ((OS_EVENT *)0);    }#endif    OS_ENTER_CRITICAL();    if (OSTCBPrioTbl[prio] != (OS_TCB *)0) {               /* Mutex priority must not already exist    */        OS_EXIT_CRITICAL();                                /* Task already exist at priority ...       */        *err = OS_PRIO_EXIST;                              /* ... inheritance priority                 */        return ((OS_EVENT *)0);                                }    OSTCBPrioTbl[prio] = (OS_TCB *)1;                      /* Reserve the table entry                  */    pevent             = OSEventFreeList;                  /* Get next free event control block        */    if (pevent == (OS_EVENT *)0) {                         /* See if an ECB was available              */        OSTCBPrioTbl[prio] = (OS_TCB *)0;                  /* No, Release the table entry              */        OS_EXIT_CRITICAL();        *err               = OS_ERR_PEVENT_NULL;           /* No more event control blocks             */        return (pevent);    }    OSEventFreeList     = (OS_EVENT *)OSEventFreeList->OSEventPtr;   /* Adjust the free list           */    OS_EXIT_CRITICAL();    pevent->OSEventType = OS_EVENT_TYPE_MUTEX;    pevent->OSEventCnt  = (prio << 8) | OS_MUTEX_AVAILABLE;/* Resource is available                    */    pevent->OSEventPtr  = (void *)0;                       /* No task owning the mutex                 */    OS_EventWaitListInit(pevent);    *err                = OS_NO_ERR;    return (pevent);}/*$PAGE*//***********************************************************************************************************                                          DELETE A MUTEX** Description: This function deletes a mutual exclusion semaphore and readies all tasks pending on the it.** Arguments  : pevent        is a pointer to the event control block associated with the desired mutex.**              opt           determines delete options as follows:*                            opt == OS_DEL_NO_PEND   Delete mutex ONLY if no task pending*                            opt == OS_DEL_ALWAYS    Deletes the mutex even if tasks are waiting.*                                                    In this case, all the tasks pending will be readied.**              err           is a pointer to an error code that can contain one of the following values:*                            OS_NO_ERR               The call was successful and the mutex was deleted*                            OS_ERR_DEL_ISR          If you attempted to delete the MUTEX from an ISR*                            OS_ERR_INVALID_OPT      An invalid option was specified*                            OS_ERR_TASK_WAITING     One or more tasks were waiting on the mutex*                            OS_ERR_EVENT_TYPE       If you didn't pass a pointer to a mutex*                            OS_ERR_PEVENT_NULL      If 'pevent' is a NULL pointer.** Returns    : pevent        upon error*              (OS_EVENT *)0 if the mutex was successfully deleted.** Note(s)    : 1) This function must be used with care.  Tasks that would normally expect the presence of*                 the mutex MUST check the return code of OSMutexPend().*              2) This call can potentially disable interrupts for a long time.  The interrupt disable*                 time is directly proportional to the number of tasks waiting on the mutex.*              3) Because ALL tasks pending on the mutex will be readied, you MUST be careful because the*                 resource(s) will no longer be guarded by the mutex.**********************************************************************************************************/#if OS_MUTEX_DEL_ENOS_EVENT  *OSMutexDel (OS_EVENT *pevent, INT8U opt, INT8U *err){#if OS_CRITICAL_METHOD == 3                      /* Allocate storage for CPU status register           */    OS_CPU_SR  cpu_sr;#endif        BOOLEAN    tasks_waiting;    INT8U      pip;    if (OSIntNesting > 0) {                                /* See if called from ISR ...               */        *err = OS_ERR_DEL_ISR;                             /* ... can't DELETE from an ISR             */        return (pevent);    }#if OS_ARG_CHK_EN > 0    if (pevent == (OS_EVENT *)0) {                         /* Validate 'pevent'                        */        *err = OS_ERR_PEVENT_NULL;        return ((OS_EVENT *)0);    }    if (pevent->OSEventType != OS_EVENT_TYPE_MUTEX) {      /* Validate event block type                */        *err = OS_ERR_EVENT_TYPE;        return (pevent);    }#endif    OS_ENTER_CRITICAL();    if (pevent->OSEventGrp != 0x00) {                      /* See if any tasks waiting on mutex        */        tasks_waiting = TRUE;                              /* Yes                                      */    } else {        tasks_waiting = FALSE;                             /* No                                       */    }    switch (opt) {        case OS_DEL_NO_PEND:                               /* Delete mutex only if no task waiting     */             if (tasks_waiting == FALSE) {                 pip                 = (INT8U)(pevent->OSEventCnt >> 8);                 OSTCBPrioTbl[pip]   = (OS_TCB *)0;        /* Free up the PIP                          */                 pevent->OSEventType = OS_EVENT_TYPE_UNUSED;                 pevent->OSEventPtr  = OSEventFreeList;    /* Return Event Control Block to free list  */                 OSEventFreeList     = pevent;                 OS_EXIT_CRITICAL();                 *err = OS_NO_ERR;                 return ((OS_EVENT *)0);                   /* Mutex has been deleted                   */             } else {                 OS_EXIT_CRITICAL();                 *err = OS_ERR_TASK_WAITING;                 return (pevent);             }        case OS_DEL_ALWAYS:                                /* Always delete the mutex                  */             while (pevent->OSEventGrp != 0x00) {          /* Ready ALL tasks waiting for mutex        */                 OS_EventTaskRdy(pevent, (void *)0, OS_STAT_MUTEX);             }             pip                 = (INT8U)(pevent->OSEventCnt >> 8);             OSTCBPrioTbl[pip]   = (OS_TCB *)0;            /* Free up the PIP                          */             pevent->OSEventType = OS_EVENT_TYPE_UNUSED;             pevent->OSEventPtr  = OSEventFreeList;        /* Return Event Control Block to free list  */             OSEventFreeList     = pevent;                 /* Get next free event control block        */             OS_EXIT_CRITICAL();             if (tasks_waiting == TRUE) {                  /* Reschedule only if task(s) were waiting  */                 OS_Sched();                               /* Find highest priority task ready to run  */             }             *err = OS_NO_ERR;             return ((OS_EVENT *)0);                       /* Mutex has been deleted                   */        default:             OS_EXIT_CRITICAL();             *err = OS_ERR_INVALID_OPT;             return (pevent);    }