1.. _module-pw_sync_threadx: 2 3=============== 4pw_sync_threadx 5=============== 6.. pigweed-module:: 7 :name: pw_sync_threadx 8 9This is a set of backends for pw_sync based on ThreadX. 10 11It is possible, if necessary, to use pw_sync_threadx without using the Pigweed 12provided pw_chrono_threadx in case the ThreadX time API (``tx_time_get()``)) is 13not available (i.e. ``TX_NO_TIMER`` is set). You are responsible for ensuring 14that the chrono backend provided has counts which match the ThreadX tick based 15API. 16 17-------------------------------- 18Critical Section Lock Primitives 19-------------------------------- 20 21Mutex & TimedMutex 22================== 23The ThreadX backend for the Mutex and TimedMutex use ``TX_MUTEX`` as the 24underlying type. It is created using ``tx_mutex_create`` as part of the 25constructors and cleaned up using ``tx_mutex_delete`` in the destructors. 26 27InterruptSpinLock 28================= 29The ThreadX backend for InterruptSpinLock is backed by an ``enum class`` and 30two ``UINT`` which permits these objects to detect accidental recursive locking 31and unlocking contexts. 32 33This object uses ``tx_interrupt_control`` to enable critical sections. In 34addition, ``tx_thread_preemption_change`` is used to prevent accidental thread 35context switches while the InterruptSpinLock is held by a thread. 36 37.. Warning:: 38 This backend does not support SMP yet as there's no internal lock to spin on. 39 40-------------------- 41Signaling Primitives 42-------------------- 43 44ThreadNotification & TimedThreadNotification 45============================================ 46Prefer using the binary semaphore backends for ThreadNotifications as 47the native ThreadX API covers direct thread signaling: 48 49- ``pw_sync:binary_semaphore_thread_notification_backend`` 50- ``pw_sync:binary_semaphore_timed_thread_notification_backend`` 51 52Background Information 53---------------------- 54Although one may be tempted to use ``tx_thread_sleep`` and 55``tx_thread_wait_abort`` to implement direct thread notifications with ThreadX, 56this unfortunately cannot work. Between the blocking thread setting its 57``TX_THREAD*`` handle and actually executing ``tx_thread_sleep`` there will 58always exist a race condition. Another thread and/or interrupt may attempt 59to invoke ``tx_thread_wait_abort`` before the blocking thread has executed 60``tx_thread_sleep`` meaning the wait abort would fail. 61 62BinarySemaphore & CountingSemaphore 63=================================== 64The ThreadX backends for the BinarySemaphore and CountingSemaphore use 65``TX_SEMAPHORE`` as the underlying type. It is created using 66``tx_semaphore_create`` as part of the constructor and cleaned up using 67``tx_semaphore_delete`` in the destructor. 68