Ensure the code builds when configSUPPORT_STATIC_ALLOCATION is 0.

Continue to document the new static allocation functions.

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

1 files changed, 142 insertions, 5 deletions

diff --git a/FreeRTOS/Source/include/timers.h b/FreeRTOS/Source/include/timers.h
index c4582d134..e5e5c137c 100644
--- a/FreeRTOS/Source/include/timers.h
+++ b/FreeRTOS/Source/include/timers.h
@@ -135,9 +135,18 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
  * 								void * pvTimerID,

  * 								TimerCallbackFunction_t pxCallbackFunction );

  *

- * Creates a new software timer instance.  This allocates the storage required

- * by the new timer, initialises the new timers internal state, and returns a

- * handle by which the new timer can be referenced.

+ * Creates a new software timer instance, and returns a handle by which the

+ * created software timer can be referenced.

+ *

+ * Internally, within the FreeRTOS implementation, software timer's use a block

+ * of memory, in which the timer data structure is stored.  If a software timer

+ * is created using xTimerCreate() then the required memory is automatically

+ * dynamically allocated inside the xTimerCreate() function.  (see

+ * http://www.freertos.org/a00111.html).  If a software timer is created using

+ * xTimerCreateStatic() then the application writer can instead optionally

+ * provide the memory that will get used by the software timer.

+ * xTimerCreateStatic() therefore allows a software to be created without using

+ * any dynamic memory allocation.

  *

  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),

  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and

@@ -259,8 +268,136 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
  */

 #define xTimerCreate( pcTimerName, xTimerPeriodInTicks, uxAutoReload, pvTimerID, pxCallbackFunction ) xTimerGenericCreate( ( pcTimerName ), ( xTimerPeriodInTicks ), ( uxAutoReload ), ( pvTimerID ), ( pxCallbackFunction ), NULL )

 

+/**

+ * TimerHandle_t xTimerCreateStatic(const char * const pcTimerName,

+ * 									TickType_t xTimerPeriodInTicks,

+ * 									UBaseType_t uxAutoReload,

+ * 									void * pvTimerID,

+ * 									TimerCallbackFunction_t pxCallbackFunction,

+ *									StaticTimer_t *pxTimerBuffer );

+ *

+ * Creates a new software timer instance, and returns a handle by which the

+ * created software timer can be referenced.

+ *

+ * Internally, within the FreeRTOS implementation, software timer's use a block

+ * of memory, in which the timer data structure is stored.  If a software timer

+ * is created using xTimerCreate() then the required memory is automatically

+ * dynamically allocated inside the xTimerCreate() function.  (see

+ * http://www.freertos.org/a00111.html).  If a software timer is created using

+ * xTimerCreateStatic() then the application writer can instead optionally

+ * provide the memory that will get used by the software timer.

+ * xTimerCreateStatic() therefore allows a software to be created without using

+ * any dynamic memory allocation.

+ *

+ * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),

+ * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and

+ * xTimerChangePeriodFromISR() API functions can all be used to transition a

+ * timer into the active state.

+ *

+ * @param pcTimerName A text name that is assigned to the timer.  This is done

+ * purely to assist debugging.  The kernel itself only ever references a timer

+ * by its handle, and never by its name.

+ *

+ * @param xTimerPeriodInTicks The timer period.  The time is defined in tick

+ * periods so the constant portTICK_PERIOD_MS can be used to convert a time that

+ * has been specified in milliseconds.  For example, if the timer must expire

+ * after 100 ticks, then xTimerPeriodInTicks should be set to 100.

+ * Alternatively, if the timer must expire after 500ms, then xPeriod can be set

+ * to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or

+ * equal to 1000.

+ *

+ * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will

+ * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter.

+ * If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and

+ * enter the dormant state after it expires.

+ *

+ * @param pvTimerID An identifier that is assigned to the timer being created.

+ * Typically this would be used in the timer callback function to identify which

+ * timer expired when the same callback function is assigned to more than one

+ * timer.

+ *

+ * @param pxCallbackFunction The function to call when the timer expires.

+ * Callback functions must have the prototype defined by TimerCallbackFunction_t,

+ * which is "void vCallbackFunction( TimerHandle_t xTimer );".

+ *

+ * @param pxTimerBuffer If pxTimerBuffer is NULL then the memory required to

+ * hold the software timer's data structure will be allocated dynamically, just

+ * as when a software timer is created using xTimerCreate().  If pxTimerBuffer

+ * is not NULL then it must point to a variable of type StaticTimer_t, which

+ * will be then be used to hold the software timer's data structures, removing

+ * the need for the memory to be allocated dynamically.

+ *

+ * @return If the timer is successfully created then a handle to the newly

+ * created timer is returned.  If the timer cannot be created (because either

+ * there is insufficient FreeRTOS heap remaining to allocate the timer

+ * structures, or the timer period was set to 0) then NULL is returned.

+ *

+ * Example usage:

+ * @verbatim

+ *

+ * // The buffer used to hold the software timer's data structure.

+ * static StaticTimer_t xTimerBuffer;

+ *

+ * // A variable that will be incremented by the software timer's callback

+ * // function.

+ * UBaseType_t uxVariableToIncrement = 0;

+ *

+ * // A software timer callback function that increments a variable passed to

+ * // it when the software timer was created.  After the 5th increment the

+ * // callback function stops the software timer.

+ * static void prvTimerCallback( TimerHandle_t xExpiredTimer )

+ * {

+ * UBaseType_t *puxVariableToIncrement;

+ * BaseType_t xReturned;

+ *

+ *     // Obtain the address of the variable to increment from the timer ID.

+ *     puxVariableToIncrement = ( UBaseType_t * ) pvTimerGetTimerID( xExpiredTimer );

+ *

+ *     // Increment the variable to show the timer callback has executed.

+ *     ( *puxVariableToIncrement )++;

+ *

+ *     // If this callback has executed the required number of times, stop the

+ *     // timer.

+ *     if( *puxVariableToIncrement == 5 )

+ *     {

+ *         // This is called from a timer callback so must not block.

+ *         xTimerStop( xExpiredTimer, staticDONT_BLOCK );

+ *     }

+ * }

+ *

+ *

+ * void main( void )

+ * {

+ *     // Create the software time.  xTimerCreateStatic() has an extra parameter

+ *     // than the normal xTimerCreate() API function.  The parameter is a pointer

+ *     // to the StaticTimer_t structure that will hold the software timer

+ *     // structure.  If the parameter is passed as NULL then the structure will be

+ *     // allocated dynamically, just as if xTimerCreate() had been called.

+ *     xTimer = xTimerCreateStatic( "T1",             // Text name for the task.  Helps debugging only.  Not used by FreeRTOS.

+ *                                  xTimerPeriod,     // The period of the timer in ticks.

+ *                                  pdTRUE,           // This is an auto-reload timer.

+ *                                  ( void * ) &uxVariableToIncrement,    // A variable incremented by the software timer's callback function

+ *                                  prvTimerCallback, // The function to execute when the timer expires.

+ *                                  &xTimerBuffer );  // The buffer that will hold the software timer structure.

+ *

+ *     // The scheduler has not started yet so a block time is not used.

+ *     xReturned = xTimerStart( xTimer, 0 );

+ *

+ *     // ...

+ *     // Create tasks here.

+ *     // ...

+ *

+ *     // Starting the scheduler will start the timers running as they have already

+ *     // been set into the active state.

+ *     xTaskStartScheduler();

+ *

+ *     // Should not reach here.

+ *     for( ;; );

+ * }

+ * @endverbatim

+ */

 #if( configSUPPORT_STATIC_ALLOCATION == 1 )

-	#define xTimerCreateStatic( pcTimerName, xTimerPeriodInTicks, uxAutoReload, pvTimerID, pxCallbackFunction, pxStaticTimer ) xTimerGenericCreate( ( pcTimerName ), ( xTimerPeriodInTicks ), ( uxAutoReload ), ( pvTimerID ), ( pxCallbackFunction ), pxStaticTimer )

+	#define xTimerCreateStatic( pcTimerName, xTimerPeriodInTicks, uxAutoReload, pvTimerID, pxCallbackFunction, pxTimerBuffer ) xTimerGenericCreate( ( pcTimerName ), ( xTimerPeriodInTicks ), ( uxAutoReload ), ( pvTimerID ), ( pxCallbackFunction ), ( pxTimerBuffer ) )

 #endif /* configSUPPORT_STATIC_ALLOCATION */

 

 /**

@@ -1140,7 +1277,7 @@ const char * pcTimerGetTimerName( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; /*
  */

 BaseType_t xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION;

 BaseType_t xTimerGenericCommand( TimerHandle_t xTimer, const BaseType_t xCommandID, const TickType_t xOptionalValue, BaseType_t * const pxHigherPriorityTaskWoken, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;

-TimerHandle_t xTimerGenericCreate( const char * const pcTimerName, const TickType_t xTimerPeriodInTicks, const UBaseType_t uxAutoReload, void * const pvTimerID, TimerCallbackFunction_t pxCallbackFunction, StaticTimer_t *pxStaticTimer ) PRIVILEGED_FUNCTION;

+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;

 

 #ifdef __cplusplus

 }