From 507572c6a77df0bcd886610a09afda643a0f3432 Mon Sep 17 00:00:00 2001
From: richardbarry <richardbarry@1d2547de-c912-0410-9cb9-b8ca96c0e9e2>
Date: Tue, 14 Aug 2012 13:04:22 +0000
Subject: [PATCH] Put comments in the code that give a reference to people who
 think that setting BASE_PRI to zero is the wrong thing to to in an ISR.

git-svn-id: https://svn.code.sf.net/p/freertos/code/trunk@1772 1d2547de-c912-0410-9cb9-b8ca96c0e9e2
---
 FreeRTOS/Source/portable/GCC/ARM_CM3/portmacro.h   |  6 +++++-
 .../Source/portable/GCC/ARM_CM3_MPU/portmacro.h    |  5 ++++-
 FreeRTOS/Source/portable/GCC/ARM_CM4F/portmacro.h  |  6 +++++-
 FreeRTOS/Source/portable/IAR/ARM_CM3/portasm.s     | 14 ++++++--------
 FreeRTOS/Source/portable/IAR/ARM_CM3/portmacro.h   |  3 +++
 FreeRTOS/Source/portable/IAR/ARM_CM4F/portasm.s    |  2 ++
 FreeRTOS/Source/portable/IAR/ARM_CM4F/portmacro.h  |  3 +++
 FreeRTOS/Source/portable/RVDS/ARM_CM3/port.c       |  6 ++----
 FreeRTOS/Source/portable/RVDS/ARM_CM3/portmacro.h  |  3 +++
 FreeRTOS/Source/portable/RVDS/ARM_CM4F/port.c      |  2 ++
 FreeRTOS/Source/portable/RVDS/ARM_CM4F/portmacro.h |  3 +++
 .../Source/portable/Tasking/ARM_CM4F/portmacro.h   |  5 ++++-
 12 files changed, 42 insertions(+), 16 deletions(-)

diff --git a/FreeRTOS/Source/portable/GCC/ARM_CM3/portmacro.h b/FreeRTOS/Source/portable/GCC/ARM_CM3/portmacro.h
index a0c3e94c0..80e2d67c5 100644
--- a/FreeRTOS/Source/portable/GCC/ARM_CM3/portmacro.h
+++ b/FreeRTOS/Source/portable/GCC/ARM_CM3/portmacro.h
@@ -132,7 +132,8 @@ extern void vPortYieldFromISR( void );
 	
 /*
  * Set basepri back to 0 without effective other registers.
- * r0 is clobbered.
+ * r0 is clobbered.  FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+ * http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing.
  */
 #define portCLEAR_INTERRUPT_MASK()			\
 	__asm volatile							\
@@ -142,6 +143,9 @@ extern void vPortYieldFromISR( void );
 		:::"r0"								\
 	)
 
+/* FAQ:  Setting BASEPRI to 0 in portCLEAR_INTERRUPT_MASK_FROM_ISR() is not a 
+bug.  Please see http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before 
+disagreeing. */
 #define portSET_INTERRUPT_MASK_FROM_ISR()		0;portSET_INTERRUPT_MASK()
 #define portCLEAR_INTERRUPT_MASK_FROM_ISR(x)	portCLEAR_INTERRUPT_MASK();(void)x
 
diff --git a/FreeRTOS/Source/portable/GCC/ARM_CM3_MPU/portmacro.h b/FreeRTOS/Source/portable/GCC/ARM_CM3_MPU/portmacro.h
index 164619574..7b15dcce7 100644
--- a/FreeRTOS/Source/portable/GCC/ARM_CM3_MPU/portmacro.h
+++ b/FreeRTOS/Source/portable/GCC/ARM_CM3_MPU/portmacro.h
@@ -173,7 +173,8 @@ typedef struct MPU_SETTINGS
 
 /*
  * Set basepri back to 0 without effective other registers.
- * r0 is clobbered.
+ * r0 is clobbered.  FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+ * http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing.
  */
 #define portCLEAR_INTERRUPT_MASK()			\
 	__asm volatile							\
@@ -183,6 +184,8 @@ typedef struct MPU_SETTINGS
 		:::"r0"								\
 	)
 
+/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
 #define portSET_INTERRUPT_MASK_FROM_ISR()		0;portSET_INTERRUPT_MASK()
 #define portCLEAR_INTERRUPT_MASK_FROM_ISR(x)	portCLEAR_INTERRUPT_MASK();(void)x
 
diff --git a/FreeRTOS/Source/portable/GCC/ARM_CM4F/portmacro.h b/FreeRTOS/Source/portable/GCC/ARM_CM4F/portmacro.h
index ddb14071e..798be5e09 100644
--- a/FreeRTOS/Source/portable/GCC/ARM_CM4F/portmacro.h
+++ b/FreeRTOS/Source/portable/GCC/ARM_CM4F/portmacro.h
@@ -132,7 +132,8 @@ extern void vPortYieldFromISR( void );
 	
 /*
  * Set basepri back to 0 without effective other registers.
- * r0 is clobbered.
+ * r0 is clobbered.  FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+ * http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing.
  */
 #define portCLEAR_INTERRUPT_MASK()			\
 	__asm volatile							\
@@ -142,6 +143,9 @@ extern void vPortYieldFromISR( void );
 		:::"r0"								\
 	)
 
+/* FAQ:  Setting BASEPRI to 0 in portCLEAR_INTERRUPT_MASK_FROM_ISR() is not a 
+bug.  Please see http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before 
+disagreeing. */
 #define portSET_INTERRUPT_MASK_FROM_ISR()		0;portSET_INTERRUPT_MASK()
 #define portCLEAR_INTERRUPT_MASK_FROM_ISR(x)	portCLEAR_INTERRUPT_MASK();(void)x
 
diff --git a/FreeRTOS/Source/portable/IAR/ARM_CM3/portasm.s b/FreeRTOS/Source/portable/IAR/ARM_CM3/portasm.s
index e6f0221f1..c9e0bb3ca 100644
--- a/FreeRTOS/Source/portable/IAR/ARM_CM3/portasm.s
+++ b/FreeRTOS/Source/portable/IAR/ARM_CM3/portasm.s
@@ -123,20 +123,18 @@ xPortPendSVHandler:
 /*-----------------------------------------------------------*/
 
 vPortSetInterruptMask:
-	push { r0 }
-	mov R0, #configMAX_SYSCALL_INTERRUPT_PRIORITY
-	msr BASEPRI, R0
-	pop { R0 }
+	mov r0, #configMAX_SYSCALL_INTERRUPT_PRIORITY
+	msr BASEPRI, r0
 
 	bx r14
 	
 /*-----------------------------------------------------------*/
 
 vPortClearInterruptMask:
-	PUSH { r0 }
-	MOV R0, #0
-	MSR BASEPRI, R0
-	POP	 { R0 }
+	/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+	http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
+	mov r0, #0
+	msr BASEPRI, r0
 
 	bx r14
 
diff --git a/FreeRTOS/Source/portable/IAR/ARM_CM3/portmacro.h b/FreeRTOS/Source/portable/IAR/ARM_CM3/portmacro.h
index f8bbd4600..939b640b5 100644
--- a/FreeRTOS/Source/portable/IAR/ARM_CM3/portmacro.h
+++ b/FreeRTOS/Source/portable/IAR/ARM_CM3/portmacro.h
@@ -127,6 +127,9 @@ extern void vPortClearInterruptMask( void );
 #define portENABLE_INTERRUPTS()		vPortClearInterruptMask()
 #define portENTER_CRITICAL()					vPortEnterCritical()
 #define portEXIT_CRITICAL()						vPortExitCritical()
+
+/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
 #define portSET_INTERRUPT_MASK_FROM_ISR()		0;vPortSetInterruptMask()
 #define portCLEAR_INTERRUPT_MASK_FROM_ISR(x)	vPortClearInterruptMask();(void)x
 
diff --git a/FreeRTOS/Source/portable/IAR/ARM_CM4F/portasm.s b/FreeRTOS/Source/portable/IAR/ARM_CM4F/portasm.s
index 94ac95c21..26eb6267e 100644
--- a/FreeRTOS/Source/portable/IAR/ARM_CM4F/portasm.s
+++ b/FreeRTOS/Source/portable/IAR/ARM_CM4F/portasm.s
@@ -136,6 +136,8 @@ vPortSetInterruptMask:
 /*-----------------------------------------------------------*/
 
 vPortClearInterruptMask:
+	/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+	http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
 	mov r0, #0
 	msr BASEPRI, r0
 
diff --git a/FreeRTOS/Source/portable/IAR/ARM_CM4F/portmacro.h b/FreeRTOS/Source/portable/IAR/ARM_CM4F/portmacro.h
index d4ec8c1e9..b88474d2b 100644
--- a/FreeRTOS/Source/portable/IAR/ARM_CM4F/portmacro.h
+++ b/FreeRTOS/Source/portable/IAR/ARM_CM4F/portmacro.h
@@ -127,6 +127,9 @@ extern void vPortClearInterruptMask( void );
 #define portENABLE_INTERRUPTS()		vPortClearInterruptMask()
 #define portENTER_CRITICAL()					vPortEnterCritical()
 #define portEXIT_CRITICAL()						vPortExitCritical()
+
+/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
 #define portSET_INTERRUPT_MASK_FROM_ISR()		0;vPortSetInterruptMask()
 #define portCLEAR_INTERRUPT_MASK_FROM_ISR(x)	vPortClearInterruptMask();(void)x
 
diff --git a/FreeRTOS/Source/portable/RVDS/ARM_CM3/port.c b/FreeRTOS/Source/portable/RVDS/ARM_CM3/port.c
index 20a2fce43..d109cecd3 100644
--- a/FreeRTOS/Source/portable/RVDS/ARM_CM3/port.c
+++ b/FreeRTOS/Source/portable/RVDS/ARM_CM3/port.c
@@ -294,10 +294,8 @@ __asm void vPortSetInterruptMask( void )
 {
 	PRESERVE8
 
-	push { r0 }
 	mov r0, #configMAX_SYSCALL_INTERRUPT_PRIORITY
 	msr basepri, r0
-	pop { r0 }
 	bx r14
 }
 
@@ -307,9 +305,9 @@ __asm void vPortClearInterruptMask( void )
 {
 	PRESERVE8
 
-	push { r0 }
+	/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+	http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
 	mov r0, #0
 	msr basepri, r0
-	pop { r0 }
 	bx r14
 }
diff --git a/FreeRTOS/Source/portable/RVDS/ARM_CM3/portmacro.h b/FreeRTOS/Source/portable/RVDS/ARM_CM3/portmacro.h
index e78487551..0b60eb202 100644
--- a/FreeRTOS/Source/portable/RVDS/ARM_CM3/portmacro.h
+++ b/FreeRTOS/Source/portable/RVDS/ARM_CM3/portmacro.h
@@ -127,6 +127,9 @@ extern void vPortExitCritical( void );
 #define portENABLE_INTERRUPTS()					vPortClearInterruptMask()
 #define portENTER_CRITICAL()					vPortEnterCritical()
 #define portEXIT_CRITICAL()						vPortExitCritical()
+
+/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
 #define portSET_INTERRUPT_MASK_FROM_ISR()		0;vPortSetInterruptMask()
 #define portCLEAR_INTERRUPT_MASK_FROM_ISR(x)	vPortClearInterruptMask();(void)x
 
diff --git a/FreeRTOS/Source/portable/RVDS/ARM_CM4F/port.c b/FreeRTOS/Source/portable/RVDS/ARM_CM4F/port.c
index 42d56df9c..a8fdad686 100644
--- a/FreeRTOS/Source/portable/RVDS/ARM_CM4F/port.c
+++ b/FreeRTOS/Source/portable/RVDS/ARM_CM4F/port.c
@@ -369,6 +369,8 @@ __asm void vPortClearInterruptMask( void )
 {
 	PRESERVE8
 
+	/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+	http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
 	mov r0, #0
 	msr basepri, r0
 	bx r14
diff --git a/FreeRTOS/Source/portable/RVDS/ARM_CM4F/portmacro.h b/FreeRTOS/Source/portable/RVDS/ARM_CM4F/portmacro.h
index 5b55a9c53..e3b86b0ed 100644
--- a/FreeRTOS/Source/portable/RVDS/ARM_CM4F/portmacro.h
+++ b/FreeRTOS/Source/portable/RVDS/ARM_CM4F/portmacro.h
@@ -127,6 +127,9 @@ extern void vPortExitCritical( void );
 #define portENABLE_INTERRUPTS()					vPortClearInterruptMask()
 #define portENTER_CRITICAL()					vPortEnterCritical()
 #define portEXIT_CRITICAL()						vPortExitCritical()
+
+/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
 #define portSET_INTERRUPT_MASK_FROM_ISR()		0;vPortSetInterruptMask()
 #define portCLEAR_INTERRUPT_MASK_FROM_ISR(x)	vPortClearInterruptMask();(void)x
 
diff --git a/FreeRTOS/Source/portable/Tasking/ARM_CM4F/portmacro.h b/FreeRTOS/Source/portable/Tasking/ARM_CM4F/portmacro.h
index 5766789a1..ea1e8786a 100644
--- a/FreeRTOS/Source/portable/Tasking/ARM_CM4F/portmacro.h
+++ b/FreeRTOS/Source/portable/Tasking/ARM_CM4F/portmacro.h
@@ -126,10 +126,13 @@ extern void vPortYieldFromISR( void );
 	
 /*
  * Set basepri back to 0 without effective other registers.
- * r0 is clobbered.
+ * r0 is clobbered.  FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+ * http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing.
  */
 #define portCLEAR_INTERRUPT_MASK() __set_BASEPRI( 0 )
 
+/* FAQ:  Setting BASEPRI to 0 is not a bug.  Please see 
+http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html before disagreeing. */
 #define portSET_INTERRUPT_MASK_FROM_ISR()		0;portSET_INTERRUPT_MASK()
 #define portCLEAR_INTERRUPT_MASK_FROM_ISR(x)	portCLEAR_INTERRUPT_MASK();(void)x
 
-- 
2.39.5