xTimerCreate
[定时器 API]

 TimerHandle_t xTimerCreate
                 ( const char * const pcTimerName,
                   const TickType_t xTimerPeriod,
                   const UBaseType_t uxAutoReload,
                   void * const pvTimerID,
                   TimerCallbackFunction_t pxCallbackFunction );

创建一个新的软件定时器实例， 并返回一个可以引用定时器的句柄。

要使此 RTOS API 函数可用：

1. configUSE_TIMERS 和 configSUPPORT_DYNAMIC_ALLOCATION 必须在 FreeRTOSConfig.h 中同时设置为 1（configSUPPORT_DYNAMIC_ALLOCATION 也可以不定义，此时其默认值为 1）。
2. FreeRTOS/Source/timers.c C 源文件必须包含在 构建中。

每个软件定时器都需要少量 RAM 来保存定时器的状态。 如果使用 xTimerCreate() 创建定时器， 则此 RAM 由 FreeRTOS 堆自动分配。 如果使用 xTimerCreateStatic() 创建软件定时器， 则 RAM 由应用程序编写器提供，这需要用到一个附加参数， 但允许在编译时静态分配 RAM 。 请参阅静态分配与 动态分配页面了解更多信息。

定时器是在休眠状态下创建的。 xTimerStart()、 xTimerReset()、 xTimerStartFromISR()、 xTimerResetFromISR()、 xTimerChangePeriod() 以及 xTimerChangePeriodFromISR() API 函数都可以用于将定时器转换为活动状态。

参数：

pcTimerName	分配给定时器的可读文本名称。 这样做纯粹是为了协助 调试。 RTOS 内核本身只通过句柄引用定时器， 而从不通过名字引用。
xTimerPeriod	定时器的周期。 以 tick 为单位指定此周期，宏 pdMS_TO_TICKS() 可用于将以毫秒为单位指定的时间转换为以 tick 为单位指定的时间。 例如， 如果定时器必须要在 100 次 tick 后到期，那么只需将 xTimerPeriod 设置为 100。 或者，如果定时器 必须在 500 毫秒后到期，则需要将 xTimerPeriod 设置为 pdMS_TO_TICKS( 500 )。 使用 pdMS_TO_TICKS() 的唯一前提条件是 configTICK_RATE_HZ 小于或等于 1000。 定时器周期必须大于 0。
uxAutoReload	如果 uxAutoReload 设置为 pdTRUE ，则定时器将按 xTimerPeriod 参数设置的频率重复到期。 如果 uxAutoReload 设置为 pdFALSE，则此定时器为一次性定时器， 它会在到期后进入休眠状态。
pvTimerID	分配给正在创建的定时器的标识符。 通常，此标识符用于定时器回调函数： 当同一个回调函数分配给了多个定时器时，此标识符可以识别哪个定时器已到期。 或者此标识符可与 vTimerSetTimerID() 和 pvTimerGetTimerID() API 函数一起使用， 以便保存调用 定时器回调函数之间的值。
pxCallbackFunction	定时器到期时调用的函数。 回调函数必须有 TimerCallbackFunction_t 定义的原型，即： void vCallbackFunction( TimerHandle_t xTimer ); 设置。

返回：

如果定时器创建成功， 则返回新创建的定时器的句柄。 如果由于剩余的 FreeRTOS 堆不足以分配定时器结构体而无法创建定时器， 则返回 NULL。

用法示例：

 #define NUM_TIMERS 5

 /* An array to hold handles to the created timers. */
 TimerHandle_t xTimers[ NUM_TIMERS ];

 /* Define a callback function that will be used by multiple timer
 instances.  The callback function does nothing but count the number
 of times the associated timer expires, and stop the timer once the
 timer has expired 10 times.  The count is saved as the ID of the
 timer. */
 void vTimerCallback( TimerHandle_t xTimer )
 {
 const uint32_t ulMaxExpiryCountBeforeStopping = 10;
 uint32_t ulCount;

    /* Optionally do something if the pxTimer parameter is NULL. */
    configASSERT( xTimer );

    /* The number of times this timer has expired is saved as the
    timer's ID.  Obtain the count. */
    ulCount = ( uint32_t ) pvTimerGetTimerID( xTimer );

    /* Increment the count, then test to see if the timer has expired
    ulMaxExpiryCountBeforeStopping yet. */
    ulCount++;

    /* If the timer has expired 10 times then stop it from running. */
    if( ulCount >= ulMaxExpiryCountBeforeStopping )
    {
        /* Do not use a block time if calling a timer API function
        from a timer callback function, as doing so could cause a
        deadlock! */
        xTimerStop( xTimer, 0 );
    }
    else
    {
       /* Store the incremented count back into the timer's ID field
       so it can be read back again the next time this software timer
       expires. */
       vTimerSetTimerID( xTimer, ( void * ) ulCount );
    }
 }

 void main( void )
 {
 long x;

     /* Create then start some timers.  Starting the timers before
     the RTOS scheduler has been started means the timers will start
     running immediately that the RTOS scheduler starts. */
     for( x = 0; x < NUM_TIMERS; x++ )
     {
         xTimers[ x ] = xTimerCreate
                   ( /* Just a text name, not used by the RTOS
                     kernel. */
                     "Timer",
                     /* The timer period in ticks, must be
                     greater than 0. */
                     ( 100 * x ) + 100,
                     /* The timers will auto-reload themselves
                     when they expire. */
                     pdTRUE,
                     /* The ID is used to store a count of the
                     number of times the timer has expired, which
                     is initialised to 0. */
                     ( void * ) 0,
                     /* Each timer calls the same callback when
                     it expires. */
                     vTimerCallback
                   );

         if( xTimers[ x ] == NULL )
         {
             /* The timer was not created. */
         }
         else
         {
             /* Start the timer.  No block time is specified, and
             even if one was it would be ignored because the RTOS
             scheduler has not yet been started. */
             if( xTimerStart( xTimers[ x ], 0 ) != pdPASS )
             {
                 /* The timer could not be set into the Active
                 state. */
             }
         }
     }

     /* ...
     Create tasks here.
     ... */

     /* Starting the RTOS scheduler will start the timers running
     as they have already been set into the active state. */
     vTaskStartScheduler();

     /* Should not reach here. */
     for( ;; );
 }