μCOS-II中OS_MUTEX.C源碼中文注釋版.doc

xilentz的網(wǎng)絡文摘博客園 首頁 新隨筆 聯(lián)系 訂閱 管理 隨筆 - 204 文章 - 0評論 - 10trackbacks - 0 OS_MUTEX.C/* uC/OS-II* The Real-Time Kernel* MUTUAL EXCLUSION SEMAPHORE MANAGEMENT* (c) Copyright 1992-2002, 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 didnt 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 its 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. 建立一個互斥型信號量描述：建立一個互斥型信號量參數(shù)：prio：當存取互斥型信號量時它的優(yōu)先級。就是說，當任務需要信號量， 而另一優(yōu)先級更高的任務想得到信號量，就改變當前任務的優(yōu)先級，變?yōu)楦?假定你改變的優(yōu)先級值小于任務競爭這個信號量的任務的值（即優(yōu)先級更高） err:應用時包含錯誤代碼的指針 ：* OS_NO_ERR 調用成功* OS_ERR_CREATE_ISR 如果想從ISR中建立* OS_PRIO_EXIST 如果優(yōu)先級繼承優(yōu)先級的優(yōu)先級已經(jīng)存在* OS_ERR_PEVENT_NULL 沒有事件控制塊可用* OS_PRIO_INVALID 如果你指定的優(yōu)先級大于最大值 */ 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; /* . cant CREATE mutex from an ISR */ return (OS_EVENT *)0); /不能從ISR中建立，不允許在ISR中調用此函數(shù)#if OS_ARG_CHK_EN 0 if (prio = OS_LOWEST_PRIO) /* Validate PIP */ *err = OS_PRIO_INVALID; return (OS_EVENT *)0); /不合理的PIP#endif OS_ENTER_CRITICAL(); if (OSTCBPrioTblprio != (OS_TCB *)0) /* Mutex priority must not already exist */ /確認PIP沒有被任何任務占用。OSTCBPrioTbl 中的一個指向NULL的空指針指示 /PIP有效 OS_EXIT_CRITICAL(); /* Task already exist at priority . */ *err = OS_PRIO_EXIST; /* . inheritance priority */ /如果優(yōu)先級存在 ，則出錯。 return (OS_EVENT *)0); OSTCBPrioTblprio = (OS_TCB *)1; /* Reserve the table entry */ /置非空指針，將這個優(yōu)先級保留下來。 pevent = OSEventFreeList; /* Get next free event control block */ /從空余ECB中得到一塊空的ECB。 if (pevent = (OS_EVENT *)0) /* See if an ECB was available */ /看ECB是否可用 OSTCBPrioTblprio = (OS_TCB *)0; /* No, Release the table entry */ /如果不可用，釋放此優(yōu)先級表入口 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 OSEventPtr = (void *)0; /* No task owning the mutex */ /消息正在初始化，所以沒有等待這個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 didnt 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. 刪除一個互斥型信號量描述： 刪除一個互斥型信號量將掛起的任務就緒參數(shù)：pevent：指向事件控制塊結合目標mutex的指針* opt 決定刪除選項* opt = OS_DEL_NO_PEND 沒有任務掛起時才刪* opt = OS_DEL_ALWAYS 即使有任務掛起也刪，刪除后所有等待的事件全部就緒* err 指向包含錯誤代碼的指針* OS_NO_ERR 調用成功 mutex 刪除* OS_ERR_DEL_ISR 如果在ISR中調用此函數(shù)* OS_ERR_INVALID_OPT 設置了非法選項* OS_ERR_TASK_WAITING 有任務在等待 mutex* OS_ERR_EVENT_TYPE 如果沒有傳遞指針到 mutex* OS_ERR_PEVENT_NULL 如果 pevent 是一個空指針備注：1) 小心使用， 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; /* . cant DELETE from an ISR */ return (pevent); /不允許在ISR中調用此函數(shù)#if OS_ARG_CHK_EN 0 if (pevent = (OS_EVENT *)0) /* Validate pevent */ *err = OS_ERR_PEVENT_NULL; return (OS_EVENT *)0); /非法的pevent 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); OSTCBPrioTblpip = (OS_TCB *)0; /* Free up the PIP */ /釋放PIP，這兩行程序書上沒有 pevent-OSEventType = OS_EVENT_TYPE_UNUSED;/標記為沒有使用 pevent-OSEventPtr = OSEventFreeList; /* Return Event Control Block to free list */ OSEventFreeList = pevent;/返回ECB到空閑列表 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); OSTCBPrioTblpip = (OS_TCB *)0; /* Free up the PIP */ /釋放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 */ /將ECB標明為沒有被占用，并被送回到空余事件控制塊 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); #endif /*$PAGE*/ /* PEND ON MUTUAL EXCLUSION SEMAPHORE* Description: This function waits for a mutual exclusion semaphore.* Arguments : pevent is a pointer to the event control block associated with the desired* mutex.* timeout is an optional timeout period (in clock ticks). If non-zero, your task will* wait for the resource up to the amount of time specified by this argument.* If you specify 0, however, your task will wait forever at the specified* mutex or, until the resource becomes available.* err is a pointer to where an