Add xSemaphoreCreateBinary() so vSemaphoreCreate() can be deprecated.

FreeRTOS/Source/include/semphr.h

@@ -83,6 +83,13 @@ typedef xQueueHandle xSemaphoreHandle;
  * semphr. h
  * <pre>vSemaphoreCreateBinary( xSemaphoreHandle xSemaphore )</pre>
  *
+ * This old vSemaphoreCreateBinary() macro is now deprecated in favour of the
+ * xSemaphoreCreateBinary() function.  Note that binary semaphores created using
+ * the vSemaphoreCreateBinary() macro are created in a state such that the
+ * first call to 'take' the semaphore would pass, whereas binary semaphores
+ * created using xSemaphoreCreateBinary() are created in a state such that the
+ * the semaphore must first be 'given' before it can be 'taken'.
+ *
  * <i>Macro</i> that implements a semaphore by using the existing queue mechanism.
  * The queue length is 1 as this is a binary semaphore.  The data size is 0
  * as we don't want to actually store any data - we just want to know if the
@@ -99,7 +106,7 @@ typedef xQueueHandle xSemaphoreHandle;
  *
  * Example usage:
  <pre>
- xSemaphoreHandle xSemaphore;
+ xSemaphoreHandle xSemaphore = NULL;
 
  void vATask( void * pvParameters )
  {
@@ -122,10 +129,57 @@ typedef xQueueHandle xSemaphoreHandle;
 		( xSemaphore ) = xQueueGenericCreate( ( unsigned portBASE_TYPE ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE );	\
 		if( ( xSemaphore ) != NULL )																											\
 		{																																		\
-			( void ) xSemaphoreGive( ( xSemaphore ) );																									\
+			( void ) xSemaphoreGive( ( xSemaphore ) );																							\
 		}																																		\
 	}
 
+/**
+ * semphr. h
+ * <pre>xSemaphoreHandle xSemaphoreCreateBinary( void )</pre>
+ *
+ * The old vSemaphoreCreateBinary() macro is now deprecated in favour of this
+ * xSemaphoreCreateBinary() function.  Note that binary semaphores created using
+ * the vSemaphoreCreateBinary() macro are created in a state such that the
+ * first call to 'take' the semaphore would pass, whereas binary semaphores
+ * created using xSemaphoreCreateBinary() are created in a state such that the
+ * the semaphore must first be 'given' before it can be 'taken'.
+ *
+ * Function that creates a semaphore by using the existing queue mechanism.
+ * The queue length is 1 as this is a binary semaphore.  The data size is 0
+ * as nothing is actually stored - all that is important is whether the queue is
+ * empty or full (the binary semaphore is available or not).
+ *
+ * This type of semaphore can be used for pure synchronisation between tasks or
+ * between an interrupt and a task.  The semaphore need not be given back once
+ * obtained, so one task/interrupt can continuously 'give' the semaphore while
+ * another continuously 'takes' the semaphore.  For this reason this type of
+ * semaphore does not use a priority inheritance mechanism.  For an alternative
+ * that does use priority inheritance see xSemaphoreCreateMutex().
+ *
+ * @return Handle to the created semaphore.
+ *
+ * Example usage:
+ <pre>
+ xSemaphoreHandle xSemaphore = NULL;
+
+ void vATask( void * pvParameters )
+ {
+    // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().
+    // This is a macro so pass the variable in directly.
+    xSemaphore = xSemaphoreCreateBinary();
+
+    if( xSemaphore != NULL )
+    {
+        // The semaphore was created successfully.
+        // The semaphore can now be used.
+    }
+ }
+ </pre>
+ * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary
+ * \ingroup Semaphores
+ */
+#define xSemaphoreCreateBinary() xQueueGenericCreate( ( unsigned portBASE_TYPE ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE )
+
 /**
  * semphr. h
  * <pre>xSemaphoreTake(