Freertos API 函数 中文详解 pdf

【实例简介】
freertos API 系统函数 中文详解 pdf
//任务代码 //此函数创建一个任务 void vOtherFunction( void static unsigned char ucParameter ToPass X TaskHandle x handle 半 创建任务,存储句柄,注意传递的参数 ucParameterToPass必须在任务生存周期内存在, 故在此例子的情况下定义为局部静态变量。如果它只是一个自动堆栈变量(局部变量),它 可能不再存在或者至少崩溃了,当新的任务试图访问时。 笔者注释:由丁该任务一建立就在同个函数中被朋除了,大可以用些局部静态变量和局部 变量,如果不是在一个函数中删除之前创建的任务,以上参数请用全局变量 冰/ to xTaskCreate( vTaskCode,"NAME", STACK SIZE, &ucParameterToPass kIdle prioritY, &hAndle 使用句柄删除任务。 vTaskDelete( hAndle 2、 XTaskCreate 函数名: xTaskCreate 头文件:task.h 函数功能:任务删除 所数声明: void vTaskDelete( xTaskHandle pxTask) 具体应用:见 XTaskCreate中列举的范例。 任务管理API函数 1、 vTaskDe lay 函数名: vTaskDelay 头文件:task.h 函数功能:任务相对延时 函数声明: void vTaskDelay( portTickType xTicksToDelay); INCLUDE V Taskdelay必须定义为1以使能此函数。见 configuration章节获得更多信 延迟一个任务给定数量的时间封(心跳间隔时间)。实际任务阻寒的时间长度在于时间 封频率。常量 portTICK rAtE Ms可以用来计算时间封的实际时间间隔。 vTaskDelay指定了任务从调用 v TaskDelay起算,解除阻塞的相对吋间。举例,指定 阻塞时间为100个时间封,会导致任务在调用 VTaskDelay后阻塞100个时间封。 vTaskDelay并不提供一个好方汯控制周期仁务的频率,其它仁务和屮断的活动,会影响 TaskDelay的调用频率。见 vTaskDelay Until(,这是另外一种API函数,设计来便利固 定频率的执行。它靠指定绝对时间(而非相对时间)来实现功能,而此时调用的任务进入阻 塞 具体参数 xTicksToDelay:时间封的数量。 范例 void vTaskFunction( void ak pvParameters /米 Block for500ms.* const port TickType DElay =500/ portTICK RATE MS /*k Simply toggle the LED every 500ms, blocking between each toggle.*k, Toggled o vTaskDelay( x Delay 2、 TaskDe lay Until 函数名: vTaskDelavUntil 头文件:task.h 函数功能:任务绝对延时 函数声明: void vTaskDelayUntil( portTickType* pxPrevious WakeTime, portTickType tIme Increment INCLUDE V TaskDelaylntil必须定义为1以使能此函数。见 configuration章节获得更 多信息。 延迟仼务直到一个指定的时间结束。该数用在周期性任务以保证仼务执行频率的稳定。 与上 vTaskDelay不同的是该任务指定绝对时间, v TaskDelay指定相对时间。 (笔者注释:原文接下来两小段反复解释为什么一个是相对时间一个是绝对时间,翻译 省略,后续笔者会描述。) 必须注意, v TaskDelayUnti1会立即返回(没有阻塞)如果它用米指定一个已经过去 的唤醒时间。所以任务用 vTaskDelayUntil(来执行周期必须重新计算它需要的唤醒时间 如果该周期执行由于任何导致任务云失1个或者多个周期的理由被打断(比如该任务被挂 起)这可以由检查 pxPrevious Wake传递的变量与当前的时间封计数器来做比较检测到。在 大多数情况这不是必须的的。 常量 portTICK RATE MS可以用来计算时间封的实际时间间隔。 当调度器由于应用调用 vTaskSuspendAll(导致挂起(调度器暂停),不能调用此函数。 具休参数 pxPreviousWaketime:上一次唤醒的时间计数器。 xTimeIncrement:间隔周期计数器。 (笔者注释:如果有写过以定时器方式询按键,去抖动等程序,或者看过PIC591键程 序的用户,对这两个参数的作用应当很容易从直观上理解。对于所有的RT0S,都有一个时 间封(心跳时间),需要靠经过设置后能提供周期性中断功能的定时器来实现,而当RTOs 发动时,将有一个计数器来计数这是第儿次定时中断,这个计数器一般只会自然溢出,即达 到最大值后归0。读这个计数器的值,就等于了解了从FR0S开始运行,到当下,经历了多 少时间间隔(不考虐归0),而所谓的绝对延时,就是只关心上一次的计数器时间 pxPrevious WakeTime,以及经历多长时间 tIme increment后完成定时。至于计数器溢出, 不会影响什么,只要这两个参数与系统的计数器的数据类型一致,又都采用自然溢出方式计 算就可以。) 范例 Example usage // Perform an action every 10 ticks void vTaskFunction( void paRameters portTickType xLastWakeTime const port tickType fRequency=10 / Initialise the lAst WakeTime variable with the current time xLast WakeTime= xTaskGet Count O or // Wait for the next cycle vTaskDelayUntil( &xLastWakeTime, fRequency // Perform action here 3 uxTaskPriorityGet 函数名: ux TaskPriorityGet 头文件:task.h 函数功能:获取某个任务的优先级。 函数声明: unsigned porLBASE TYPE uxTaskPrioriLyGe( x TaskHandle px Task); 其余翻译,略,原因,比较简单 4、 VTaskPrioritySet 函数名: TaskPriorilySet 头文件:task.h 函数功能:设置某个任务的优先级。 i*Fi D: void vTaskPrioritySet( xTaskHandle px Task, unsi gned portBASE TYPE uxNewPriority 其余翻译,略,原因,比较简单 5、 vTaskSuspend 函数名: vTaskSuspend 头文件:task.h 函数功能:挂起某个任务 函数声明: void vTaskSuspend( xTaskHandle pxtaskToSuspend) 其余翻译,略,原因,比较简单 、 vlaskresume 函数名: vTaskResume 头文件:task.h 函数功能:恢复挂起的某个任务 函数声明: void vtaskResume( x TaskHandle pxtaskToresume); 其余翻译,略,原因,比较简单 7、 TaskResumefrolsr 函数名: vTaskResumefromISR 头文件:task.h 函数功能:从中断处理函数中,恢复挂起的某个任务 函数声明: port BASe TYPe XTaskResume FromISR( xTaskHandle pxtasktoResume) 其氽翻译,略,原因,比较简单。 三、任务公用程序 笔者注释,暂不翻译。 四、内核控制 1、 LaskY Ield 头文件:task.h 功能:强制进行现场切换的宏。 2、 taskENTER CRITICAL 头文件:task.h 功能 进入代码的临界段的宏。在临界段,抢先的现场切换无法发生 注意,这可能改变堆栈(依赖于移植是如何实现的),故必须小心使用。 3、 taSkEXIT CRITICAL 头文件:task.h 功能:退出代码的临界段的宏。在临界段,抢先的现场切换无法发生 注意,这可能改变堆栈(依赖于移植是如何实现的),故必须小心使用。 4 taskDISABLE INTERRLPTS 头文件:task 功能 关处理器的总中断 5 laskENABLE INTERRUPTS 头文件:task 功能 开处理器的总中断 6 vTaskStartScheduler 函数名: vTaskStartScheduler 头文件:task.h 函数声明: void ytaskstartscheduler(void) 函数功能:启动实时内核时间封处理。调用后,内核控制何时何地哪个任务运行。 当此函数被调用时,空闲任务自动创建 此函数成功时,永远不会返冋,直到 ytaskendScheduler(被调用。如果没有足够的 RAM创建空闲涵数,则该函数可能失败并立即返回。 范例 See the demo application file main. c for an example of creating tasks and tarting the kernel Example usage void aFUnction( void // Create at least one task before starting the kernel xTaskCreate( vTask Code,"NAME" STACK SIZE, NULL, tskTDlE PRTORTTY, NULL. // Start the real time kernel with preemption vTaskStart Scheduler / Will not get here unless a task calls vTaskEndScheduler O 7、ⅴ TaskEndscheduler 函数名: vTaskEndScheduler 头文件:task.h 函数声明: void vtaskendscheduler(void) 函数功能:停止实时内核的时间封。所有已经创建的任务会被自动删除,多任务处理(无论 是可占先述是非可占先仟务)停止。 执行从调用 vTaskStart Scheduler处恢复执行,当 VTaskstart Scheduler返回时。(笔 者注释,翻译得比较拗口,后续修止。) 见demo/PC文件夹的DEM文件main.c,演示了 vTaskendScheduler(的使用。 vTaskEndScheduler需要在移植层定义一个退出函数,这表现为硬件指定操作,比如停 止时间封(停止定时器?待后续追加注释) vTaskEndScheduler导致所有由内核分配的资源被释放,但由任务分配的资源不会被释 放。 范例 void vTaskCode( void a paRameters or / Task code goes here // At some point we want to end the real time kernel processing so Ca scheduler void aFUnction( void / Create at least one task before starting the kernel TaskCreate( v TaskCode,NAME, STACK SIZE, NULL, tskIDLE PRIORITY, NULL / Start the real time kernel with preemption vTaskStart Scheduler // Will only get here when the vTaskCode o task has called //vTaskEndScheduler ( When we get here we are back to single task exccution 8、 vTaskSuspendA11 所数名: TaskSuspendAl1 头文件:task.h 函数声明: void vTaskSuspendAll(void) 函数功能:挂起所有实时内核的活动,当保持中断(包括内核时间封中断)使能时 当调用 v TaskSuspendAll(后,调用该函数的任务依然会执行而不会被置换出运行态, 直到 xTaskResumeAll O被调用(即可以重新廾始任条调度,则当前的任务当然有可能被 置换岀运行态)。 冇澘在可能导致现场切换的API函数不得被调用,当调度器被挂起时。 范例 void vTaskI( void s paRameters / Task code goes here / / At somc point the task wants to perform a long opcration during / which it does not want to get swapped out. It cannot use / taskENTER CRITICAL (/taskEXIT CRITICAL ( as thc lcngth of thc operation may cause interrupts to be missed- including the / ticks Prevent the real time kernel swapping out the task vTaskSuspendAll O // Perform the operation here. There is no need to use critical // sections as we have all the microcontroller processing time / During this time interrupts will still operate and the kerne // tick count will be maintained / The operation is complete. Restart the kernel xTaskResumeAll O 9、 XTaskResumeA11 函数名: XTaskResueAll 头文件:task.h 函数声明: portBASE Type XTaskResumeAll(void); 乐数功能:恢复实时内核的活动。调用后,内核决定何时何地何任务运行。 返回值 如果再召唤调度器导致现场切换,返回 PaTRIE,否则为 pdFALSE。 范例 void vtaskl( void x paRameters for(:: // Task code goe es here / / At some point the task wants to perform a long operation during // which it does not want to get swapped out. It cannot use / taskENTER CRITICAL (/taskEXIT CRITICAL ()as the lcngth of thc // operation may cause interrupts to be missed- including the 7 ticks / Prevent the real time kernel swapping out the task xTaskSuspendAll O 7/ Perform the operation here. There is no need to use critica // sections as we have all the microcontroller processing time // during this time interrupts will still operate and the real // time kernel tick count will be maintained / The operation is complete. Restart the kernel. We want to force / a contcxt switch but there is no point if resuming the scheduler caused a context switch already if(! xTask ResumeAll () taskYIeLd o 五、FRT0SMPU函数 暂不翻译。 六、消息队列 If includE vTaskSuspend is set to 1 then specifying the block time as portMAX DELAY will cause the task to block indefinitely (without d 1 uxQueueMessagesWaiting 函数名: ux QueueMessages Waiting 头文件: queue.h 函数声明: unsigned porLBASE TYPE uxQueueMessages Waiving( XQueueHandle qUeue) 函数功能:返回消息队列中的消息数 2、 XQueue Create 函数名: XQueueCreate 头文件: queue.h 函数声明: xQueueHandle xQueue Create unsigned portBASE TYPE uxQueueLeng th insigned port BAsE TYPE uxItemSize 乐数功能:创建一个消息队列 具体参数 uxQueuelength:消息队列能存储的最大消息数。 uxItemSize:每条消息的字节数。消息是靠拷贝而非引用进入队列,因此该字节数会被拷 贝到每条发出的消息,队列中的每条消息必须是同样大小。 返回值 如果成功创建,则返回一个针对新建的消息队列的句柄,否则返回0。 范例 struct AMessage port Char ucMessage ID portCHAR ucData[ 20 void vATask( void *pvParameters xQueueHandle xQueue l, Queue2 【实例截图】
【核心代码】