FreeRTOS API Semaphore / Mutexes

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

Previous topic - Next topic

tha

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

xSemaphoreTake
[Semaphores]

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


semphr. h

xSemaphoreTake( SemaphoreHandle_t xSemaphore,
                 TickType_t xTicksToWait );

Macro เพื่อรับ a semaphore. The semaphore ต้องถูกสร้างก่อนหน้าด้วยการเรียกถึง xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or xSemaphoreCreateCounting().

มาโครนี้ต้องไม่ถูกเรียกจาก an ISR. xQueueReceiveFromISR() สามารถถูกใช้เพื่อเอา a semaphore จากภายใน an interrupt ถ้าต้องการ, แม้ว่าจะไม่ใช่การดำเนินการปกติก็ตาม. Semaphores ใช้ queues เป็นกลไกพื้นฐานของพวกมัน ดังนั้นฟังก์ชันจึงสามารถทำงานร่วมกันได้ในระดับหนึ่ง.

Parameters:

     xSemaphore         A handle to the semaphore ที่กำลังถูก take - ได้รับเมื่อ the semaphore ถูกสร้าง.

     xTicksToWait         เวลาเป็น ticks เพื่อรอสำหรับ the semaphore กลายมาเป็นมีให้ใช้ประโยชน์. The macro
                                    portTICK_PERIOD_MS สามารถถูกใช้เพื่อแปลงเป็น a real time. A block time เป็นศูนย์สามารถถูกใช้
                                    เพื่อวนตรวจเช็ค the semaphore.

                                     ถ้า INCLUDE_vTaskSuspend ถูกเซ็ตเป็น '1' ดังนั้นการระบุ the block time เป็น portMAX_DELAY
                                     จะเป็นเหตุให้ the task บล็อกโดยไม่มีกำหนด (โดยไม่มี a timeout).

Returns:

     pdTRUE ถ้า the semaphore ถูกได้รับแล้ว. pdFALSE ถ้า xTicksToWait หมดเวลาลงโดยไม่มี the semaphore กลายมาเป็นมีให้
     ใช้ประโยชน์.

Example usage:



tha

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

xSemaphoreTakeFromISR
[Semaphores]

semphr. h

xSemaphoreTakeFromISR
      (
        SemaphoreHandle_t xSemaphore,
        signed BaseType_t *pxHigherPriorityTaskWoken
      )


A version of xSemaphoreTake() ที่สามารถถูกเรียกจาก an ISR. ไม่เหมือน xSemaphoreTake(), xSemaphoreTakeFromISR() ไม่ยอมให้ a block time ถูกระบุ.

Parameters:

     xSemaphore                          The semaphore ที่กำลังถูก 'taken'. A semaphore ถูกอ้างอิงโดยตัวแปรชนิด
                                                     SemaphoreHandle_t และต้องถูกสร้างอย่างชัดแจ้งก่อนที่จะถูกใช้.

pxHigherPriorityTaskWoken   เป็นไปได้ (แม้ว่าไม่น่าเป็นไปได้และขึ้นอยู่กับ the semaphore type) ที่ a semaphore จะมีอย่าง
                                                     น้อยหนึ่ง tasks ที่บล็อกบนมันรอเพื่อให้ the semaphore. การเรียก
                                                     xSemaphoreTakeFromISR() จะทำให้ a task ที่ถูกบล็อกรอเพื่อให้ the semaphore
                                                     ออกจาก the Blocked state. ถ้าการเรียก the API function เป็นเหตุให้ a task ออกจาก
                                                     the Blocked state, และ the unblocked task นั้นมี a priority เท่ากับสูงกว่า the
                                                     currently executing task (the task ที่ถูกอินเตอร์รัพท์), ดังนั้น, ภายใน, the API
                                                     function จะเซ็ต *pxHigherPriorityTaskWoken เป็น pdTRUE.

                                                     ถ้า xSemaphoreTakeFromISR() เซ็ต *pxHigherPriorityTaskWoken เป็น pdTRUE,
                                                     ดังนั้น a context switch ควรถูกดำเนินการก่อนที่ the interrupt จะถูกออก. นี้จะทำให้แน่ใจ
                                                     ว่า the interrupt รีเทิร์นโดยตรงไปยัง the highest priority Ready state task. The
                                                     mechanism นี้เหมือนกันกับนั่นที่ใช้ใน the xQueueReceiveFromISR() function, และ
                                                     readers ถูกอ้างอิงถึง the xQueueReceiveFromISR() documentation สำหรับคำ
                                                     อธิบายที่มากขึ้น.

                                                     จาก FreeRTOS V7.3.0 pxHigherPriorityTaskWoken เป็น an optional parameter
                                                     และสามารถถูกเซ็ตเป็น NULL.

Returns:

     pdTRUE ถ้า the semaphore ถูก taken สำเร็จ. pdFALSE ถ้า the semaphore ไม่ถูก taken สำเร็จเนื่องจากมันไม่มีให้ใช้
     ประโยชน์.

tha

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

xSemaphoreTakeRecursive
[Semaphores]

semphr. h

xSemaphoreTakeRecursive( SemaphoreHandle_t xMutex,
                         TickType_t xTicksToWait );


Macro เพื่อให้ได้รับ, หรือ 'take', a mutex type semaphore ซ้ำ. The mutex ต้องถูกสร้างก่อนหน้าโดยใช้การเรียกถึง xSemaphoreCreateRecursiveMutex();

configUSE_RECURSIVE_MUTEXES ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h สำหรับมาโครนี้มีให้ใช้เป็นประโยชน์.

มาโครนี้ต้องไม่ถูกใช้บน mutexes ที่สร้างโดยใช้ xSemaphoreCreateMutex().

A mutex ที่ใช้ซ้ำๆสามารถถูก 'taken' ซ้ำๆโดย the owner. The mutex ไม่กลายมาเป็นมีให้ใช้เป็นประโยชน์จนกระทั่ง the owner เรียก xSemaphoreGiveRecursive() ต่อแต่ละคำขอ 'take' ที่สำเร็จ. ตัวอย่างเช่น, ถ้า a task 'takes' the same mutex สำเร็จ 5 ครั้งดังนั้น the mutex จะไม่มีให้ใช้เป็นประโยชน์ไปยัง task อื่นใดๆจนกว่ามันจะ 'given' the mutex กลับห้าครั้งพอดีอีกด้วย.

Parameters:

     xMutex                  A handle to the mutex ที่กำลังถูกได้รับ. นี้เป็น the handle ที่ส่งคืนกลับโดย
                                     xSemaphoreCreateRecursiveMutex().

     xTicksToWait       เวลาเป็น ticks เพื่อรอสำหรับ the semaphore กลายมาเป็นมีให้ใช้ประโยชน์. The macro
                                    portTICK_PERIOD_MS สามารถถูกใช้เพื่อแปลงเป็น a real time. A block time เป็นศูนย์สามารถถูกใช้
                                    เพื่อวนตรวจเช็ค the semaphore.  ถ้า the task เป็นเจ้าของ the semaphore อยู่แล้วดังนั้น
                                    xSemaphoreTakeRecursive() จะส่งคืนกลับทันที ไม่ว่าค่าของ xTicksToWait จะเป็นเท่าใด.

Returns:

     pdTRUE ถ้า the semaphore ถูกได้รับแล้ว. pdFALSE ถ้า xTicksToWait หมดเวลาลงโดยไม่มี the semaphore กลายมาเป็นมีให้
     ใช้ประโยชน์

Example usage:
(ตัวอย่างดูในลิ้งค์เอานะครับ)


tha

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

xSemaphoreGive
[Semaphores]

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


semphr. h

xSemaphoreGive( SemaphoreHandle_t xSemaphore );

Macro เพื่อปล่อย a semaphore. The semaphore must ต้องถูกสร้างก่อนหน้าด้วยการเรียกถึง xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or xSemaphoreCreateCounting().

นี้ต้องไม่ถูกใช้จาก an ISR. ดู xSemaphoreGiveFromISR() เป็นทางเลือกซึ่งสามารถถูกใช้จาก an ISR.

มาโครนี้ต้องไม่ถูกใช้บน semaphores ที่สร้างโดยใช้ xSemaphoreCreateRecursiveMutex().

Parameters:
     
     xSemaphore          A handle to the semaphore ที่กำลังถูกปล่อย. นี้เป็น the handle ที่ส่งคืนกลับเมื่อตอน the semaphore
                                       ถูกสร้าง.

Returns:

     pdTRUE ถ้า the semaphore ถูกปล่อยแล้ว. pdFALSE ถ้า an error เกิดขึ้น. Semaphores ถูกจัดให้มีใช้โดยใช้ queues. An
     error สามารถเกิดขึ้นถ้าไม่มี space บน the queue เพื่อโพสต์ a message - แสดงให้เห็นว่า the semaphore ไม่ถูกได้รับอย่างถูก
     ต้องในตอนแรก.

Example usage:
(ตัวอย่างดูในลิ้งค์เอานะครับ)

tha

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

xSemaphoreGiveRecursive
[Semaphores]

semphr. h

xSemaphoreGiveRecursive( SemaphoreHandle_t xMutex )

Macro เพื่อปล่อย, หรือ 'give', a mutex type semaphore ซ้ำๆ. The mutex ต้องถูกสร้างก่อนหน้าโดยใช้การเรียกถึง xSemaphoreCreateRecursiveMutex();

configUSE_RECURSIVE_MUTEXES ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h สำหรับมาโครนี้มีให้ใช้เป็นประโยชน์.

มาโครนี้ต้องไม่ถูกใช้บน mutexes ที่สร้างโดยใช้ xSemaphoreCreateMutex().

A mutex ที่ใช้ซ้ำๆสามารถถูก 'taken' ซ้ำๆโดย the owner. The mutex ไม่กลายมาเป็นมีให้ใช้เป็นประโยชน์จนกระทั่ง the owner เรียก xSemaphoreGiveRecursive() ต่อแต่ละคำขอ 'take' ที่สำเร็จ. ตัวอย่างเช่น, ถ้า a task 'takes' the same mutex สำเร็จ 5 ครั้งดังนั้น the mutex จะไม่มีให้ใช้เป็นประโยชน์ไปยัง task อื่นใดๆจนกว่ามันจะ 'given' the mutex กลับห้าครั้งพอดีอีกด้วย.

Parameters:

     xMutex          A handle to the mutex ที่กำลังถูกปล่อย, หรือ 'given'. นี้คือ the handle ที่ส่งคืนกลับโดย
                              xSemaphoreCreateRecursiveMutex().

Returns:

     pdTRUE ถ้า the semaphore ถูกให้สำเร็จ.

Example usage:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

tha

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

xSemaphoreGiveFromISR
[Semaphores]

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

xSemaphoreGiveFromISR
      (
        SemaphoreHandle_t xSemaphore,
        signed BaseType_t *pxHigherPriorityTaskWoken
      )


Macro เพื่อปล่อย a semaphore. The semaphore ต้องถูกสร้างก่อนหน้าด้วยการเรียกถึง xSemaphoreCreateBinary() or xSemaphoreCreateCounting().

Mutex type semaphores (เหล่านั้นที่สร้างโดยใช้การเรียกถึง xSemaphoreCreateMutex()) ต้องไม่ถูกใช้ด้วย macro นี้.

มาโครนี้สามารถถูกใช้จาก an ISR.

Parameters:

      xSemaphore                           A handle to the semaphore ที่กำลังถูกปล่อย. นี้คือ the handle ที่ส่งคืนกลับเมื่อตอน the
                                                        semaphore ถูกสร้าง.

pxHigherPriorityTaskWoken      xSemaphoreGiveFromISR() จะเซ็ต *pxHigherPriorityTaskWoken เป็น pdTRUE ถ้า
                                                         การให้ the semaphore เป็นเหตุให้ a task ปลดบล็อก, และ the unblocked task มี a
                                                         priority สูงกว่า the currently running task. ถ้า xSemaphoreGiveFromISR()
                                                         เซ็ตค่านี้เป็น pdTRUE ดังนั้น a context switch ควรถูกร้องขอก่อนที่ the interrupt จะ
                                                         ถูกออก.

                                                         จาก FreeRTOS V7.3.0 pxHigherPriorityTaskWoken เป็น an optional
                                                         parameter และสามารถถูกเซ็ตเป็น NULL.

Returns:

     pdTRUE ถ้า the semaphore ถูกให้สำเร็จ, ถ้าเป็นอย่างอื่น errQUEUE_FULL.

Example usage:

โปรดทราบว่าฟังชั่นที่แสดงข้างล่างสามารถมักจะถูกทำให้สำเร็จในวิธีที่มีประสิทธิภาพมากกว่าโดยการใช้ a direct to task notification แทนที่ a semaphore.

(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)