FreeRTOS API Reference

Started by tha, December 07, 2021, 06:05:54 AM

Previous topic - Next topic

tha

https://www.freertos.org/a00019.html



Detailed Description

TaskHandle_t

task. h

Type โดยที่ tasks ถูกอ้างอิง. ตัวอย่างเช่น, การเรียกไปยัง xTaskCreate รีเทิร์น (โดยทาง a pointer parameter) an TaskHandle_t variable ที่ดังนั้นสามารถถูกใช้เป็น a parameter ไปยัง vTaskDelete เพื่อลบ the task.

tha

https://www.freertos.org/a00125.html



สร้าง a new task และเพิ่มมันไปยังรายการของ tasks ที่พร้อมจะรัน. configSUPPORT_DYNAMIC_ALLOCATION ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h, หรือทิ้งไว้ไม่กำหนด (ซึ่งในกรณีนี้มันจะมีค่าเริ่มต้นเป็น 1), เพื่อให้ RTOS API function นี้มีให้ใช้เป็นประโยชน์.

แต่ละ task ต้องการ RAM ที่ถูกใช้เก็บ the task state, และที่ใช้โดย the task เป็น stack ของมัน. ถ้า a task ถูกสร้างโดยใช้ xTaskCreate() ดังนั้น RAM ที่ต้องการจะถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า a task ถูกสร้างโดยใช้ xTaskCreateStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ดังนั้นมันสามารถถูกจัดสรรแบบคงที่ที่ compile time. ดู the Static Vs Dynamic allocation page สำหรับข้อมูลเพิ่มเติม.

ถ้าคุณกำลังใช้ FreeRTOS-MPU ดังนั้นเราขอแนะนำให้คุณใช้ xTaskCreateRestricted() แทน xTaskCreate().

Parameters:

     pvTaskCode      ตัวชี้ไปยัง the task entry function (เพียงเป็นชื่อของ the function ที่จัดให้มีใช้ the task, ดูตัวอย่างข้างล่าง).

                            Tasks โดยปกติจัดให้มีใช้เป็น an infinite loop; the function ซึ่งจัดให้มีใช้ the task ต้องไม่พยายามรีเทิร์นหรือออก. อย่างไรก็ตาม Tasks
                            สามารถ, ลบตัวของพวกมันเอง.

     pcName         ชื่อที่สื่อความหมายสำหรับ the task. ส่วนใหญ่จะถูกใช้เพื่ออำนวยความสะดวกในการดีบัก, แต่สามารถถูกใช้เพื่อรับ a task handle อีกด้วย.

                            ความยาวสูงสุดของชื่อ task ถูกกำหนดโดย configMAX_TASK_NAME_LEN ใน FreeRTOSConfig.h.

     usStackDepth   จำนวนของ words (ไม่ใช่ bytes!) ที่จัดสรรสำหรับใช้เป็น the task's stack. ตัวอย่างเช่น, ถ้า the stack กว้าง 16-bits และ usStackDepth
                            คือ 100, ดังนั้น 200 bytes จะถูกจัดสรรสำหรับใช้เป็น the task's stack. อีกตัวอย่างหนึ่ง, ถ้า the stack กว้าง 32-bits และ usStackDepth
                            คือ 400 ดังนั้น 1600 bytes จะถูกจัดสรรสำหรับใช้เป็น the task's stack.

                            The stack depth คูณด้วย the stack width ต้องไม่เกินค่าสูงสุดที่สามารถถูกบรรจุในตัวแปรของชนิด size_t.

                            ดูคำถามที่พบบ่อย How big should the stack be?

     pvParameters   ค่าที่ถูกส่งผ่านเป็น the paramater ไปยัง the created task.

                            ถ้า pvParameters ถูกเซ็ตเป็น the address of a variable ดังนั้น the variable ต้องยังคงมีอยู่เมื่อ the created task ปฏิบัติ - ดังนั้นมันจะ
                            ใช้ไม่ได้ที่จะส่งผ่าน the address of a stack variable.

     uxPriority         The priority ที่ the created task จะปฏิบัติ.

                            Systems ที่รวมการรองรับ MPU สามารถมีทางเลือกที่จะสร้าง a task ใน a privileged (system) mode โดยการเซ็ต the bit
                            portPRIVILEGE_BIT ใน uxPriority. ตัวอย่างเช่น, เพื่อสร้าง a privileged task ที่ priority 2 เซ็ต uxPriority เป็น ( 2 |
                            portPRIVILEGE_BIT ).

                            Priorities ถูกถือสิทธิ์จะน้อยกว่า configMAX_PRIORITIES. ถ้า configASSERT ไม่ถูกกำหนด, priorities จะถูกจำกัดไว้ที่
                            (configMAX_PRIORITIES - 1).

     pxCreatedTask  ใช้ส่งผ่าน a handle ไปยัง task ที่สร้างขึ้นจาก the xTaskCreate() function. pxCreatedTask เป็นทางเลือกและสามารถถูกเซ็ตเป็น NULL.

Returns:

ถ้า the task ถูกสร้างขึ้นสำเร็จแล้ว pdPASS จะถูกส่งคืนกลับ มิฉะนั้น errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY จะถูกส่งคืนกลับ





tha

https://www.freertos.org/xTaskCreateStatic.html



สร้าง a new task และเพิ่มมันไปยังรายการของ tasks ที่พร้อมรัน. configSUPPORT_STATIC_ALLOCATION ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h เพื่อให้ RTOS API function นี้มีให้ใช้เป็นประโยชน์.

แต่ละ task ต้องการ RAM ที่ถูกใช้เก็บ the task state, และที่ใช้โดย the task เป็น stack ของมัน. ถ้า a task ถูกสร้างโดยใช้ xTaskCreate() ดังนั้น RAM ที่ต้องการจะถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า a task ถูกสร้างโดยใช้ xTaskCreateStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ซึ่งส่งผลให้มีพารามิเตอร์จำนวนที่มากขึ้น ดังนั้นมันสามารถถูกจัดสรรแบบคงที่ที่ compile time. ดู the Static Vs Dynamic allocation page สำหรับข้อมูลเพิ่มเติม.

ถ้าคุณกำลังใช้ FreeRTOS-MPU ดังนั้นเราขอแนะนำให้คุณใช้ xTaskCreateRestricted() แทน xTaskCreateStatic()

tha

Parameters:

     pvTaskCode        ตัวชี้ไปยัง the task entry function (เพียงเป็นชื่อของ the function ที่จัดให้มีใช้ the task, ดูตัวอย่างข้างล่าง).

                              Tasks โดยปกติจัดให้มีใช้เป็น an infinite loop; the function ซึ่งจัดให้มีใช้ the task ต้องไม่พยายามรีเทิร์นหรือออก. อย่างไรก็ตาม Tasks
                              สามารถ, ลบตัวของพวกมันเอง.

     pcName            ชื่อที่สื่อความหมายสำหรับ the task. ส่วนใหญ่จะถูกใช้เพื่ออำนวยความสะดวกในการดีบัก, แต่สามารถถูกใช้เพื่อรับ a task handle อีกด้วย.

                             ความยาวสูงสุดของชื่อ task ถูกกำหนดโดย configMAX_TASK_NAME_LEN ใน FreeRTOSConfig.h.

     ulStackDepth     The puxStackBuffer parameter ถูกใช้เพื่อส่งผ่านอาร์เรย์ของตัวแปร StackType_t ลงใน xTaskCreateStatic(). ulStackDepth ต้อง
                              ถูกเซ็ตเป็นจำนวนของดัชนีใน the array.

                              ดูคำถามที่พบบ่อย How big should the stack be?

     pvParameters    ค่าที่ถูกส่งผ่านเป็น the paramater ไปยัง the created task.

                             ถ้า pvParameters ถูกเซ็ตเป็น the address of a variable ดังนั้น the variable ต้องยังคงมีอยู่เมื่อ the created task ปฏิบัติ - ดังนั้นมัน
                             จะใช้ไม่ได้ที่จะส่งผ่าน the address of a stack variable.

     uxPriority          The priority ที่ the created task จะปฏิบัติ.

                             Systems ที่รวมการรองรับ MPU สามารถมีทางเลือกที่จะสร้าง a task ใน a privileged (system) mode โดยการเซ็ต the bit
                             portPRIVILEGE_BIT ใน uxPriority. ตัวอย่างเช่น, เพื่อสร้าง a privileged task ที่ priority 2 เซ็ต uxPriority เป็น ( 2 |
                             portPRIVILEGE_BIT ).

                              Priorities ถูกถือสิทธิ์จะน้อยกว่า configMAX_PRIORITIES. ถ้า configASSERT ไม่ถูกกำหนด, priorities จะถูกจำกัดไว้ที่
                              (configMAX_PRIORITIES - 1).

tha

     puxStackBuffer  ต้องชี้ไปยัง a StackType_t array ที่มีอย่างน้อย ulStackDepth indexes (ดู the ulStackDepth parameter ข้างบน) - the array จะถูก
                                  ใช้เป็น the task's stack, ดังนั้นมันต้องคงอยู่ (ไม่ประกาศบน the stack of a function).

     pxTaskBuffer     ต้องชี้ไปยัง a variable of type StaticTask_t. The variable จะถูกใช้เพื่อเก็บ the new task's data structures (TCB), ดังนั้นมันต้องคง
                                  อยู่ (ไม่ประกาศบน the stack of a function).

Returns:

ถ้าไม่ทั้ง puxStackBuffer หรือ pxTaskBuffer เป็น NULL ดังนั้น the task จะถูกสร้าง, และ the task's handle จะถูกรีเทิร์น. ถ้าอย่างใดอย่างหนึ่ง puxStackBuffer หรือ pxTaskBuffer เป็น NULL ดังนั้น the task จะไม่ถูกสร้างและ NULL จะถูกรีเทิร์น.



tha

https://www.freertos.org/xtaskcreaterestrictedstaticfreertos-mpu-specific.html



สร้าง a new Memory Protection Unit (MPU) restricted task และเพิ่มมันไปยังรายการของ tasks ที่พร้อมจะรัน. configSUPPORT_STATIC_ALLOCATION ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h เพื่อให้ RTOS API function นี้มีให้ใช้เป็นประโยชน์.

ภายใน, ภายใน the FreeRTOS implementation, แต่ละh task ต้องการ two blocks of memory. The first block ถูกใช้เพื่อเก็บ the task's data structures. The second block ถูกใช้เป็น the task's stack. ถ้า a task ถูกสร้างโดยใช้ xTaskCreateRestricted() ดังนั้น the memory สำหรับ the task's stack ถูกจัดให้มีโดย the application writer, และ the memory สำหรับ the task's data structures ถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า a task ถูกสร้างโดยใช้ xTaskCreateRestrictedStatic() ดังนั้น the application writer ต้องจัดให้มี the memory สำหรับ the task's data structures ด้วย. xTaskCreateRestrictedStatic() ดังนั้นยอมให้ a memory protected task ถูกสร้างโดยไม่มีการใช้ dynamic memory allocation ใดๆ.

xTaskCreateRestrictedStatic() ถูกมุ่งหมายสำหรับใช้กับ FreeRTOS-MPU, the demo applications ซึ่งบรรจุตัวอย่างที่ครอบคลุมและจัดทำเป็นเอกสารเกี่ยวกับวิธีการใช้ฟังก์ชันที่คล้ายกัน xTaskCreateRestricted().

Parameters:

     pxTaskDefinition   ตัวชี้ไปยัง a structure ที่กำหนด the task. The structure ถูกอธิบายไว้ในหน้านี้.

     pxCreatedTask    ที่ใช้ส่งผ่านกลับ a handle โดยที่ the created task สามารถถูกอ้างอิง.

Returns:

     pdPASS ถ้า the task ถูกสร้างสำเร็จแล้วและเพิ่มไปยังรายการพร้อมทำงาน, มิฉะนั้น an error code ที่กำหนดใน the file projdefs.h

Tasks ที่รวมการรองรับ MPU ต้องการ parameters ในการสร้างมากกว่าที่ไม่มี. การส่งผ่านแต่ละ parameter ไปยัง xTaskCreateRestrictedStatic() แต่ละรายการจะไม่สะดวก ดังนั้นแทนที่ด้วย the structure TaskParameters_t ถูกใช้เพื่อยอมให้ the parameters ถูกกำหนดค่าแบบคงที่ในขณะ compile time. The structure ถูกกำหนดใน task.h ดังนี้:


tha

ต่อไปนี้คือคำอธิบายของแต่ละ structure member:

     •  pvTaskCode to uxPriority

        สมาชิกเหล่านี้เหมือนกันทุกประการกับพารามิเตอร์ของชื่อเดียวกันที่ส่งไปยัง xTaskCreate() โดยเฉพาะอย่างยิ่ง uxPriority ถูกใช้เพื่อเซ็ตทั้ง the priority of the
        task และ the mode ซึ่ง the task จะปฏิบัติ. ตัวอย่างเช่น, เพื่อสร้าง a User mode task ที่ priority 2, เซ็ตง่ายๆ uxPriority เป็น 2, เพื่อสร้าง a
        Privileged mode task ที่ priority 2 เซ็ต uxPriority เป็น ( 2 | portPRIVILEGE_BIT ).

     •  puxStackBuffer

        ทุกครั้งที่ a task ถูกสลับเข้า, the MPU จะถูกกำหนดค่าใหม่แบบไดนามิกเพื่อกำหนด a region ที่จัดให้มี the task อ่านและเขียนเข้าถึงไปยัง stack ของตัวมัน
        เอง. MPU regions ต้องเป็นไปตามข้อจำกัดจำนวนหนึ่ง - โดยเฉพาะ, the size และ alignment ของ regions ดังกล่าวทั้งหมดต้องเท่ากับค่ากำลังสองเดียวกัน

        Standard FreeRTOS ports ใช้ pvPortMalloc() เพื่อจัดสรร a new stack แต่ละครั้งที่ a task ถูกสร้าง. การจัดให้มี a pvPortMalloc() implementation
        ที่ดูแล the MPU data alignment requirements จะสามารถเป็นไปได้แต่จะซับซ้อนและไม่มีประสิทธิภาพในการใช้ RAM ของมันด้วย. เพื่อขจัดความจำเป็นใน
        ความซับซ้อนนี้  FreeRTOS-MPU ยอมให้ stacks ถูกประกาศแบบคงที่ในขณะ compile time. นี้ยอมให้ the alignment ถูกจัดการโดยใช้ compiler
        extensions และประสิทธิภาพการใช้ RAM usage ถูกจัดการโดย the linker. ตัวอย่างเช่น, ถ้าใช้ GCC, a stack สามารถถูกประกาศและวางแนวอย่างถูกต้องโดย
        ใช้โค้ดต่อไปนี้:

                  char cTaskStack[ 1024 ] __attribute__((aligned(1024));

        puxStackBuffer โดยปกติจะถูกเซ็ตเป็น the address of the statically declared stack. ตามที่ puxStackBuffer อีกทางเลือกสามารถถูกเซ็ตเป็น NULL -
        ในกรณีนี้ pvPortMallocAligned() จะถูกเรียกเพื่อจัดสรร the task stack และมันเป็นความรับผิดชอบของ the application writer เพื่อจัดให้มี an
        implementation of pvPortMallocAligned() ที่ตรงตาม the alignment requirements of the MPU.