From 2658a3b6eff3fede45246c05ba6ff192a42988d3 Mon Sep 17 00:00:00 2001
From: Richard Barry <ribarry@amazon.com>
Date: Sun, 11 Mar 2012 15:23:51 +0000
Subject: [PATCH] Added xSemaphoreGetMutexHolder() macro and equivalent
 function.

---
 Source/include/queue.h  |  8 +++++---
 Source/include/semphr.h | 19 +++++++++++++++++--
 Source/queue.c          | 39 +++++++++++++++++++++++++++++++++++----
 3 files changed, 57 insertions(+), 9 deletions(-)

diff --git a/Source/include/queue.h b/Source/include/queue.h
index d129f64cd..81f46cf98 100644
--- a/Source/include/queue.h
+++ b/Source/include/queue.h
@@ -56,7 +56,7 @@
 #define QUEUE_H
 
 #ifndef INC_FREERTOS_H
-	#error "#include FreeRTOS.h" must appear in source files before "#include queue.h"
+	#error "include FreeRTOS.h" must appear in source files before "include queue.h"
 #endif
 
 #ifdef __cplusplus
@@ -1221,11 +1221,13 @@ signed portBASE_TYPE xQueueCRSend( xQueueHandle pxQueue, const void *pvItemToQue
 signed portBASE_TYPE xQueueCRReceive( xQueueHandle pxQueue, void *pvBuffer, portTickType xTicksToWait );
 
 /*
- * For internal use only.  Use xSemaphoreCreateMutex() or
- * xSemaphoreCreateCounting() instead of calling these functions directly.
+ * For internal use only.  Use xSemaphoreCreateMutex(), 
+ * xSemaphoreCreateCounting() or xSemaphoreGetMutexHolder() instead of calling 
+ * these functions directly.
  */
 xQueueHandle xQueueCreateMutex( unsigned char ucQueueType );
 xQueueHandle xQueueCreateCountingSemaphore( unsigned portBASE_TYPE uxCountValue, unsigned portBASE_TYPE uxInitialCount );
+void* xQueueGetMutexHolder( xQueueHandle xSemaphore );
 
 /*
  * For internal use only.  Use xSemaphoreTakeMutexRecursive() or
diff --git a/Source/include/semphr.h b/Source/include/semphr.h
index 251e73809..98f3b4fcd 100644
--- a/Source/include/semphr.h
+++ b/Source/include/semphr.h
@@ -55,7 +55,7 @@
 #define SEMAPHORE_H
 
 #ifndef INC_FREERTOS_H
-	#error "#include FreeRTOS.h" must appear in source files before "#include semphr.h"
+	#error "include FreeRTOS.h" must appear in source files before "include semphr.h"
 #endif
 
 #include "queue.h"
@@ -718,7 +718,22 @@ typedef xQueueHandle xSemaphoreHandle;
  * \page vSemaphoreDelete vSemaphoreDelete
  * \ingroup Semaphores
  */
-#define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( xQueueHandle ) xSemaphore )
+#define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( xQueueHandle ) ( xSemaphore ) )
+
+/**
+ * semphr.h
+ * <pre>xTaskHandle xSemaphoreGetMutexHolder( xSemaphoreHandle xMutex );</pre>
+ *
+ * If xMutex is indeed a mutex type semaphore, return the current mutex holder.
+ * If xMutex is not a mutex type semaphore, or the mutex is available (not held
+ * by a task), return NULL.
+ *
+ * Note: This Is is a good way of determining if the calling task is the mutex 
+ * holder, but not a good way of determining the identity of the mutex holder as
+ * the holder may change between the function exiting and the returned value
+ * being tested.
+ */
+#define xSemaphoreGetMutexHolder( xSemaphore ) xQueueGetMutexHolder( ( xSemaphore ) )
 
 #endif /* SEMAPHORE_H */
 
diff --git a/Source/queue.c b/Source/queue.c
index 19c51d759..0eb8d2bdd 100644
--- a/Source/queue.c
+++ b/Source/queue.c
@@ -164,6 +164,7 @@ unsigned char ucQueueGetQueueNumber( xQueueHandle pxQueue ) PRIVILEGED_FUNCTION;
 void vQueueSetQueueNumber( xQueueHandle pxQueue, unsigned char ucQueueNumber ) PRIVILEGED_FUNCTION;
 unsigned char ucQueueGetQueueType( xQueueHandle pxQueue ) PRIVILEGED_FUNCTION;
 portBASE_TYPE xQueueGenericReset( xQueueHandle pxQueue, portBASE_TYPE xNewQueue ) PRIVILEGED_FUNCTION;
+xTaskHandle xQueueGetMutexHolder( xQueueHandle xSemaphore ) PRIVILEGED_FUNCTION;
 
 /*
  * Co-routine queue functions differ from task queue functions.  Co-routines are
@@ -307,7 +308,7 @@ xQUEUE *pxNewQueue;
 size_t xQueueSizeInBytes;
 xQueueHandle xReturn = NULL;
 
-	/* Remove compiler warnings about unused parameters should 
+	/* Remove compiler warnings about unused parameters should
 	configUSE_TRACE_FACILITY not be set to 1. */
 	( void ) ucQueueType;
 
@@ -361,7 +362,7 @@ xQueueHandle xReturn = NULL;
 		/* Prevent compiler warnings about unused parameters if
 		configUSE_TRACE_FACILITY does not equal 1. */
 		( void ) ucQueueType;
-	
+
 		/* Allocate the new queue structure. */
 		pxNewQueue = ( xQUEUE * ) pvPortMalloc( sizeof( xQUEUE ) );
 		if( pxNewQueue != NULL )
@@ -383,7 +384,7 @@ xQueueHandle xReturn = NULL;
 			pxNewQueue->uxItemSize = ( unsigned portBASE_TYPE ) 0U;
 			pxNewQueue->xRxLock = queueUNLOCKED;
 			pxNewQueue->xTxLock = queueUNLOCKED;
-			
+
 			#if ( configUSE_TRACE_FACILITY == 1 )
 			{
 				pxNewQueue->ucQueueType = ucQueueType;
@@ -411,7 +412,37 @@ xQueueHandle xReturn = NULL;
 #endif /* configUSE_MUTEXES */
 /*-----------------------------------------------------------*/
 
-#if configUSE_RECURSIVE_MUTEXES == 1
+#if ( configUSE_MUTEXES == 1 )
+
+	void* xQueueGetMutexHolder( xQueueHandle xSemaphore )
+	{
+	void *pxReturn;
+
+		/* This function is called by xSemaphoreGetMutexHolder(), and should not
+		be called directly.  Note:  This is is a good way of determining if the
+		calling task is the mutex holder, but not a good way of determining the
+		identity of the mutex holder, as the holder may change between the 
+		following critical section exiting and the function returning. */
+		taskENTER_CRITICAL();
+		{
+			if( xSemaphore->uxQueueType == queueQUEUE_IS_MUTEX )
+			{
+				pxReturn = ( void * ) xSemaphore->pxMutexHolder;
+			}
+			else
+			{
+				pxReturn = NULL;
+			}
+		}
+		taskEXIT_CRITICAL();
+		
+		return pxReturn;
+	}
+
+#endif
+/*-----------------------------------------------------------*/
+
+#if ( configUSE_RECURSIVE_MUTEXES == 1 )
 
 	portBASE_TYPE xQueueGiveMutexRecursive( xQueueHandle pxMutex )
 	{