From: RichardBarry <RichardBarry@1d2547de-c912-0410-9cb9-b8ca96c0e9e2>
Date: Thu, 6 Dec 2007 10:19:28 +0000 (+0000)
Subject: Update documentation.
X-Git-Tag: V4.7.1~21
X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=ca9ce82ac4787fd62d3560c56c441b1cee8bfd71;p=freertos

Update documentation.

git-svn-id: https://svn.code.sf.net/p/freertos/code/trunk@127 1d2547de-c912-0410-9cb9-b8ca96c0e9e2
---

diff --git a/Source/include/queue.h b/Source/include/queue.h
index b093e7c1a..bafb56619 100644
--- a/Source/include/queue.h
+++ b/Source/include/queue.h
@@ -1160,25 +1160,21 @@ signed portBASE_TYPE xQueueGenericSendFromISR( xQueueHandle pxQueue, const void
 signed portBASE_TYPE xQueueReceiveFromISR( xQueueHandle pxQueue, const void * const pvBuffer, signed portBASE_TYPE *pxTaskWoken );
 
 /* 
- * xQueueAltGenericSend() is a light weight version of xQueueGenericSend().
- * Likewise xQueueAltGenericReceive() is a light weight version of
+ * xQueueAltGenericSend() is an alternative version of xQueueGenericSend().
+ * Likewise xQueueAltGenericReceive() is an alternative version of
  * xQueueGenericReceive().
  *
- * The source code that implements the light weight (fast) API is much 
+ * The source code that implements the alternative (Alt) API is much 
  * simpler	because it executes everything from within a critical section.  
  * This is	the approach taken by many other RTOSes, but FreeRTOS.org has the 
- * fully featured API as an alternative.  The fully featured API has more 
+ * preferred fully featured API too.  The fully featured API has more 
  * complex	code that takes longer to execute, but makes much less use of 
- * critical sections.  Therefore the light weight API sacrifices interrupt 
+ * critical sections.  Therefore the alternative API sacrifices interrupt 
  * responsiveness to gain execution speed, whereas the fully featured API
  * sacrifices execution speed to ensure better interrupt responsiveness.
  */
 signed portBASE_TYPE xQueueAltGenericSend( xQueueHandle pxQueue, const void * const pvItemToQueue, portTickType xTicksToWait, portBASE_TYPE xCopyPosition );
 signed portBASE_TYPE xQueueAltGenericReceive( xQueueHandle pxQueue, const void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeeking );
-
-/*
- * The light weight versions of the fully featured macros.
- */
 #define xQueueAltSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_FRONT )
 #define xQueueAltSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_BACK )
 #define xQueueAltReceive( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( xQueue, pvBuffer, xTicksToWait, pdFALSE )
diff --git a/Source/include/semphr.h b/Source/include/semphr.h
index 75d6e8a33..c14af05b5 100644
--- a/Source/include/semphr.h
+++ b/Source/include/semphr.h
@@ -155,6 +155,19 @@ typedef xQueueHandle xSemaphoreHandle;
  * \ingroup Semaphores
  */
 #define xSemaphoreTake( xSemaphore, xBlockTime )		xQueueGenericReceive( ( xQueueHandle ) xSemaphore, NULL, xBlockTime, pdFALSE )
+
+/* 
+ * xSemaphoreAltTake() is an alternative version of xSemaphoreTake().
+ *
+ * The source code that implements the alternative (Alt) API is much 
+ * simpler	because it executes everything from within a critical section.  
+ * This is	the approach taken by many other RTOSes, but FreeRTOS.org has the 
+ * preferred fully featured API too.  The fully featured API has more 
+ * complex	code that takes longer to execute, but makes much less use of 
+ * critical sections.  Therefore the alternative API sacrifices interrupt 
+ * responsiveness to gain execution speed, whereas the fully featured API
+ * sacrifices execution speed to ensure better interrupt responsiveness.
+ */
 #define xSemaphoreAltTake( xSemaphore, xBlockTime )		xQueueAltGenericReceive( ( xQueueHandle ) xSemaphore, NULL, xBlockTime, pdFALSE )
 
 /**
@@ -215,6 +228,19 @@ typedef xQueueHandle xSemaphoreHandle;
  * \ingroup Semaphores
  */
 #define xSemaphoreGive( xSemaphore )		xQueueGenericSend( ( xQueueHandle ) xSemaphore, NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )
+
+/* 
+ * xSemaphoreAltGive() is an alternative version of xSemaphoreGive().
+ *
+ * The source code that implements the alternative (Alt) API is much 
+ * simpler	because it executes everything from within a critical section.  
+ * This is	the approach taken by many other RTOSes, but FreeRTOS.org has the 
+ * preferred fully featured API too.  The fully featured API has more 
+ * complex	code that takes longer to execute, but makes much less use of 
+ * critical sections.  Therefore the alternative API sacrifices interrupt 
+ * responsiveness to gain execution speed, whereas the fully featured API
+ * sacrifices execution speed to ensure better interrupt responsiveness.
+ */
 #define xSemaphoreAltGive( xSemaphore )		xQueueAltGenericSend( ( xQueueHandle ) xSemaphore, NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )
 
 /**
@@ -313,7 +339,7 @@ typedef xQueueHandle xSemaphoreHandle;
  *
  * Mutex type semaphores cannot be used from within interrupt service routines.  
  *
- * See xSemaphoreCreateBinary() for an alternative implemnetation that can be 
+ * See xSemaphoreCreateBinary() for an alternative implementation that can be 
  * used for pure synchronisation (where one task or interrupt always 'gives' the 
  * semaphore and another always 'takes' the semaphore) and from within interrupt 
  * service routines.
diff --git a/Source/queue.c b/Source/queue.c
index 80b014966..67e24e9c3 100644
--- a/Source/queue.c
+++ b/Source/queue.c
@@ -464,12 +464,12 @@ xTimeOutType xTimeOut;
 	signed portBASE_TYPE xReturn;
 	xTimeOutType xTimeOut;
 
-		/* The source code that implements the light weight (fast) API is much 
+		/* The source code that implements the alternative (Alt) API is much 
 		simpler	because it executes everything from within a critical section.  
 		This is	the approach taken by many other RTOSes, but FreeRTOS.org has the 
-		fully featured API as an alternative.  The fully featured API has more 
+		preferred fully featured API too.  The fully featured API has more 
 		complex	code that takes longer to execute, but makes much less use of 
-		critical sections.  Therefore the light weight API sacrifices interrupt 
+		critical sections.  Therefore the alternative API sacrifices interrupt 
 		responsiveness to gain execution speed, whereas the fully featured API
 		sacrifices execution speed to ensure better interrupt responsiveness.  */
 
@@ -528,10 +528,6 @@ xTimeOutType xTimeOut;
 							xReturn = queueERRONEOUS_UNBLOCK;
 						}
 					}
-					else
-					{
-						
-					}
 				}
 			}
 			while( xReturn == queueERRONEOUS_UNBLOCK );
@@ -552,12 +548,12 @@ xTimeOutType xTimeOut;
 	xTimeOutType xTimeOut;
 	signed portCHAR *pcOriginalReadPosition;
 
-		/* The source code that implements the light weight (fast) API is much 
+		/* The source code that implements the alternative (Alt) API is much 
 		simpler	because it executes everything from within a critical section.  
 		This is	the approach taken by many other RTOSes, but FreeRTOS.org has the 
-		fully featured API as an alternative.  The fully featured API has more 
+		preferred fully featured API too.  The fully featured API has more 
 		complex	code that takes longer to execute, but makes much less use of 
-		critical sections.  Therefore the light weight API sacrifices interrupt 
+		critical sections.  Therefore the alternative API sacrifices interrupt 
 		responsiveness to gain execution speed, whereas the fully featured API
 		sacrifices execution speed to ensure better interrupt responsiveness.  */