FreeRTOS API Semaphore / Mutexes

Started by tha, January 09, 2022, 11:03:11 AM

Previous topic - Next topic

tha

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

Semaphores
[API]

      TIP: 'Task Notifications' สามารถจัดให้มี a light weight alternative แทน semaphores ในหลายสถานะการณ์


tha

vSemaphoreDelete

semphr.h

void vSemaphoreDelete( SemaphoreHandle_t xSemaphore );

ลบ a semaphore, รวมถึง mutex type semaphores และ recursive semaphores.

ไม่ลบ a semaphore ที่มี tasks ถูกบล็อกบนมัน (tasks ที่อยู่ใน the Blocked state กำลังรอสำหรับ the semaphore กลายมาเป็นมีให้ใช้ประโยชน์).

Parameters:

     xSemaphore          The handle of the semaphore ที่กำลังถูกลบ.

tha

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

xSemaphoreCreateBinary
[Semaphores]

   เคล็ดลับ: ในสถานการณ์การใช้งานหลายๆ สถานการณ์ มันจะเร็วกว่าและ memory มีประสิทธิภาพมากขึ้นเมื่อใช้ a direct to task
                                                        notification แทน a binary semaphore

semphr. h

SemaphoreHandle_t xSemaphoreCreateBinary( void );

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

แต่ละ binary semaphore ต้องการจำนวนน้อยๆของ RAM ที่ถูกใช้เพื่อเก็บ the semaphore's state. ถ้า a binary semaphore ถูกสร้างโดยใช้ xSemaphoreCreateBinary() ดังนั้น RAM ที่ต้องการจะถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า a binary semaphore ถูกสร้างโดยใช้ xSemaphoreCreateBinaryStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ซึ่งต้องการ parameter เพิ่มเติม, แต่ยอมให้ the RAM ถูกจัดสรรแบบคงที่ที่เวลา compile. ดู the Static Vs Dynamic allocation page สำหรับข้อมูลเพิ่มเติม.

The semaphore ถูกสร้างใน the 'empty' state, หมายความว่า the semaphore อย่างแรกต้องถูกให้ก่อนโดยใช้ the xSemaphoreGive() API function ก่อนที่มันสามารถถูกเอาภายหลัง (ได้รับ) โดยใช้ the xSemaphoreTake() function.


tha

Binary semaphores และ mutexes จะคล้ายกันมากแต่มีความแตกต่างเล็กน้อย: Mutexes รวม a priority inheritance mechanism เอาไว้, binary semaphores ไม่มี. นี้ทำให้ binary semaphores เป็นตัวเลือกที่ดีกว่าสำหรับการจัดให้มีใช้ synchronisation (ระหว่าง tasks หรือระหว่าง tasks and an interrupt), และ mutexes เป็นตัวเลือกที่ดีกว่าสำหรับการจัดให้มีใช้การกันไว้สำหรับคนพิเศษอย่างง่ายๆ (simple mutual exclusion).

A binary semaphore ไม่จำเป็นต้องถูกให้คืนเมื่อได้รับ, ดังนั้น task synchronisation สามารถถูกจัดให้มีใช้โดย one task/interrupt  'ให้' the semaphore อย่างต่อเนื่องในขณะที่อีก task/interrupt หนึ่ง 'เอา' the semaphore อย่างต่อเนื่อง. นี้ถูกสาธิตโดย the sample code บน the xSemaphoreGiveFromISR() documentation page. โปรดทราบว่าฟังชั่นเดียวกันมักจะสามารถถูกทำให้สำเร็จในวิธีที่มีประสิทธิภาพมากกว่าโดยใช้ a direct to task notification.

tha

The priority of a task ที่ 'takes(เอา)' a mutex สามารถถูกทำให้พุ่งขึ้นอย่างมีศักยภาพถ้าอีก task หนึ่งที่มี higher priority พยายามได้รับ the same mutex. The task ที่เป็นเจ้าของ the mutex 'inherits(สืบทอด)' the priority of the task ที่กำลังพยายาม 'take(เอา)' the same mutex. นี้หมายความว่า the mutex ต้องถูก 'given(ให้)' กลับเสมอ - มิฉะนั้น the higher priority task จะไม่สามารถได้รับ the mutex, และ the lower priority task จะไม่ 'disinherit(ละทิ้ง)' the priority. An example of a mutex ที่กำลังถูกใช้เพื่อจัดให้มีใช้ mutual exclusion ถูกจัดให้มีบน the xSemaphoreTake() documentation page.

ทั้ง mutex and binary semaphores ถูกอ้างอิงโดยตัวแปรของชนิด SemaphoreHandle_t และสามารถถูกใช้ใน task level API function ใดๆก็ตามที่เอา a parameter ของชนิดนั้น. ไม่เหมือน mutexes, binary semaphores สามารถถูกใช้ใน interrupt service routines.

Return values:

      NULL                    The semaphore ไม่สามารถถูกสร้างเนื่องจากมี insufficient FreeRTOS heap ให้ใช้เป็นประโยชน์.

     Any other value     The semaphore ถูกสร้างสำเร็จแล้ว. The returned value คือ a handle ซึ่ง the semaphore สามารถถูก
                                       อ้างอิงถึงได้.


tha

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

xSemaphoreCreateBinaryStatic
[Semaphores]

   เคล็ดลับ: ในสถานการณ์การใช้งานหลายๆ สถานการณ์ มันจะเร็วกว่าและ memory มีประสิทธิภาพมากขึ้นเมื่อใช้ a direct to task
                                                        notification แทน a binary semaphore

semphr. h

SemaphoreHandle_t xSemaphoreCreateBinaryStatic(
                          StaticSemaphore_t *pxSemaphoreBuffer );


สร้าง a binary semaphore, และส่งคืนกลับ a handle ซึ่ง the semaphore สามารถถูกอ้างอิง. configSUPPORT_STATIC_ALLOCATION ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h, สำหรับ RTOS API function นี้มีให้ใช้เป็นประโยชน์.

แต่ละ binary semaphore ต้องการจำนวนน้อยๆของ RAM ที่ถูกใช้เพื่อเก็บ the semaphore's state. ถ้า a binary semaphore ถูกสร้างโดยใช้ xSemaphoreCreateBinary() ดังนั้น RAM ที่ต้องการจะถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า a binary semaphore ถูกสร้างโดยใช้ xSemaphoreCreateBinaryStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ซึ่งต้องการ parameter เพิ่มเติม, แต่ยอมให้ the RAM ถูกจัดสรรแบบคงที่ที่เวลา compile. ดู the Static Vs Dynamic allocation page สำหรับข้อมูลเพิ่มเติม.

The semaphore ถูกสร้างใน the 'empty' state, หมายความว่า the semaphore อย่างแรกต้องถูกให้ก่อนโดยใช้ the xSemaphoreGive() API function ก่อนที่มันสามารถถูกเอาภายหลัง (ได้รับ) โดยใช้ the xSemaphoreTake() function.

tha

Binary semaphores และ mutexes จะคล้ายกันมากแต่มีความแตกต่างเล็กน้อย: Mutexes รวม a priority inheritance mechanism เอาไว้, binary semaphores ไม่มี. นี้ทำให้ binary semaphores เป็นตัวเลือกที่ดีกว่าสำหรับการจัดให้มีใช้ synchronisation (ระหว่าง tasks หรือระหว่าง tasks and an interrupt), และ mutexes เป็นตัวเลือกที่ดีกว่าสำหรับการจัดให้มีใช้การกันไว้สำหรับคนพิเศษอย่างง่ายๆ (simple mutual exclusion).

A binary semaphore ไม่จำเป็นต้องถูกให้คืนเมื่อได้รับ, ดังนั้น task synchronisation สามารถถูกจัดให้มีใช้โดย one task/interrupt  'ให้' the semaphore อย่างต่อเนื่องในขณะที่อีก task/interrupt หนึ่ง 'เอา' the semaphore อย่างต่อเนื่อง. นี้ถูกสาธิตโดย the sample code บน the xSemaphoreGiveFromISR() documentation page. โปรดทราบว่าฟังชั่นเดียวกันมักจะสามารถถูกทำให้สำเร็จในวิธีที่มีประสิทธิภาพมากกว่าโดยใช้ a direct to task notification.

tha

The priority of a task ที่ 'takes(เอา)' a mutex สามารถถูกทำให้พุ่งขึ้นอย่างมีศักยภาพถ้าอีก task หนึ่งที่มี higher priority พยายามได้รับ the same mutex. The task ที่เป็นเจ้าของ the mutex 'inherits(สืบทอด)' the priority of the task ที่กำลังพยายาม 'take(เอา)' the same mutex. นี้หมายความว่า the mutex ต้องถูก 'given(ให้)' กลับเสมอ - มิฉะนั้น the higher priority task จะไม่สามารถได้รับ the mutex, และ the lower priority task จะไม่ 'disinherit(ละทิ้ง)' the priority. An example of a mutex ที่กำลังถูกใช้เพื่อจัดให้มีใช้ mutual exclusion ถูกจัดให้มีบน the xSemaphoreTake() documentation page.

ทั้ง mutex and binary semaphores ถูกอ้างอิงโดยตัวแปรของชนิด SemaphoreHandle_t และสามารถถูกใช้ใน task level API function ใดๆก็ตามที่เอา a parameter ของชนิดนั้น. ไม่เหมือน mutexes, binary semaphores สามารถถูกใช้ใน interrupt service routines.

Parameters:

     pxSemaphoreBuffer     ต้องชี้ไปยังตัวแปรของชนิด StaticSemaphore_t, ซึ่งจะถูกใช้เพื่อเก็บ the semaphore's state.

Return values:

      NULL                    The semaphore ไม่สามารถถูกสร้างเนื่องจาก pxSemaphoreBuffer เป็น NULL.

     Any other value     The semaphore ถูกสร้างสำเร็จแล้ว. The returned value คือ a handle ซึ่ง the semaphore สามารถถูก
                                       อ้างอิงถึงได้.