From a7b8bcb91cf7bdcb79fe1724320e1b3719cff03c Mon Sep 17 00:00:00 2001 From: rtel Date: Fri, 28 Jun 2019 23:20:52 +0000 Subject: [PATCH] Add the first and most basic task pool example. git-svn-id: https://svn.code.sf.net/p/freertos/code/trunk@2667 1d2547de-c912-0410-9cb9-b8ca96c0e9e2 --- .../TaskPool/.settings/language.settings.xml | 2 +- .../FreeRTOS_Plus_IoT_SDK/TaskPool/main.c | 110 ++++++++++++++++++ .../standard/common/include/iot_taskpool.h | 81 +++++++++++++ 3 files changed, 192 insertions(+), 1 deletion(-) diff --git a/FreeRTOS-Plus/Demo/FreeRTOS_Plus_IoT_SDK/TaskPool/.settings/language.settings.xml b/FreeRTOS-Plus/Demo/FreeRTOS_Plus_IoT_SDK/TaskPool/.settings/language.settings.xml index a11d160d6..782b97ca1 100644 --- a/FreeRTOS-Plus/Demo/FreeRTOS_Plus_IoT_SDK/TaskPool/.settings/language.settings.xml +++ b/FreeRTOS-Plus/Demo/FreeRTOS_Plus_IoT_SDK/TaskPool/.settings/language.settings.xml @@ -5,7 +5,7 @@ - + diff --git a/FreeRTOS-Plus/Demo/FreeRTOS_Plus_IoT_SDK/TaskPool/main.c b/FreeRTOS-Plus/Demo/FreeRTOS_Plus_IoT_SDK/TaskPool/main.c index bf6e538da..c3181f570 100644 --- a/FreeRTOS-Plus/Demo/FreeRTOS_Plus_IoT_SDK/TaskPool/main.c +++ b/FreeRTOS-Plus/Demo/FreeRTOS_Plus_IoT_SDK/TaskPool/main.c @@ -2,15 +2,125 @@ #include "FreeRTOS.h" #include "task.h" +/* IoT SDK includes. */ +#include "iot_taskpool.h" + +/* + * Prototypes for the functions that demonstrate the task pool API. + */ +static void prvExample_BasicSingleJob( void ); + +/* Prototypes of the callback functions used in the examples. */ +static void prvSimpleTaskNotifyCallback( IotTaskPool_t pTaskPool, IotTaskPoolJob_t pJob, void *pUserContext ); + +/* + * Prototypes for the standard FreeRTOS application hook (callback) functions + * implemented within this file. See http://www.freertos.org/a00016.html . + */ +void vApplicationMallocFailedHook( void ); +void vApplicationIdleHook( void ); +void vApplicationStackOverflowHook( TaskHandle_t pxTask, char *pcTaskName ); +void vApplicationTickHook( void ); void vApplicationGetIdleTaskMemory( StaticTask_t **ppxIdleTaskTCBBuffer, StackType_t **ppxIdleTaskStackBuffer, uint32_t *pulIdleTaskStackSize ); void vApplicationGetTimerTaskMemory( StaticTask_t **ppxTimerTaskTCBBuffer, StackType_t **ppxTimerTaskStackBuffer, uint32_t *pulTimerTaskStackSize ); +/* + * The task used to demonstrate the task pool API. + */ +static void prvTaskPoolDemoTask( void *pvParameters ); + +static const IotTaskPoolInfo_t xTaskPoolParameters = { + /* Minimum number of threads in a task pool. */ + 2, + /* Maximum number of threads in a task pool. */ + 2, + /* Stack size for every task pool thread - in words, not bytes. */ + configMINIMAL_STACK_SIZE, + /* Priority for every task pool thread. */ + tskIDLE_PRIORITY, + }; + +/*-----------------------------------------------------------*/ int main( void ) { + /* This example uses a single application task, which in turn is used to + create and send jobs to task pool tasks. */ + xTaskCreate( prvTaskPoolDemoTask, + "PoolDemo", + configMINIMAL_STACK_SIZE, + NULL, + tskIDLE_PRIORITY, + NULL ); + + vTaskStartScheduler(); + + /* Should not reach here as vTaskStartScheduler() will only return if there + was insufficient FreeRTOS heap memory to create the Idle or Timer + Daemon task. */ return 0; } +/*-----------------------------------------------------------*/ + +static void prvSimpleTaskNotifyCallback( IotTaskPool_t pTaskPool, IotTaskPoolJob_t pJob, void *pUserContext ) +{ +TaskHandle_t xTaskToNotify = ( TaskHandle_t ) pUserContext; + + /* Remove warnings about unused parameters. */ + ( void ) pTaskPool; + ( void ) pJob; + + /* Notify the task that created this job. */ + xTaskNotifyGive( xTaskToNotify ); +} +/*-----------------------------------------------------------*/ + +static void prvExample_BasicSingleJob( void ) +{ +IotTaskPoolJobStorage_t xJobStorage; +IotTaskPoolJob_t xJob; +IotTaskPoolError_t xResult; + + /* Ensure the notification count is 0 before scheduling the job. */ + while( ulTaskNotifyTake( pdTRUE, 0 ) != 0 ); + + /* Create and schedule a job using the handle of this task as the job's + context and the function that sends a notification to the task handle as + the jobs callback function. */ + xResult = IotTaskPool_CreateJob( prvSimpleTaskNotifyCallback, /* Callback function. */ + ( void * ) xTaskGetCurrentTaskHandle(), /* Job context. */ + &xJobStorage, + &xJob ); + configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); + IotTaskPool_ScheduleSystem( xJob, 0 ); + + /* Wait for the notification coming from the job's callback function. */ + ulTaskNotifyTake( pdTRUE, portMAX_DELAY ); +} +/*-----------------------------------------------------------*/ + +static void prvTaskPoolDemoTask( void *pvParameters ) +{ +IotTaskPoolError_t xResult; + /* Remove compiler warnings about unused parameters. */ + ( void ) pvParameters; + + /* The task pool must be created before it can be used. */ + xResult = IotTaskPool_CreateSystemTaskPool( &xTaskPoolParameters ); + configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); + + for( ;; ) + { + /* Run through each task pool example in turn. See the comments in the + below functions for details of their behaviour. */ + prvExample_BasicSingleJob(); + + + + vTaskDelete( NULL ); + } +} /*-----------------------------------------------------------*/ void vApplicationMallocFailedHook( void ) diff --git a/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/include/iot_taskpool.h b/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/include/iot_taskpool.h index 081e968dc..142c431ef 100644 --- a/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/include/iot_taskpool.h +++ b/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/include/iot_taskpool.h @@ -411,6 +411,87 @@ IotTaskPoolError_t IotTaskPool_RecycleJob( IotTaskPool_t taskPool, IotTaskPoolError_t IotTaskPool_Schedule( IotTaskPool_t taskPool, IotTaskPoolJob_t job, uint32_t flags ); + +/** + * @brief This function schedules a job created with @ref IotTaskPool_CreateJob or @ref IotTaskPool_CreateRecyclableJob + * against the system task pool. The system task pool is the task pool created by @ref IotTaskPool_CreateSystemTaskPool. + * + * See @ref taskpool_design for a description of the jobs lifetime and interaction with the threads used in the task pool + * library. + * + * @param[in] job A job to schedule for execution. This must be first initialized with a call to @ref IotTaskPool_CreateJob. + * @param[in] flags Flags to be passed by the user, e.g. to identify the job as high priority by specifying #IOT_TASKPOOL_JOB_HIGH_PRIORITY. + * + * @return One of the following: + * - #IOT_TASKPOOL_SUCCESS + * - #IOT_TASKPOOL_BAD_PARAMETER + * - #IOT_TASKPOOL_ILLEGAL_OPERATION + * - #IOT_TASKPOOL_NO_MEMORY + * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS + * + * + * @note This function will not allocate memory, so it is guaranteed to succeed if the parameters are correct and the task pool + * was correctly initialized, and not yet destroyed. + * + * Example + * @code{c} + * // An example of a user context to pass to a callback through a task pool thread. + * typedef struct JobUserContext + * { + * uint32_t counter; + * } JobUserContext_t; + * + * // An example of a user callback to invoke through a task pool thread. + * static void ExecutionCb( IotTaskPool_t taskPool, IotTaskPoolJob_t job, void * context ) + * { + * ( void )taskPool; + * ( void )job; + * + * JobUserContext_t * pUserContext = ( JobUserContext_t * )context; + * + * pUserContext->counter++; + * } + * + * void TaskPoolExample( ) + * { + * JobUserContext_t userContext = { 0 }; + * IotTaskPoolJob_t job; + * + * // Create the system task pool. This example assumes the task pool is created successfully. + * // It is recommended to test the function's return value in production code. + * IotTaskPool_CreateSystemTaskPool( &xTaskPoolParameters ); + * + * // Statically allocate one job, schedule it. + * IotTaskPool_CreateJob( &ExecutionCb, &userContext, &job ); + * + * IotTaskPoolError_t errorSchedule = IotTaskPool_ScheduleSystem( &job, 0 ); + * + * switch ( errorSchedule ) + * { + * case IOT_TASKPOOL_SUCCESS: + * break; + * case IOT_TASKPOOL_BAD_PARAMETER: // Invalid parameters, such as a NULL handle, can trigger this error. + * case IOT_TASKPOOL_ILLEGAL_OPERATION: // Scheduling a job that was previously scheduled or destroyed could trigger this error. + * case IOT_TASKPOOL_NO_MEMORY: // Scheduling a with flag #IOT_TASKPOOL_JOB_HIGH_PRIORITY could trigger this error. + * case IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS: // Scheduling a job after trying to destroy the task pool could trigger this error. + * // ASSERT + * break; + * default: + * // ASSERT + * } + * + * // + * // ... Perform other operations ... + * // + * + * IotTaskPool_Destroy( taskPool ); + * } + * @endcode + */ +/* @[declare_taskpool_schedule] */ +IotTaskPoolError_t IotTaskPool_ScheduleSystem( IotTaskPoolJob_t pJob, + uint32_t flags ); + /* @[declare_taskpool_schedule] */ /** -- 2.39.5