--- /dev/null
+[{000214A0-0000-0000-C000-000000000046}]\r
+Prop3=19,2\r
+[InternetShortcut]\r
+URL=http://www.freertos.org/labs\r
+IDList=\r
#define configUSE_PORT_OPTIMISED_TASK_SELECTION 1\r
#define configUSE_IDLE_HOOK 1\r
#define configUSE_TICK_HOOK 1\r
+#define configUSE_DAEMON_TASK_STARTUP_HOOK 1\r
#define configTICK_RATE_HZ ( 1000 ) /* In this non-real time simulated environment the tick frequency has to be at least a multiple of the Win32 tick frequency, and therefore very slow. */\r
#define configMINIMAL_STACK_SIZE ( ( unsigned short ) 50 ) /* In this simulated case, the stack only has to hold one small structure as the real stack is part of the win32 thread. */\r
#define configTOTAL_HEAP_SIZE ( ( size_t ) ( 24 * 1024 ) )\r
#define INCLUDE_xTimerGetTimerDaemonTaskHandle 1\r
#define INCLUDE_xTaskGetIdleTaskHandle 1\r
#define INCLUDE_pcTaskGetTaskName 1\r
+#define INCLUDE_xTaskGetTaskHandle 1\r
#define INCLUDE_eTaskGetState 1\r
#define INCLUDE_xSemaphoreGetMutexHolder 1\r
#define INCLUDE_xTimerPendFunctionCall 1\r
void vApplicationIdleHook( void );\r
void vApplicationStackOverflowHook( TaskHandle_t pxTask, char *pcTaskName );\r
void vApplicationTickHook( void );\r
-void vApplicationGetIdleTaskMemory( DummyTCB_t **ppxIdleTaskTCBBuffer, StackType_t **ppxIdleTaskStackBuffer, uint16_t *pusIdleTaskStackSize );\r
-void vApplicationGetTimerTaskMemory( DummyTCB_t **ppxTimerTaskTCBBuffer, StackType_t **ppxTimerTaskStackBuffer, uint16_t *pusTimerTaskStackSize );\r
+void vApplicationGetIdleTaskMemory( StaticTask_t **ppxIdleTaskTCBBuffer, StackType_t **ppxIdleTaskStackBuffer, uint16_t *pusIdleTaskStackSize );\r
+void vApplicationGetTimerTaskMemory( StaticTask_t **ppxTimerTaskTCBBuffer, StackType_t **ppxTimerTaskStackBuffer, uint16_t *pusTimerTaskStackSize );\r
\r
/*\r
* Writes trace data to a disk file when the trace recording is stopped.\r
*/\r
static void prvSaveTraceFile( void );\r
\r
+/*-----------------------------------------------------------*/\r
+\r
+/* When configSUPPORT_STATIC_ALLOCATION is set to 1 the application writer can\r
+use a callback function to optionally provide the memory required by the idle\r
+and timer tasks. This is the stack that will be used by the timer task. It is\r
+declared here, as a global, so it can be checked by a test that is implemented\r
+in a different file. */\r
+StackType_t uxTimerTaskStack[ configTIMER_TASK_STACK_DEPTH ];\r
+\r
/* The user trace event posted to the trace recording on each tick interrupt.\r
Note: This project runs under Windows, and Windows will not be executing the\r
RTOS threads continuously. Therefore tick events will not appear with a regular\r
}\r
/*-----------------------------------------------------------*/\r
\r
+void vApplicationDaemonTaskStartupHook( void )\r
+{\r
+ /* This function will be called once only, when the daemon task starts to\r
+ execute (sometimes called the timer task). This is useful if the\r
+ application includes initialisation code that would benefit from executing\r
+ after the scheduler has been started. */\r
+}\r
+/*-----------------------------------------------------------*/\r
+\r
void vAssertCalled( unsigned long ulLine, const char * const pcFileName )\r
{\r
static portBASE_TYPE xPrinted = pdFALSE;\r
}\r
/*-----------------------------------------------------------*/\r
\r
-void vApplicationGetIdleTaskMemory( DummyTCB_t **ppxIdleTaskTCBBuffer, StackType_t **ppxIdleTaskStackBuffer, uint16_t *pusIdleTaskStackSize )\r
+void vApplicationGetIdleTaskMemory( StaticTask_t **ppxIdleTaskTCBBuffer, StackType_t **ppxIdleTaskStackBuffer, uint16_t *pusIdleTaskStackSize )\r
{\r
/* The buffers used by the idle task must be static so they are persistent, and\r
so exist after this function returns. */\r
-static DummyTCB_t xIdleTaskTCB;\r
+static StaticTask_t xIdleTaskTCB;\r
static StackType_t uxIdleTaskStack[ configMINIMAL_STACK_SIZE ];\r
\r
/* configUSE_STATIC_ALLOCATION is set to 1, so the application has the\r
}\r
/*-----------------------------------------------------------*/\r
\r
-void vApplicationGetTimerTaskMemory( DummyTCB_t **ppxTimerTaskTCBBuffer, StackType_t **ppxTimerTaskStackBuffer, uint16_t *pusTimerTaskStackSize )\r
+void vApplicationGetTimerTaskMemory( StaticTask_t **ppxTimerTaskTCBBuffer, StackType_t **ppxTimerTaskStackBuffer, uint16_t *pusTimerTaskStackSize )\r
{\r
/* The buffers used by the Timer/Daemon task must be static so they are\r
-persistent, and so exist after this function returns. */\r
-static DummyTCB_t xTimerTaskTCB;\r
-static StackType_t uxTimerTaskStack[ configTIMER_TASK_STACK_DEPTH ];\r
+persistent, and so exist after this function returns. The stack buffer is\r
+not declared here, but globally, as it is checked by a test in a different\r
+file. */\r
+static StaticTask_t xTimerTaskTCB;\r
\r
/* configUSE_STATIC_ALLOCATION is set to 1, so the application has the\r
opportunity to supply the buffers that will be used by the Timer/RTOS daemon\r
vStartInterruptSemaphoreTasks();\r
vStartQueueSetPollingTask();\r
xTaskCreate( prvDemoQueueSpaceFunctions, "QSpace", configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );\r
- vStartStaticallyAllocatedTasks();\r
+\r
+ #if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
+ {\r
+ vStartStaticallyAllocatedTasks();\r
+ }\r
+ #endif\r
\r
#if( configUSE_PREEMPTION != 0 )\r
{\r
{\r
pcStatusMessage = "Error: Queue set polling";\r
}\r
- else if( xAreStaticAllocationTasksStillRunning() != pdPASS )\r
- {\r
- pcStatusMessage = "Error: Static allocation";\r
- }\r
+\r
+ #if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
+ else if( xAreStaticAllocationTasksStillRunning() != pdPASS )\r
+ {\r
+ pcStatusMessage = "Error: Static allocation";\r
+ }\r
+ #endif /* configSUPPORT_STATIC_ALLOCATION */\r
\r
/* This is the only task that uses stdout so its ok to call printf()\r
directly. */\r
that has tasks blocked on it. */\r
if( xMutexToDelete != NULL )\r
{\r
+ /* For test purposes, add the mutex to the registry, then remove it\r
+ again, before it is deleted - checking its name is as expected before\r
+ and after the assertion into the registry and its removal from the\r
+ registry. */\r
+ configASSERT( pcQueueGetQueueName( xMutexToDelete ) == NULL );\r
+ vQueueAddToRegistry( xMutexToDelete, "Test_Mutex" );\r
+ configASSERT( strcmp( pcQueueGetQueueName( xMutexToDelete ), "Test_Mutex" ) == 0 );\r
+ vQueueUnregisterQueue( xMutexToDelete );\r
+ configASSERT( pcQueueGetQueueName( xMutexToDelete ) == NULL );\r
+\r
vSemaphoreDelete( xMutexToDelete );\r
xMutexToDelete = NULL;\r
}\r
char *pcTaskName;\r
static portBASE_TYPE xPerformedOneShotTests = pdFALSE;\r
TaskHandle_t xTestTask;\r
+TaskStatus_t xTaskInfo;\r
+extern StackType_t uxTimerTaskStack[];\r
\r
/* Demonstrate the use of the xTimerGetTimerDaemonTaskHandle() and\r
xTaskGetIdleTaskHandle() functions. Also try using the function that sets\r
pcStatusMessage = "Error: Returned idle task handle was incorrect";\r
}\r
\r
+ /* Check the same handle is obtained using the idle task's name. First try\r
+ with the wrong name, then the right name. */\r
+ if( xTaskGetTaskHandle( "Idle" ) == xIdleTaskHandle )\r
+ {\r
+ pcStatusMessage = "Error: Returned handle for name Idle was incorrect";\r
+ }\r
+\r
+ if( xTaskGetTaskHandle( "IDLE" ) != xIdleTaskHandle )\r
+ {\r
+ pcStatusMessage = "Error: Returned handle for name Idle was incorrect";\r
+ }\r
+\r
/* Check the timer task handle was returned correctly. */\r
pcTaskName = pcTaskGetTaskName( xTimerTaskHandle );\r
if( strcmp( pcTaskName, "Tmr Svc" ) != 0 )\r
pcStatusMessage = "Error: Returned timer task handle was incorrect";\r
}\r
\r
+ if( xTaskGetTaskHandle( "Tmr Svc" ) != xTimerTaskHandle )\r
+ {\r
+ pcStatusMessage = "Error: Returned handle for name Tmr Svc was incorrect";\r
+ }\r
+\r
/* This task is running, make sure it's state is returned as running. */\r
if( eTaskStateGet( xIdleTaskHandle ) != eRunning )\r
{\r
pcStatusMessage = "Error: Returned timer task state was incorrect";\r
}\r
\r
+ /* Also with the vTaskGetTaskInfo() function. */\r
+ vTaskGetTaskInfo( xTimerTaskHandle, /* The task being queried. */\r
+ &xTaskInfo, /* The structure into which information on the task will be written. */\r
+ pdTRUE, /* Include the task's high watermark in the structure. */\r
+ eInvalid ); /* Include the task state in the structure. */\r
+\r
+ /* Check the information returned by vTaskGetTaskInfo() is as expected. */\r
+ if( ( xTaskInfo.eCurrentState != eBlocked ) ||\r
+ ( strcmp( xTaskInfo.pcTaskName, "Tmr Svc" ) != 0 ) ||\r
+ ( xTaskInfo.uxCurrentPriority != configTIMER_TASK_PRIORITY ) ||\r
+ ( xTaskInfo.pxStackBase != uxTimerTaskStack ) ||\r
+ ( xTaskInfo.xHandle != xTimerTaskHandle ) )\r
+ {\r
+ pcStatusMessage = "Error: vTaskGetTaskInfo() returned incorrect information about the timer task";\r
+ }\r
+\r
/* Other tests that should only be performed once follow. The test task\r
is not created on each iteration because to do so would cause the death\r
task to report an error (too many tasks running). */\r
#endif\r
#endif\r
\r
+#ifndef configUSE_DAEMON_TASK_STARTUP_HOOK\r
+ #define configUSE_DAEMON_TASK_STARTUP_HOOK 0\r
+#endif\r
+\r
#ifndef INCLUDE_xTaskGetIdleTaskHandle\r
#define INCLUDE_xTaskGetIdleTaskHandle 0\r
#endif\r
#define INCLUDE_pcTaskGetTaskName 0\r
#endif\r
\r
+#ifndef INCLUDE_xTaskGetTaskHandle\r
+ #define INCLUDE_xTaskGetTaskHandle 0\r
+#endif\r
+\r
#ifndef configUSE_APPLICATION_TASK_TAG\r
#define configUSE_APPLICATION_TASK_TAG 0\r
#endif\r
* hold the queue's data structure, removing the need for the memory to be\r
* allocated dynamically.\r
*\r
- * @return If the queue is successfully create then a handle to the newly\r
- * created queue is returned. If the queue cannot be created then 0 is\r
- * returned.\r
+ * @return If neither pucQueueStorageBuffer or pxQueueBuffer are NULL, then the\r
+ * function will not attempt any dynamic memory allocation, and a handle to the\r
+ * created queue will always be returned. If pucQueueStorageBuffer or\r
+ * pxQueueBuffer is NULL then the function will attempt to dynamically allocate\r
+ * one of both buffers. In this case, if the allocation succeeds then a handle\r
+ * to the created queue will be returned, and if one of the the allocation fails\r
+ * NULL will be returned.\r
*\r
* Example usage:\r
<pre>\r
#define ITEM_SIZE sizeof( uint32_t )\r
\r
// xQueueBuffer will hold the queue structure.\r
- StaticQueue_t xQueueBuffer; \r
+ StaticQueue_t xQueueBuffer;\r
\r
// ucQueueStorage will hold the items posted to the queue. Must be at least\r
// [(queue length) * ( queue item size)] bytes long.\r
// ... Rest of task code.\r
}\r
</pre>\r
- * \defgroup xQueueCreate xQueueCreate\r
+ * \defgroup xQueueCreateStatic xQueueCreateStatic\r
* \ingroup QueueManagement\r
*/\r
#if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
* returned.\r
*/\r
#if( configQUEUE_REGISTRY_SIZE > 0 )\r
- const char *pcQueueGetQueueName( QueueHandle_t xQueue );\r
+ const char *pcQueueGetQueueName( QueueHandle_t xQueue ); /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
#endif\r
\r
/*\r
* semphr. h\r
* <pre>SemaphoreHandle_t xSemaphoreCreateBinary( void )</pre>\r
*\r
+ * Creates a new binary semaphore instance, and returns a handle by which the\r
+ * new semaphore can be referenced.\r
+ *\r
* In many usage scenarios it is faster and more memory efficient to use a\r
* direct to task notification in place of a binary semaphore!\r
* http://www.freertos.org/RTOS-task-notifications.html\r
*\r
+ * Internally, within the FreeRTOS implementation, binary semaphores use a block\r
+ * of memory, in which the semaphore structure is stored. If a binary semaphore\r
+ * is created using xSemaphoreCreateBinary() then the required memory is\r
+ * automatically dynamically allocated inside the xSemaphoreCreateBinary()\r
+ * function. (see http://www.freertos.org/a00111.html). If a binary semaphore\r
+ * is created using xSemaphoreCreateBinaryStatic() then the application writer\r
+ * can instead optionally provide the memory that will get used by the binary\r
+ * semaphore. xSemaphoreCreateBinaryStatic() therefore allows a binary\r
+ * semaphore to be created without using any dynamic memory allocation.\r
+ *\r
* The old vSemaphoreCreateBinary() macro is now deprecated in favour of this\r
* xSemaphoreCreateBinary() function. Note that binary semaphores created using\r
* the vSemaphoreCreateBinary() macro are created in a state such that the\r
* created using xSemaphoreCreateBinary() are created in a state such that the\r
* the semaphore must first be 'given' before it can be 'taken'.\r
*\r
- * Function that creates a semaphore by using the existing queue mechanism.\r
- * The queue length is 1 as this is a binary semaphore. The data size is 0\r
- * as nothing is actually stored - all that is important is whether the queue is\r
- * empty or full (the binary semaphore is available or not).\r
- *\r
* This type of semaphore can be used for pure synchronisation between tasks or\r
* between an interrupt and a task. The semaphore need not be given back once\r
* obtained, so one task/interrupt can continuously 'give' the semaphore while\r
* semaphore does not use a priority inheritance mechanism. For an alternative\r
* that does use priority inheritance see xSemaphoreCreateMutex().\r
*\r
- * @return Handle to the created semaphore.\r
+ * @return Handle to the created semaphore, or NULL if the memory required to\r
+ * hold the semaphore's data structures could not be allocated.\r
*\r
* Example usage:\r
<pre>\r
\r
void vATask( void * pvParameters )\r
{\r
- // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().\r
+ // Semaphore cannot be used before a call to xSemaphoreCreateBinary().\r
// This is a macro so pass the variable in directly.\r
xSemaphore = xSemaphoreCreateBinary();\r
\r
}\r
}\r
</pre>\r
- * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary\r
+ * \defgroup xSemaphoreCreateBinary xSemaphoreCreateBinary\r
* \ingroup Semaphores\r
*/\r
#define xSemaphoreCreateBinary() xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, NULL, queueQUEUE_TYPE_BINARY_SEMAPHORE )\r
\r
+/**\r
+ * semphr. h\r
+ * <pre>SemaphoreHandle_t xSemaphoreCreateBinaryStatic( StaticSemaphore_t *pxSemaphoreBuffer )</pre>\r
+ *\r
+ * Creates a new binary semaphore instance, and returns a handle by which the\r
+ * new semaphore can be referenced.\r
+ *\r
+ * NOTE: In many usage scenarios it is faster and more memory efficient to use a\r
+ * direct to task notification in place of a binary semaphore!\r
+ * http://www.freertos.org/RTOS-task-notifications.html\r
+ *\r
+ * Internally, within the FreeRTOS implementation, binary semaphores use a block\r
+ * of memory, in which the semaphore structure is stored. If a binary semaphore\r
+ * is created using xSemaphoreCreateBinary() then the required memory is\r
+ * automatically dynamically allocated inside the xSemaphoreCreateBinary()\r
+ * function. (see http://www.freertos.org/a00111.html). If a binary semaphore\r
+ * is created using xSemaphoreCreateBinaryStatic() then the application writer\r
+ * can instead optionally provide the memory that will get used by the binary\r
+ * semaphore. xSemaphoreCreateBinaryStatic() therefore allows a binary\r
+ * semaphore to be created without using any dynamic memory allocation.\r
+ *\r
+ * This type of semaphore can be used for pure synchronisation between tasks or\r
+ * between an interrupt and a task. The semaphore need not be given back once\r
+ * obtained, so one task/interrupt can continuously 'give' the semaphore while\r
+ * another continuously 'takes' the semaphore. For this reason this type of\r
+ * semaphore does not use a priority inheritance mechanism. For an alternative\r
+ * that does use priority inheritance see xSemaphoreCreateMutex().\r
+ *\r
+ * @param pxSemaphoreBuffer If pxSemaphoreBuffer is NULL then the memory\r
+ * required to hold the semaphore's data structures will be allocated\r
+ * dynamically, just as when a semaphore is created using\r
+ * xSemaphoreCreateBinary(). If pxSemaphoreBuffer is not NULL then it must\r
+ * point to a variable of type StaticSemaphore_t, which will then be used to\r
+ * hold the semaphore's data structure, removing the need for the memory to be\r
+ * allocated dynamically.\r
+ *\r
+ * @return If pxSemaphoreBuffer is not NULL then the function will not attempt\r
+ * any dynamic memory allocation, and a handle to the created semaphore will\r
+ * always be returned. If pxSemaphoreBuffer is NULL then the function will\r
+ * attempt to dynamically allocate the memory required to hold the semaphore's\r
+ * data structures. In this case, if the allocation succeeds then a handle to\r
+ * the created semaphore will be returned, and if the allocation fails NULL will\r
+ * be returned.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ SemaphoreHandle_t xSemaphore = NULL;\r
+ StaticSemaphore_t xSemaphoreBuffer;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // Semaphore cannot be used before a call to xSemaphoreCreateBinary().\r
+ // The semaphore's data structures will be placed in the xSemaphoreBuffer\r
+ // variable, the address of which is passed into the function. The\r
+ // function's parameter is not NULL, so the function will not attempt any\r
+ // dynamic memory allocation, and therefore the function will not return\r
+ // return NULL.\r
+ xSemaphore = xSemaphoreCreateBinary( &xSemaphoreBuffer );\r
+\r
+ // Rest of task code goes here.\r
+ }\r
+ </pre>\r
+ * \defgroup xSemaphoreCreateBinaryStatic xSemaphoreCreateBinaryStatic\r
+ * \ingroup Semaphores\r
+ */\r
#if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
- #define xSemaphoreCreateBinaryStatic( pxStaticQueue ) xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, pxStaticQueue, queueQUEUE_TYPE_BINARY_SEMAPHORE )\r
+ #define xSemaphoreCreateBinaryStatic( pxStaticSemaphore ) xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, pxStaticSemaphore, queueQUEUE_TYPE_BINARY_SEMAPHORE )\r
#endif /* configSUPPORT_STATIC_ALLOCATION */\r
\r
/**\r
* )</pre>\r
*\r
* <i>Macro</i> to obtain a semaphore. The semaphore must have previously been\r
- * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
+ * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
* xSemaphoreCreateCounting().\r
*\r
* @param xSemaphore A handle to the semaphore being taken - obtained when\r
void vATask( void * pvParameters )\r
{\r
// Create the semaphore to guard a shared resource.\r
- vSemaphoreCreateBinary( xSemaphore );\r
+ xSemaphore = xSemaphoreCreateBinary();\r
}\r
\r
// A task that uses the semaphore.\r
* <pre>xSemaphoreGive( SemaphoreHandle_t xSemaphore )</pre>\r
*\r
* <i>Macro</i> to release a semaphore. The semaphore must have previously been\r
- * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
+ * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or\r
* xSemaphoreCreateCounting(). and obtained using sSemaphoreTake().\r
*\r
* This macro must not be used from an ISR. See xSemaphoreGiveFromISR () for\r
void vATask( void * pvParameters )\r
{\r
// Create the semaphore to guard a shared resource.\r
- vSemaphoreCreateBinary( xSemaphore );\r
+ xSemaphore = vSemaphoreCreateBinary();\r
\r
if( xSemaphore != NULL )\r
{\r
)</pre>\r
*\r
* <i>Macro</i> to release a semaphore. The semaphore must have previously been\r
- * created with a call to vSemaphoreCreateBinary() or xSemaphoreCreateCounting().\r
+ * created with a call to xSemaphoreCreateBinary() or xSemaphoreCreateCounting().\r
*\r
* Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
* must not be used with this macro.\r
)</pre>\r
*\r
* <i>Macro</i> to take a semaphore from an ISR. The semaphore must have\r
- * previously been created with a call to vSemaphoreCreateBinary() or\r
+ * previously been created with a call to xSemaphoreCreateBinary() or\r
* xSemaphoreCreateCounting().\r
*\r
* Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
* semphr. h\r
* <pre>SemaphoreHandle_t xSemaphoreCreateMutex( void )</pre>\r
*\r
- * <i>Macro</i> that implements a mutex semaphore by using the existing queue\r
- * mechanism.\r
+ * Creates a new mutex type semaphore instance, and returns a handle by which\r
+ * the new mutex can be referenced.\r
*\r
- * Mutexes created using this macro can be accessed using the xSemaphoreTake()\r
+ * Internally, within the FreeRTOS implementation, mutex semaphores use a block\r
+ * of memory, in which the mutex structure is stored. If a mutex is created\r
+ * using xSemaphoreCreateMutex() then the required memory is automatically\r
+ * dynamically allocated inside the xSemaphoreCreateMutex() function. (see\r
+ * http://www.freertos.org/a00111.html). If a mutex is created using\r
+ * xSemaphoreCreateMutexStatic() then the application writer can instead\r
+ * optionally provide the memory that will get used by the mutex.\r
+ * xSemaphoreCreateMutexStatic() therefore allows a mutex to be created without\r
+ * using any dynamic memory allocation.\r
+ *\r
+ * Mutexes created using this function can be accessed using the xSemaphoreTake()\r
* and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and\r
- * xSemaphoreGiveRecursive() macros should not be used.\r
+ * xSemaphoreGiveRecursive() macros must not be used.\r
*\r
* This type of semaphore uses a priority inheritance mechanism so a task\r
* 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the\r
*\r
* Mutex type semaphores cannot be used from within interrupt service routines.\r
*\r
- * See vSemaphoreCreateBinary() for an alternative implementation that can be\r
+ * See xSemaphoreCreateBinary() for an alternative implementation that can be\r
* used for pure synchronisation (where one task or interrupt always 'gives' the\r
* semaphore and another always 'takes' the semaphore) and from within interrupt\r
* service routines.\r
*\r
- * @return xSemaphore Handle to the created mutex semaphore. Should be of type\r
- * SemaphoreHandle_t.\r
+ * @return If the mutex was successfully created then a handle to the created\r
+ * semaphore is returned. If there was not enough heap to allocate the mutex\r
+ * data structures then NULL is returned.\r
*\r
* Example usage:\r
<pre>\r
}\r
}\r
</pre>\r
- * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex\r
+ * \defgroup xSemaphoreCreateMutex xSemaphoreCreateMutex\r
* \ingroup Semaphores\r
*/\r
#define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX, NULL )\r
\r
-#if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
- #define xSemaphoreCreateMutexStatic( pxStaticQueue ) xQueueCreateMutex( queueQUEUE_TYPE_MUTEX, ( pxStaticQueue ) )\r
+/**\r
+ * semphr. h\r
+ * <pre>SemaphoreHandle_t xSemaphoreCreateMutexStatic( StaticSemaphore_t *pxMutexBuffer )</pre>\r
+ *\r
+ * Creates a new mutex type semaphore instance, and returns a handle by which\r
+ * the new mutex can be referenced.\r
+ *\r
+ * Internally, within the FreeRTOS implementation, mutex semaphores use a block\r
+ * of memory, in which the mutex structure is stored. If a mutex is created\r
+ * using xSemaphoreCreateMutex() then the required memory is automatically\r
+ * dynamically allocated inside the xSemaphoreCreateMutex() function. (see\r
+ * http://www.freertos.org/a00111.html). If a mutex is created using\r
+ * xSemaphoreCreateMutexStatic() then the application writer can instead\r
+ * optionally provide the memory that will get used by the mutex.\r
+ * xSemaphoreCreateMutexStatic() therefore allows a mutex to be created without\r
+ * using any dynamic memory allocation.\r
+ *\r
+ * Mutexes created using this function can be accessed using the xSemaphoreTake()\r
+ * and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and\r
+ * xSemaphoreGiveRecursive() macros must not be used.\r
+ *\r
+ * This type of semaphore uses a priority inheritance mechanism so a task\r
+ * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the\r
+ * semaphore it is no longer required.\r
+ *\r
+ * Mutex type semaphores cannot be used from within interrupt service routines.\r
+ *\r
+ * See xSemaphoreCreateBinary() for an alternative implementation that can be\r
+ * used for pure synchronisation (where one task or interrupt always 'gives' the\r
+ * semaphore and another always 'takes' the semaphore) and from within interrupt\r
+ * service routines.\r
+ *\r
+ * @param pxMutexBuffer If pxMutexBuffer is NULL then the memory required to\r
+ * hold the mutex's data structures will be allocated dynamically, just as when\r
+ * a mutex is created using xSemaphoreCreateMutex(). If pxMutexBuffer is not\r
+ * NULL then it must point to a variable of type StaticSemaphore_t, which will\r
+ * then be used to hold the mutex's data structure, removing the need for\r
+ * the memory to be allocated dynamically.\r
+ *\r
+ * @return If the mutex was successfully created then a handle to the created\r
+ * mutex is returned. If pxMutexBuffer was NULL, and there was not enough\r
+ * heap to allocate the mutex data structures, then NULL is returned.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ SemaphoreHandle_t xSemaphore;\r
+ StaticSemaphore_t xMutexBuffer;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // A mutex cannot be used before it has been created. xMutexBuffer is\r
+ // into xSemaphoreCreateMutexStatic() so no dynamic memory allocation is\r
+ // attempted.\r
+ xSemaphore = xSemaphoreCreateMutexStatic( &xMutexBuffer );\r
+\r
+ // As no dynamic memory allocation was performed, xSemaphore cannot be NULL,\r
+ // so there is no need to check it.\r
+ }\r
+ </pre>\r
+ * \defgroup xSemaphoreCreateMutexStatic xSemaphoreCreateMutexStatic\r
+ * \ingroup Semaphores\r
+ */\r
+ #if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
+ #define xSemaphoreCreateMutexStatic( pxMutexBuffer ) xQueueCreateMutex( queueQUEUE_TYPE_MUTEX, ( pxMutexBuffer ) )\r
#endif /* configSUPPORT_STATIC_ALLOCATION */\r
\r
\r
* semphr. h\r
* <pre>SemaphoreHandle_t xSemaphoreCreateRecursiveMutex( void )</pre>\r
*\r
- * <i>Macro</i> that implements a recursive mutex by using the existing queue\r
- * mechanism.\r
+ * Creates a new recursive mutex type semaphore instance, and returns a handle\r
+ * by which the new recursive mutex can be referenced.\r
+ *\r
+ * Internally, within the FreeRTOS implementation, recursive mutexs use a block\r
+ * of memory, in which the mutex structure is stored. If a recursive mutex is\r
+ * created using xSemaphoreCreateRecursiveMutex() then the required memory is\r
+ * automatically dynamically allocated inside the\r
+ * xSemaphoreCreateRecursiveMutex() function. (see\r
+ * http://www.freertos.org/a00111.html). If a recursive mutex is created using\r
+ * xSemaphoreCreateRecursiveMutexStatic() then the application writer can\r
+ * instead optionally provide the memory that will get used by the mutex.\r
+ * xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to\r
+ * be created without using any dynamic memory allocation.\r
*\r
* Mutexes created using this macro can be accessed using the\r
* xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The\r
- * xSemaphoreTake() and xSemaphoreGive() macros should not be used.\r
+ * xSemaphoreTake() and xSemaphoreGive() macros must not be used.\r
*\r
* A mutex used recursively can be 'taken' repeatedly by the owner. The mutex\r
* doesn't become available again until the owner has called\r
*\r
* Mutex type semaphores cannot be used from within interrupt service routines.\r
*\r
- * See vSemaphoreCreateBinary() for an alternative implementation that can be\r
+ * See xSemaphoreCreateBinary() for an alternative implementation that can be\r
* used for pure synchronisation (where one task or interrupt always 'gives' the\r
* semaphore and another always 'takes' the semaphore) and from within interrupt\r
* service routines.\r
*\r
* @return xSemaphore Handle to the created mutex semaphore. Should be of type\r
- * SemaphoreHandle_t.\r
+ * SemaphoreHandle_t.\r
*\r
* Example usage:\r
<pre>\r
}\r
}\r
</pre>\r
- * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex\r
+ * \defgroup xSemaphoreCreateRecursiveMutex xSemaphoreCreateRecursiveMutex\r
* \ingroup Semaphores\r
*/\r
#define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX, NULL )\r
\r
+/**\r
+ * semphr. h\r
+ * <pre>SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic( StaticSemaphore_t *pxMutexBuffer )</pre>\r
+ *\r
+ * Creates a new recursive mutex type semaphore instance, and returns a handle\r
+ * by which the new recursive mutex can be referenced.\r
+ *\r
+ * Internally, within the FreeRTOS implementation, recursive mutexs use a block\r
+ * of memory, in which the mutex structure is stored. If a recursive mutex is\r
+ * created using xSemaphoreCreateRecursiveMutex() then the required memory is\r
+ * automatically dynamically allocated inside the\r
+ * xSemaphoreCreateRecursiveMutex() function. (see\r
+ * http://www.freertos.org/a00111.html). If a recursive mutex is created using\r
+ * xSemaphoreCreateRecursiveMutexStatic() then the application writer can\r
+ * instead optionally provide the memory that will get used by the mutex.\r
+ * xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to\r
+ * be created without using any dynamic memory allocation.\r
+ *\r
+ * Mutexes created using this macro can be accessed using the\r
+ * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The\r
+ * xSemaphoreTake() and xSemaphoreGive() macros must not be used.\r
+ *\r
+ * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex\r
+ * doesn't become available again until the owner has called\r
+ * xSemaphoreGiveRecursive() for each successful 'take' request. For example,\r
+ * if a task successfully 'takes' the same mutex 5 times then the mutex will\r
+ * not be available to any other task until it has also 'given' the mutex back\r
+ * exactly five times.\r
+ *\r
+ * This type of semaphore uses a priority inheritance mechanism so a task\r
+ * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the\r
+ * semaphore it is no longer required.\r
+ *\r
+ * Mutex type semaphores cannot be used from within interrupt service routines.\r
+ *\r
+ * See xSemaphoreCreateBinary() for an alternative implementation that can be\r
+ * used for pure synchronisation (where one task or interrupt always 'gives' the\r
+ * semaphore and another always 'takes' the semaphore) and from within interrupt\r
+ * service routines.\r
+ *\r
+ * @param pxMutexBuffer If pxMutexBuffer is NULL then the memory required to\r
+ * hold the recursive mutex's data structures will be allocated dynamically,\r
+ * just as when a recursive mutex is created using\r
+ * xSemaphoreCreateRecursiveMutex(). If pxMutexBuffer is not NULL then it must\r
+ * point to a variable of type StaticSemaphore_t, which will then be used to\r
+ * hold the recursive mutex's data structure, removing the need for the memory\r
+ * to be allocated dynamically.\r
+ *\r
+ * @return If the recursive mutex was successfully created then a handle to the\r
+ * created recursive mutex is returned. If pxMutexBuffer was NULL, and there\r
+ * was not enough heap to allocate the mutex data structures, then NULL is\r
+ * returned.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ SemaphoreHandle_t xSemaphore;\r
+ StaticSemaphore_t xMutexBuffer;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ // A recursive semaphore cannot be used before it is created. Here a\r
+ // recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic().\r
+ // The address of xMutexBuffer is passed into the function, and will hold\r
+ // the mutexes data structures - so no dynamic memory allocation will be\r
+ // attempted.\r
+ xSemaphore = xSemaphoreCreateRecursiveMutexStatic( &xMutexBuffer );\r
+\r
+ // As no dynamic memory allocation was performed, xSemaphore cannot be NULL,\r
+ // so there is no need to check it.\r
+ }\r
+ </pre>\r
+ * \defgroup xSemaphoreCreateRecursiveMutexStatic xSemaphoreCreateRecursiveMutexStatic\r
+ * \ingroup Semaphores\r
+ */\r
#if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
#define xSemaphoreCreateRecursiveMutexStatic( pxStaticSemaphore ) xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX, pxStaticSemaphore )\r
#endif /* configSUPPORT_STATIC_ALLOCATION */\r
* semphr. h\r
* <pre>SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount )</pre>\r
*\r
- * <i>Macro</i> that creates a counting semaphore by using the existing\r
- * queue mechanism.\r
+ * Creates a new counting semaphore instance, and returns a handle by which the\r
+ * new counting semaphore can be referenced.\r
+ *\r
+ * Internally, within the FreeRTOS implementation, counting semaphores use a\r
+ * block of memory, in which the counting semaphore structure is stored. If a\r
+ * counting semaphore is created using xSemaphoreCreateCounting() then the\r
+ * required memory is automatically dynamically allocated inside the\r
+ * xSemaphoreCreateCounting() function. (see\r
+ * http://www.freertos.org/a00111.html). If a counting semaphore is created\r
+ * using xSemaphoreCreateCountingStatic() then the application writer can\r
+ * instead optionally provide the memory that will get used by the counting\r
+ * semaphore. xSemaphoreCreateCountingStatic() therefore allows a counting\r
+ * semaphore to be created without using any dynamic memory allocation.\r
*\r
* Counting semaphores are typically used for two things:\r
*\r
*/\r
#define xSemaphoreCreateCounting( uxMaxCount, uxInitialCount ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ), ( NULL ) )\r
\r
+/**\r
+ * semphr. h\r
+ * <pre>SemaphoreHandle_t xSemaphoreCreateCountingStatic( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount, StaticSemaphore_t *pxSemaphoreBuffer )</pre>\r
+ *\r
+ * Creates a new counting semaphore instance, and returns a handle by which the\r
+ * new counting semaphore can be referenced.\r
+ *\r
+ * Internally, within the FreeRTOS implementation, counting semaphores use a\r
+ * block of memory, in which the counting semaphore structure is stored. If a\r
+ * counting semaphore is created using xSemaphoreCreateCounting() then the\r
+ * required memory is automatically dynamically allocated inside the\r
+ * xSemaphoreCreateCounting() function. (see\r
+ * http://www.freertos.org/a00111.html). If a counting semaphore is created\r
+ * using xSemaphoreCreateCountingStatic() then the application writer can\r
+ * instead optionally provide the memory that will get used by the counting\r
+ * semaphore. xSemaphoreCreateCountingStatic() therefore allows a counting\r
+ * semaphore to be created without using any dynamic memory allocation.\r
+ *\r
+ * Counting semaphores are typically used for two things:\r
+ *\r
+ * 1) Counting events.\r
+ *\r
+ * In this usage scenario an event handler will 'give' a semaphore each time\r
+ * an event occurs (incrementing the semaphore count value), and a handler\r
+ * task will 'take' a semaphore each time it processes an event\r
+ * (decrementing the semaphore count value). The count value is therefore\r
+ * the difference between the number of events that have occurred and the\r
+ * number that have been processed. In this case it is desirable for the\r
+ * initial count value to be zero.\r
+ *\r
+ * 2) Resource management.\r
+ *\r
+ * In this usage scenario the count value indicates the number of resources\r
+ * available. To obtain control of a resource a task must first obtain a\r
+ * semaphore - decrementing the semaphore count value. When the count value\r
+ * reaches zero there are no free resources. When a task finishes with the\r
+ * resource it 'gives' the semaphore back - incrementing the semaphore count\r
+ * value. In this case it is desirable for the initial count value to be\r
+ * equal to the maximum count value, indicating that all resources are free.\r
+ *\r
+ * @param uxMaxCount The maximum count value that can be reached. When the\r
+ * semaphore reaches this value it can no longer be 'given'.\r
+ *\r
+ * @param uxInitialCount The count value assigned to the semaphore when it is\r
+ * created.\r
+ *\r
+ * @param pxSemaphoreBuffer If pxSemaphoreBuffer is NULL then the memory\r
+ * required to hold the semaphore's data structures will be allocated\r
+ * dynamically, just as when a counting semaphore is created using\r
+ * xSemaphoreCreateCounting(). If pxSemaphoreBuffer is not NULL then it must\r
+ * point to a variable of type StaticSemaphore_t, which will then be used to\r
+ * hold the semaphore's data structure, removing the need for the memory\r
+ * to be allocated dynamically.\r
+ *\r
+ * @return If the counting semaphore was successfully created then a handle to\r
+ * the created counting semaphore is returned. If pxSemaphoreBuffer was NULL,\r
+ * and there was not enough heap to allocate the counting semaphore data\r
+ * structures, then NULL is returned.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ SemaphoreHandle_t xSemaphore;\r
+ StaticSemaphore_t xSemaphoreBuffer;\r
+\r
+ void vATask( void * pvParameters )\r
+ {\r
+ SemaphoreHandle_t xSemaphore = NULL;\r
+\r
+ // Counting semaphore cannot be used before they have been created. Create\r
+ // a counting semaphore using xSemaphoreCreateCountingStatic(). The max\r
+ // value to which the semaphore can count is 10, and the initial value\r
+ // assigned to the count will be 0. The address of xSemaphoreBuffer is\r
+ // passed in and will be used to hold the semaphore structure, so no dynamic\r
+ // memory allocation will be used.\r
+ xSemaphore = xSemaphoreCreateCounting( 10, 0, &xSemaphoreBuffer );\r
+\r
+ // No memory allocation was attempted so xSemaphore cannot be NULL, so there\r
+ // is no need to check its value.\r
+ }\r
+ </pre>\r
+ * \defgroup xSemaphoreCreateCountingStatic xSemaphoreCreateCountingStatic\r
+ * \ingroup Semaphores\r
+ */\r
#if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
- #define xSemaphoreCreateCountingStatic( uxMaxCount, uxInitialCount, pxStaticSemaphore ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ), ( pxStaticSemaphore ) )\r
+ #define xSemaphoreCreateCountingStatic( uxMaxCount, uxInitialCount, pxSemaphoreBuffer ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ), ( pxSemaphoreBuffer ) )\r
#endif /* configSUPPORT_STATIC_ALLOCATION */\r
\r
/**\r
eReady, /* The task being queried is in a read or pending ready list. */\r
eBlocked, /* The task being queried is in the Blocked state. */\r
eSuspended, /* The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out. */\r
- eDeleted /* The task being queried has been deleted, but its TCB has not yet been freed. */\r
+ eDeleted, /* The task being queried has been deleted, but its TCB has not yet been freed. */\r
+ eInvalid /* Used as an 'invalid state' value. */\r
} eTaskState;\r
\r
/* Actions that can be performed when vTaskNotify() is called. */\r
UBaseType_t uxCurrentPriority; /* The priority at which the task was running (may be inherited) when the structure was populated. */\r
UBaseType_t uxBasePriority; /* The priority to which the task will return if the task's current priority has been inherited to avoid unbounded priority inversion when obtaining a mutex. Only valid if configUSE_MUTEXES is defined as 1 in FreeRTOSConfig.h. */\r
uint32_t ulRunTimeCounter; /* The total run time allocated to the task so far, as defined by the run time stats clock. See http://www.freertos.org/rtos-run-time-stats.html. Only valid when configGENERATE_RUN_TIME_STATS is defined as 1 in FreeRTOSConfig.h. */\r
+ StackType_t *pxStackBase; /* Points to the lowest address of the task's stack area. */\r
uint16_t usStackHighWaterMark; /* The minimum amount of stack space that has remained for the task since the task was created. The closer this value is to zero the closer the task has come to overflowing its stack. */\r
} TaskStatus_t;\r
\r
* task's data structures, removing the need for the memory to be allocated\r
* dynamically.\r
*\r
- * @return pdPASS if the task was successfully created and added to a ready\r
- * list, otherwise an error code defined in the file projdefs.h\r
+ * @return If neither pxStackBuffer or pxTaskBuffer are NULL, then the function\r
+ * will not attempt any dynamic memory allocation, and pdPASS will always be\r
+ * returned. If pxStackBuffer or pxTaskBuffer is NULL then the function will\r
+ * attempt to dynamically allocate one of both buffers. In this case, if the\r
+ * allocation succeeds then pdPASS will be returned, and if the allocation fails\r
+ * then an error code defined in projdefs.h is returned.\r
*\r
* Example usage:\r
<pre>\r
*/\r
eTaskState eTaskGetState( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;\r
\r
+/**\r
+ * task. h\r
+ * <pre>void vTaskGetTaskInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState );</pre>\r
+ *\r
+ * configUSE_TRACE_FACILITY must be defined as 1 for this function to be\r
+ * available. See the configuration section for more information.\r
+ *\r
+ * Populates a TaskStatus_t structure with information about a task.\r
+ *\r
+ * @param xTask Handle of the task being queried. If xTask is NULL then\r
+ * information will be returned about the calling task.\r
+ *\r
+ * @param pxTaskStatus A pointer to the TaskStatus_t structure that will be\r
+ * filled with information about the task referenced by the handle passed using\r
+ * the xTask parameter.\r
+ *\r
+ * @xGetFreeStackSpace The TaskStatus_t structure contains a member to report\r
+ * the stack high water mark of the task being queried. Calculating the stack\r
+ * high water mark takes a relatively long time, and can make the system\r
+ * temporarily unresponsive - so the xGetFreeStackSpace parameter is provided to\r
+ * allow the high water mark checking to be skipped. The high watermark value\r
+ * will only be written to the TaskStatus_t structure if xGetFreeStackSpace is\r
+ * not set to pdFALSE;\r
+ *\r
+ * @param eState The TaskStatus_t structure contains a member to report the\r
+ * state of the task being queried. Obtaining the task state is not as fast as\r
+ * a simple assignment - so the eState parameter is provided to allow the state\r
+ * information to be omitted from the TaskStatus_t structure. To obtain state\r
+ * information then set eState to eInvalid - otherwise the value passed in\r
+ * eState will be reported as the task state in the TaskStatus_t structure.\r
+ *\r
+ * Example usage:\r
+ <pre>\r
+ void vAFunction( void )\r
+ {\r
+ TaskHandle_t xHandle;\r
+ TaskStatus_t xTaskDetails;\r
+\r
+ // Obtain the handle of a task from its name.\r
+ xHandle = xTaskGetTaskHandle( "Task_Name" );\r
+\r
+ // Check the handle is not NULL.\r
+ configASSERT( xHandle );\r
+\r
+ // Use the handle to obtain further information about the task.\r
+ vTaskGetTaskInfo( xHandle,\r
+ &xTaskDetails,\r
+ pdTRUE, // Include the high water mark in xTaskDetails.\r
+ eInvalid ); // Include the task state in xTaskDetails.\r
+ }\r
+ </pre>\r
+ * \defgroup vTaskGetTaskInfo vTaskGetTaskInfo\r
+ * \ingroup TaskCtrl\r
+ */\r
+void vTaskGetTaskInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState );\r
+\r
/**\r
* task. h\r
* <pre>void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority );</pre>\r
*/\r
char *pcTaskGetTaskName( TaskHandle_t xTaskToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
\r
+/**\r
+ * task. h\r
+ * <PRE>TaskHandle_t xTaskGetTaskHandle( const char *pcNameToQuery );</PRE>\r
+ *\r
+ * NOTE: This function takes a relatively long time to complete and should be\r
+ * used sparingly.\r
+ *\r
+ * @return The handle of the task that has the human readable name pcNameToQuery.\r
+ * NULL is returned if no matching name is found. INCLUDE_xTaskGetTaskHandle\r
+ * must be set to 1 in FreeRTOSConfig.h for pcTaskGetTaskHandle() to be available.\r
+ *\r
+ * \defgroup pcTaskGetTaskHandle pcTaskGetTaskHandle\r
+ * \ingroup TaskUtils\r
+ */\r
+TaskHandle_t xTaskGetTaskHandle( const char *pcNameToQuery ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
+\r
/**\r
* task.h\r
* <PRE>UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );</PRE>\r
* http://www.freertos.org/a00111.html). If a software timer is created using\r
* xTimerCreateStatic() then the application writer can instead optionally\r
* provide the memory that will get used by the software timer.\r
- * xTimerCreateStatic() therefore allows a software to be created without using\r
- * any dynamic memory allocation.\r
+ * xTimerCreateStatic() therefore allows a software timer to be created without\r
+ * using any dynamic memory allocation.\r
*\r
* Timers are created in the dormant state. The xTimerStart(), xTimerReset(),\r
* xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and\r
* will be then be used to hold the software timer's data structures, removing\r
* the need for the memory to be allocated dynamically.\r
*\r
- * @return If the timer is successfully created then a handle to the newly\r
- * created timer is returned. If the timer cannot be created (because either\r
- * there is insufficient FreeRTOS heap remaining to allocate the timer\r
- * structures, or the timer period was set to 0) then NULL is returned.\r
+ * @return If pxTimerBuffer is not NULL then the function will not attempt\r
+ * any dynamic memory allocation, and a handle to the created timer will always\r
+ * be returned. If pxTimerBuffer is NULL then the function will attempt to\r
+ * dynamically allocate the memory required to hold the timer's data structures.\r
+ * In this case, if the allocation succeeds then a handle to the created timer\r
+ * will be returned, and if the allocation fails NULL will be returned.\r
*\r
* Example usage:\r
* @verbatim\r
*/\r
BaseType_t xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION;\r
BaseType_t xTimerGenericCommand( TimerHandle_t xTimer, const BaseType_t xCommandID, const TickType_t xOptionalValue, BaseType_t * const pxHigherPriorityTaskWoken, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;\r
-TimerHandle_t xTimerGenericCreate( const char * const pcTimerName, const TickType_t xTimerPeriodInTicks, const UBaseType_t uxAutoReload, void * const pvTimerID, TimerCallbackFunction_t pxCallbackFunction, StaticTimer_t *pxTimerBuffer ) PRIVILEGED_FUNCTION;\r
+TimerHandle_t xTimerGenericCreate( const char * const pcTimerName, const TickType_t xTimerPeriodInTicks, const UBaseType_t uxAutoReload, void * const pvTimerID, TimerCallbackFunction_t pxCallbackFunction, StaticTimer_t *pxTimerBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
\r
#ifdef __cplusplus\r
}\r
*/\r
#if ( configUSE_TRACE_FACILITY == 1 )\r
\r
- static UBaseType_t prvListTaskWithinSingleList( TaskStatus_t *pxTaskStatusArray, List_t *pxList, eTaskState eState ) PRIVILEGED_FUNCTION;\r
+ static UBaseType_t prvListTasksWithinSingleList( TaskStatus_t *pxTaskStatusArray, List_t *pxList, eTaskState eState ) PRIVILEGED_FUNCTION;\r
+\r
+#endif\r
+\r
+/*\r
+ * Searches pxList for a task with name pcNameToQuery - returning a handle to\r
+ * the task if it is found, or NULL if the task is not found.\r
+ */\r
+#if ( INCLUDE_xTaskGetTaskHandle == 1 )\r
+\r
+ static TCB_t *prvSearchForNameWithinSingleList( List_t *pxList, const char pcNameToQuery[] );\r
\r
#endif\r
\r
#endif /* INCLUDE_vTaskDelay */\r
/*-----------------------------------------------------------*/\r
\r
-#if ( INCLUDE_eTaskGetState == 1 )\r
+#if( ( INCLUDE_eTaskGetState == 1 ) || ( configUSE_TRACE_FACILITY == 1 ) )\r
\r
eTaskState eTaskGetState( TaskHandle_t xTask )\r
{\r
}\r
taskEXIT_CRITICAL();\r
\r
+ if( xSchedulerRunning != pdFALSE )\r
+ {\r
+ /* Reset the next expected unblock time in case it referred to the\r
+ task that is now in the Suspended state. */\r
+ taskENTER_CRITICAL();\r
+ {\r
+ prvResetNextTaskUnblockTime();\r
+ }\r
+ taskEXIT_CRITICAL();\r
+ }\r
+ else\r
+ {\r
+ mtCOVERAGE_TEST_MARKER();\r
+ }\r
+\r
if( pxTCB == pxCurrentTCB )\r
{\r
if( xSchedulerRunning != pdFALSE )\r
}\r
else\r
{\r
- if( xSchedulerRunning != pdFALSE )\r
- {\r
- /* A task other than the currently running task was suspended,\r
- reset the next expected unblock time in case it referred to the\r
- task that is now in the Suspended state. */\r
- taskENTER_CRITICAL();\r
- {\r
- prvResetNextTaskUnblockTime();\r
- }\r
- taskEXIT_CRITICAL();\r
- }\r
- else\r
- {\r
- mtCOVERAGE_TEST_MARKER();\r
- }\r
+ mtCOVERAGE_TEST_MARKER();\r
}\r
}\r
\r
\r
BaseType_t xTaskResumeAll( void )\r
{\r
-TCB_t *pxTCB;\r
+TCB_t *pxTCB = NULL;\r
BaseType_t xAlreadyYielded = pdFALSE;\r
\r
/* If uxSchedulerSuspended is zero then this function does not match a\r
}\r
}\r
\r
+ if( pxTCB != NULL )\r
+ {\r
+ /* A task was unblocked while the scheduler was suspended,\r
+ which may have prevented the next unblock time from being\r
+ re-calculated, in which case re-calculate it now. Mainly\r
+ important for low power tickless implementations, where\r
+ this can prevent an unnecessary exit from low power\r
+ state. */\r
+ prvResetNextTaskUnblockTime();\r
+ }\r
+\r
/* If any ticks occurred while the scheduler was suspended then\r
they should be processed now. This ensures the tick count does\r
not slip, and that any delayed tasks are resumed at the correct\r
{\r
TCB_t *pxTCB;\r
\r
- /* If null is passed in here then the name of the calling task is being queried. */\r
+ /* If null is passed in here then the name of the calling task is being\r
+ queried. */\r
pxTCB = prvGetTCBFromHandle( xTaskToQuery );\r
configASSERT( pxTCB );\r
return &( pxTCB->pcTaskName[ 0 ] );\r
#endif /* INCLUDE_pcTaskGetTaskName */\r
/*-----------------------------------------------------------*/\r
\r
+#if ( INCLUDE_xTaskGetTaskHandle == 1 )\r
+\r
+ static TCB_t *prvSearchForNameWithinSingleList( List_t *pxList, const char pcNameToQuery[] )\r
+ {\r
+ TCB_t *pxNextTCB, *pxFirstTCB, *pxReturn = NULL;\r
+ UBaseType_t x;\r
+ char cNextChar;\r
+\r
+ /* This function is called with the scheduler suspended. */\r
+\r
+ if( listCURRENT_LIST_LENGTH( pxList ) > ( UBaseType_t ) 0 )\r
+ {\r
+ listGET_OWNER_OF_NEXT_ENTRY( pxFirstTCB, pxList );\r
+\r
+ do\r
+ {\r
+ listGET_OWNER_OF_NEXT_ENTRY( pxNextTCB, pxList );\r
+\r
+ /* Check each character in the name looking for a match or\r
+ mismatch. */\r
+ for( x = ( UBaseType_t ) 0; x < ( UBaseType_t ) configMAX_TASK_NAME_LEN; x++ )\r
+ {\r
+ cNextChar = pxNextTCB->pcTaskName[ x ];\r
+\r
+ if( cNextChar != pcNameToQuery[ x ] )\r
+ {\r
+ /* Characters didn't match. */\r
+ break;\r
+ }\r
+ else if( cNextChar == 0x00 )\r
+ {\r
+ /* Both strings terminated, a match must have been\r
+ found. */\r
+ pxReturn = pxNextTCB;\r
+ break;\r
+ }\r
+ else\r
+ {\r
+ mtCOVERAGE_TEST_MARKER();\r
+ }\r
+ }\r
+\r
+ if( pxReturn != NULL )\r
+ {\r
+ /* The handle has been found. */\r
+ break;\r
+ }\r
+\r
+ } while( pxNextTCB != pxFirstTCB );\r
+ }\r
+ else\r
+ {\r
+ mtCOVERAGE_TEST_MARKER();\r
+ }\r
+\r
+ return pxReturn;\r
+ }\r
+\r
+#endif /* INCLUDE_xTaskGetTaskHandle */\r
+/*-----------------------------------------------------------*/\r
+\r
+#if ( INCLUDE_xTaskGetTaskHandle == 1 )\r
+\r
+ TaskHandle_t xTaskGetTaskHandle( const char *pcNameToQuery ) /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
+ {\r
+ UBaseType_t uxQueue = configMAX_PRIORITIES;\r
+ TCB_t* pxTCB;\r
+\r
+ vTaskSuspendAll();\r
+ {\r
+ /* Search the ready lists. */\r
+ do\r
+ {\r
+ uxQueue--;\r
+ pxTCB = prvSearchForNameWithinSingleList( ( List_t * ) &( pxReadyTasksLists[ uxQueue ] ), pcNameToQuery );\r
+\r
+ if( pxTCB != NULL )\r
+ {\r
+ /* Found the handle. */\r
+ break;\r
+ }\r
+\r
+ } while( uxQueue > ( UBaseType_t ) tskIDLE_PRIORITY ); /*lint !e961 MISRA exception as the casts are only redundant for some ports. */\r
+\r
+ /* Search the delayed lists. */\r
+ if( pxTCB == NULL )\r
+ {\r
+ pxTCB = prvSearchForNameWithinSingleList( ( List_t * ) pxDelayedTaskList, pcNameToQuery );\r
+ }\r
+\r
+ if( pxTCB == NULL )\r
+ {\r
+ pxTCB = prvSearchForNameWithinSingleList( ( List_t * ) pxOverflowDelayedTaskList, pcNameToQuery );\r
+ }\r
+\r
+ #if ( INCLUDE_vTaskSuspend == 1 )\r
+ {\r
+ if( pxTCB == NULL )\r
+ {\r
+ /* Search the suspended list. */\r
+ pxTCB = prvSearchForNameWithinSingleList( &xSuspendedTaskList, pcNameToQuery );\r
+ }\r
+ }\r
+ #endif\r
+\r
+ #if( INCLUDE_vTaskDelete == 1 )\r
+ {\r
+ if( pxTCB == NULL )\r
+ {\r
+ /* Search the deleted list. */\r
+ pxTCB = prvSearchForNameWithinSingleList( &xTasksWaitingTermination, pcNameToQuery );\r
+ }\r
+ }\r
+ #endif\r
+ }\r
+ ( void ) xTaskResumeAll();\r
+\r
+ return ( TaskHandle_t ) pxTCB;\r
+ }\r
+\r
+#endif /* INCLUDE_xTaskGetTaskHandle */\r
+/*-----------------------------------------------------------*/\r
+\r
#if ( configUSE_TRACE_FACILITY == 1 )\r
\r
UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, const UBaseType_t uxArraySize, uint32_t * const pulTotalRunTime )\r
do\r
{\r
uxQueue--;\r
- uxTask += prvListTaskWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), &( pxReadyTasksLists[ uxQueue ] ), eReady );\r
+ uxTask += prvListTasksWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), &( pxReadyTasksLists[ uxQueue ] ), eReady );\r
\r
} while( uxQueue > ( UBaseType_t ) tskIDLE_PRIORITY ); /*lint !e961 MISRA exception as the casts are only redundant for some ports. */\r
\r
/* Fill in an TaskStatus_t structure with information on each\r
task in the Blocked state. */\r
- uxTask += prvListTaskWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), ( List_t * ) pxDelayedTaskList, eBlocked );\r
- uxTask += prvListTaskWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), ( List_t * ) pxOverflowDelayedTaskList, eBlocked );\r
+ uxTask += prvListTasksWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), ( List_t * ) pxDelayedTaskList, eBlocked );\r
+ uxTask += prvListTasksWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), ( List_t * ) pxOverflowDelayedTaskList, eBlocked );\r
\r
#if( INCLUDE_vTaskDelete == 1 )\r
{\r
/* Fill in an TaskStatus_t structure with information on\r
each task that has been deleted but not yet cleaned up. */\r
- uxTask += prvListTaskWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), &xTasksWaitingTermination, eDeleted );\r
+ uxTask += prvListTasksWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), &xTasksWaitingTermination, eDeleted );\r
}\r
#endif\r
\r
{\r
/* Fill in an TaskStatus_t structure with information on\r
each task in the Suspended state. */\r
- uxTask += prvListTaskWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), &xSuspendedTaskList, eSuspended );\r
+ uxTask += prvListTasksWithinSingleList( &( pxTaskStatusArray[ uxTask ] ), &xSuspendedTaskList, eSuspended );\r
}\r
#endif\r
\r
}\r
/*-----------------------------------------------------------*/\r
\r
+#if( configUSE_TRACE_FACILITY == 1 )\r
+\r
+ void vTaskGetTaskInfo( TaskHandle_t xTask, TaskStatus_t *pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState )\r
+ {\r
+ TCB_t *pxTCB;\r
+\r
+ /* xTask is NULL then get the state of the calling task. */\r
+ pxTCB = prvGetTCBFromHandle( xTask );\r
+\r
+ pxTaskStatus->xHandle = ( TaskHandle_t ) pxTCB;\r
+ pxTaskStatus->pcTaskName = ( const char * ) &( pxTCB->pcTaskName [ 0 ] );\r
+ pxTaskStatus->uxCurrentPriority = pxTCB->uxPriority;\r
+ pxTaskStatus->pxStackBase = pxTCB->pxStack;\r
+ pxTaskStatus->xTaskNumber = pxTCB->uxTCBNumber;\r
+\r
+ #if ( INCLUDE_vTaskSuspend == 1 )\r
+ {\r
+ /* If the task is in the suspended list then there is a chance it is\r
+ actually just blocked indefinitely - so really it should be reported as\r
+ being in the Blocked state. */\r
+ if( pxTaskStatus->eCurrentState == eSuspended )\r
+ {\r
+ vTaskSuspendAll();\r
+ {\r
+ if( listLIST_ITEM_CONTAINER( &( pxTCB->xEventListItem ) ) != NULL )\r
+ {\r
+ pxTaskStatus->eCurrentState = eBlocked;\r
+ }\r
+ }\r
+ xTaskResumeAll();\r
+ }\r
+ }\r
+ #endif /* INCLUDE_vTaskSuspend */\r
+\r
+ #if ( configUSE_MUTEXES == 1 )\r
+ {\r
+ pxTaskStatus->uxBasePriority = pxTCB->uxBasePriority;\r
+ }\r
+ #else\r
+ {\r
+ pxTaskStatus->uxBasePriority = 0;\r
+ }\r
+ #endif\r
+\r
+ #if ( configGENERATE_RUN_TIME_STATS == 1 )\r
+ {\r
+ pxTaskStatus->ulRunTimeCounter = pxTCB->ulRunTimeCounter;\r
+ }\r
+ #else\r
+ {\r
+ pxTaskStatus->ulRunTimeCounter = 0;\r
+ }\r
+ #endif\r
+\r
+ /* Obtaining the task state is a little fiddly, so is only done if the value\r
+ of eState passed into this function is eInvalid - otherwise the state is\r
+ just set to whatever is passed in. */\r
+ if( eState != eInvalid )\r
+ {\r
+ pxTaskStatus->eCurrentState = eState;\r
+ }\r
+ else\r
+ {\r
+ pxTaskStatus->eCurrentState = eTaskGetState( xTask );\r
+ }\r
+\r
+ /* Obtaining the stack space takes some time, so the xGetFreeStackSpace\r
+ parameter is provided to allow it to be skipped. */\r
+ if( xGetFreeStackSpace != pdFALSE )\r
+ {\r
+ #if ( portSTACK_GROWTH > 0 )\r
+ {\r
+ pxTaskStatus->usStackHighWaterMark = prvTaskCheckFreeStackSpace( ( uint8_t * ) pxTCB->pxEndOfStack );\r
+ }\r
+ #else\r
+ {\r
+ pxTaskStatus->usStackHighWaterMark = prvTaskCheckFreeStackSpace( ( uint8_t * ) pxTCB->pxStack );\r
+ }\r
+ #endif\r
+ }\r
+ else\r
+ {\r
+ pxTaskStatus->usStackHighWaterMark = 0;\r
+ }\r
+ }\r
+\r
+#endif /* INCLUDE_eTaskGetState */\r
+/*-----------------------------------------------------------*/\r
+\r
#if ( configUSE_TRACE_FACILITY == 1 )\r
\r
- static UBaseType_t prvListTaskWithinSingleList( TaskStatus_t *pxTaskStatusArray, List_t *pxList, eTaskState eState )\r
+ static UBaseType_t prvListTasksWithinSingleList( TaskStatus_t *pxTaskStatusArray, List_t *pxList, eTaskState eState )\r
{\r
volatile TCB_t *pxNextTCB, *pxFirstTCB;\r
UBaseType_t uxTask = 0;\r
do\r
{\r
listGET_OWNER_OF_NEXT_ENTRY( pxNextTCB, pxList );\r
-\r
- pxTaskStatusArray[ uxTask ].xHandle = ( TaskHandle_t ) pxNextTCB;\r
- pxTaskStatusArray[ uxTask ].pcTaskName = ( const char * ) &( pxNextTCB->pcTaskName [ 0 ] );\r
- pxTaskStatusArray[ uxTask ].xTaskNumber = pxNextTCB->uxTCBNumber;\r
- pxTaskStatusArray[ uxTask ].eCurrentState = eState;\r
- pxTaskStatusArray[ uxTask ].uxCurrentPriority = pxNextTCB->uxPriority;\r
-\r
- #if ( INCLUDE_vTaskSuspend == 1 )\r
- {\r
- /* If the task is in the suspended list then there is a chance\r
- it is actually just blocked indefinitely - so really it should\r
- be reported as being in the Blocked state. */\r
- if( eState == eSuspended )\r
- {\r
- if( listLIST_ITEM_CONTAINER( &( pxNextTCB->xEventListItem ) ) != NULL )\r
- {\r
- pxTaskStatusArray[ uxTask ].eCurrentState = eBlocked;\r
- }\r
- }\r
- }\r
- #endif /* INCLUDE_vTaskSuspend */\r
-\r
- #if ( configUSE_MUTEXES == 1 )\r
- {\r
- pxTaskStatusArray[ uxTask ].uxBasePriority = pxNextTCB->uxBasePriority;\r
- }\r
- #else\r
- {\r
- pxTaskStatusArray[ uxTask ].uxBasePriority = 0;\r
- }\r
- #endif\r
-\r
- #if ( configGENERATE_RUN_TIME_STATS == 1 )\r
- {\r
- pxTaskStatusArray[ uxTask ].ulRunTimeCounter = pxNextTCB->ulRunTimeCounter;\r
- }\r
- #else\r
- {\r
- pxTaskStatusArray[ uxTask ].ulRunTimeCounter = 0;\r
- }\r
- #endif\r
-\r
- #if ( portSTACK_GROWTH > 0 )\r
- {\r
- pxTaskStatusArray[ uxTask ].usStackHighWaterMark = prvTaskCheckFreeStackSpace( ( uint8_t * ) pxNextTCB->pxEndOfStack );\r
- }\r
- #else\r
- {\r
- pxTaskStatusArray[ uxTask ].usStackHighWaterMark = prvTaskCheckFreeStackSpace( ( uint8_t * ) pxNextTCB->pxStack );\r
- }\r
- #endif\r
-\r
+ vTaskGetTaskInfo( ( TaskHandle_t ) pxNextTCB, &( pxTaskStatusArray[ uxTask ] ), pdTRUE, eState );\r
uxTask++;\r
-\r
} while( pxNextTCB != pxFirstTCB );\r
}\r
else\r
{\r
/* Only free the stack and TCB if they were allocated dynamically in\r
the first place. */\r
- if( ( pxTCB->ucStaticAllocationFlags & taskSTATICALLY_ALLOCATED_STACK ) == ( UBaseType_t ) 0 )\r
+ if( ( pxTCB->ucStaticAllocationFlags & taskSTATICALLY_ALLOCATED_STACK ) == ( uint8_t ) 0 )\r
{\r
vPortFreeAligned( pxTCB->pxStack );\r
}\r
mtCOVERAGE_TEST_MARKER();\r
}\r
\r
- if( ( pxTCB->ucStaticAllocationFlags & taskSTATICALLY_ALLOCATED_TCB ) == ( UBaseType_t ) 0 )\r
+ if( ( pxTCB->ucStaticAllocationFlags & taskSTATICALLY_ALLOCATED_TCB ) == ( uint8_t ) 0 )\r
{\r
vPortFreeAligned( pxTCB );\r
}\r
}\r
#endif /* configSUPPORT_STATIC_ALLOCATION */\r
\r
-\r
#if ( INCLUDE_xTimerGetTimerDaemonTaskHandle == 1 )\r
{\r
/* Create the timer task, storing its handle in xTimerTaskHandle so\r
}\r
else\r
{\r
- pxNewTimer = ( Timer_t * ) pxTimerBuffer;\r
+ pxNewTimer = ( Timer_t * ) pxTimerBuffer; /*lint !e740 Unusual cast is ok as the structures are designed to have the same alignment, and the size is checked by an assert. */\r
}\r
\r
if( pxNewTimer != NULL )\r
#endif\r
/*-----------------------------------------------------------*/\r
\r
-const char * pcTimerGetTimerName( TimerHandle_t xTimer )\r
+const char * pcTimerGetTimerName( TimerHandle_t xTimer ) /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
{\r
Timer_t *pxTimer = ( Timer_t * ) xTimer;\r
\r
/* Just to avoid compiler warnings. */\r
( void ) pvParameters;\r
\r
+ #if( configUSE_DAEMON_TASK_STARTUP_HOOK == 1 )\r
+ {\r
+ extern void vApplicationDaemonTaskStartupHook( void );\r
+\r
+ /* Allow the application writer to execute some code in the context of\r
+ this task at the point the task starts executing. This is useful if the\r
+ application includes initialisation code that would benefit from\r
+ executing after the scheduler has been started. */\r
+ vApplicationDaemonTaskStartupHook();\r
+ }\r
+ #endif /* configUSE_DAEMON_TASK_STARTUP_HOOK */\r
+\r
for( ;; )\r
{\r
/* Query the timers list to see if it contains any timers, and if so,\r
allocated. */\r
#if( configSUPPORT_STATIC_ALLOCATION == 1 )\r
{\r
- if( pxTimer->ucStaticallyAllocated == pdFALSE )\r
+ if( pxTimer->ucStaticallyAllocated == ( uint8_t ) pdFALSE )\r
{\r
vPortFree( pxTimer );\r
}\r
projects / freertos / commitdiff