Add comments to the portASSERT_IF_INTERRUPT_PRIORITY_INVALID() calls in the core...

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

diff --git a/FreeRTOS/Source/queue.c b/FreeRTOS/Source/queue.c
index ec665174b5df6cc07657336a091311859a046911..2532aa9ab68820af0b7168fbe48fb9c6bec31d4c 100644 (file)
--- a/FreeRTOS/Source/queue.c
+++ b/FreeRTOS/Source/queue.c
@@ -940,6 +940,21 @@ xQUEUE *pxQueue;
        configASSERT( pxQueue );\r
        configASSERT( !( ( pvItemToQueue == NULL ) && ( pxQueue->uxItemSize != ( unsigned portBASE_TYPE ) 0U ) ) );\r
        configASSERT( !( ( xCopyPosition == queueOVERWRITE ) && ( pxQueue->uxLength != 1 ) ) );\r
+\r
+       /* RTOS ports that support interrupt nesting have the concept of a maximum\r
+       system call (or maximum API call) interrupt priority.  Interrupts that are\r
+       above the maximum system call priority are keep permanently enabled, even\r
+       when the RTOS kernel is in a critical section, but cannot make any calls to\r
+       FreeRTOS API functions.  If configASSERT() is defined in FreeRTOSConfig.h\r
+       then portASSERT_IF_INTERRUPT_PRIORITY_INVALID() will result in an assertion\r
+       failure if a FreeRTOS API function is called from an interrupt that has been\r
+       assigned a priority above the configured maximum system call priority.\r
+       Only FreeRTOS functions that end in FromISR can be called from interrupts\r
+       that have been assigned a priority at or (logically) below the maximum\r
+       system call     interrupt priority.  FreeRTOS maintains a separate interrupt\r
+       safe API to ensure interrupt entry is as fast and as simple as possible.\r
+       More information (albeit Cortex-M specific) is provided on the following\r
+       link: http://www.freertos.org/RTOS-Cortex-M3-M4.html */\r
        portASSERT_IF_INTERRUPT_PRIORITY_INVALID();\r
 \r
        /* Similar to xQueueGenericSend, except we don't block if there is no room\r
@@ -1189,6 +1204,21 @@ xQUEUE *pxQueue;
        pxQueue = ( xQUEUE * ) xQueue;\r
        configASSERT( pxQueue );\r
        configASSERT( !( ( pvBuffer == NULL ) && ( pxQueue->uxItemSize != ( unsigned portBASE_TYPE ) 0U ) ) );\r
+\r
+       /* RTOS ports that support interrupt nesting have the concept of a maximum\r
+       system call (or maximum API call) interrupt priority.  Interrupts that are\r
+       above the maximum system call priority are keep permanently enabled, even \r
+       when the RTOS kernel is in a critical section, but cannot make any calls to\r
+       FreeRTOS API functions.  If configASSERT() is defined in FreeRTOSConfig.h \r
+       then portASSERT_IF_INTERRUPT_PRIORITY_INVALID() will result in an assertion\r
+       failure if a FreeRTOS API function is called from an interrupt that has been\r
+       assigned a priority above the configured maximum system call priority.\r
+       Only FreeRTOS functions that end in FromISR can be called from interrupts\r
+       that have been assigned a priority at or (logically) below the maximum \r
+       system call     interrupt priority.  FreeRTOS maintains a separate interrupt \r
+       safe API to ensure interrupt entry is as fast and as simple as possible.  \r
+       More information (albeit Cortex-M specific) is provided on the following \r
+       link: http://www.freertos.org/RTOS-Cortex-M3-M4.html */\r
        portASSERT_IF_INTERRUPT_PRIORITY_INVALID();\r
 \r
        uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();\r
@@ -1251,6 +1281,21 @@ xQUEUE *pxQueue;
        pxQueue = ( xQUEUE * ) xQueue;\r
        configASSERT( pxQueue );\r
        configASSERT( !( ( pvBuffer == NULL ) && ( pxQueue->uxItemSize != ( unsigned portBASE_TYPE ) 0U ) ) );\r
+\r
+       /* RTOS ports that support interrupt nesting have the concept of a maximum\r
+       system call (or maximum API call) interrupt priority.  Interrupts that are\r
+       above the maximum system call priority are keep permanently enabled, even \r
+       when the RTOS kernel is in a critical section, but cannot make any calls to\r
+       FreeRTOS API functions.  If configASSERT() is defined in FreeRTOSConfig.h \r
+       then portASSERT_IF_INTERRUPT_PRIORITY_INVALID() will result in an assertion\r
+       failure if a FreeRTOS API function is called from an interrupt that has been\r
+       assigned a priority above the configured maximum system call priority.\r
+       Only FreeRTOS functions that end in FromISR can be called from interrupts\r
+       that have been assigned a priority at or (logically) below the maximum \r
+       system call     interrupt priority.  FreeRTOS maintains a separate interrupt \r
+       safe API to ensure interrupt entry is as fast and as simple as possible.  \r
+       More information (albeit Cortex-M specific) is provided on the following \r
+       link: http://www.freertos.org/RTOS-Cortex-M3-M4.html */\r
        portASSERT_IF_INTERRUPT_PRIORITY_INVALID();\r
 \r
        uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();\r

diff --git a/FreeRTOS/Source/tasks.c b/FreeRTOS/Source/tasks.c
index dc4f6010782133ccd1f0e64ac2ceb03c0f46ef91..225e61cf085c4528aa42c89571311c4cb9f8de81 100644 (file)
--- a/FreeRTOS/Source/tasks.c
+++ b/FreeRTOS/Source/tasks.c
@@ -1176,6 +1176,23 @@ tskTCB * pxNewTCB;
        unsigned portBASE_TYPE uxSavedInterruptStatus;\r
 \r
                configASSERT( xTaskToResume );\r
+\r
+               /* RTOS ports that support interrupt nesting have the concept of a \r
+               maximum system call (or maximum API call) interrupt priority.  \r
+               Interrupts that are     above the maximum system call priority are keep \r
+               permanently enabled, even when the RTOS kernel is in a critical section, \r
+               but cannot make any calls to FreeRTOS API functions.  If configASSERT() \r
+               is defined in FreeRTOSConfig.h then \r
+               portASSERT_IF_INTERRUPT_PRIORITY_INVALID() will result in an assertion\r
+               failure if a FreeRTOS API function is called from an interrupt that has \r
+               been assigned a priority above the configured maximum system call \r
+               priority.  Only FreeRTOS functions that end in FromISR can be called \r
+               from interrupts that have been assigned a priority at or (logically) \r
+               below the maximum system call interrupt priority.  FreeRTOS maintains a \r
+               separate interrupt safe API to ensure interrupt entry is as fast and as \r
+               simple as possible.  More information (albeit Cortex-M specific) is \r
+               provided on the following link: \r
+               http://www.freertos.org/RTOS-Cortex-M3-M4.html */\r
                portASSERT_IF_INTERRUPT_PRIORITY_INVALID();\r
 \r
                pxTCB = ( tskTCB * ) xTaskToResume;\r
@@ -1415,6 +1432,20 @@ portTickType xTaskGetTickCountFromISR( void )
 portTickType xReturn;\r
 unsigned portBASE_TYPE uxSavedInterruptStatus;\r
 \r
+       /* RTOS ports that support interrupt nesting have the concept of a maximum\r
+       system call (or maximum API call) interrupt priority.  Interrupts that are\r
+       above the maximum system call priority are keep permanently enabled, even \r
+       when the RTOS kernel is in a critical section, but cannot make any calls to\r
+       FreeRTOS API functions.  If configASSERT() is defined in FreeRTOSConfig.h \r
+       then portASSERT_IF_INTERRUPT_PRIORITY_INVALID() will result in an assertion\r
+       failure if a FreeRTOS API function is called from an interrupt that has been\r
+       assigned a priority above the configured maximum system call priority.\r
+       Only FreeRTOS functions that end in FromISR can be called from interrupts\r
+       that have been assigned a priority at or (logically) below the maximum \r
+       system call     interrupt priority.  FreeRTOS maintains a separate interrupt \r
+       safe API to ensure interrupt entry is as fast and as simple as possible.  \r
+       More information (albeit Cortex-M specific) is provided on the following \r
+       link: http://www.freertos.org/RTOS-Cortex-M3-M4.html */\r
        portASSERT_IF_INTERRUPT_PRIORITY_INVALID();\r
        \r
        uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();\r