Ewout van Bekkum | fe5b4a7 | 2021-02-01 17:03:58 -0800 | [diff] [blame] | 1 | .. _module-pw_thread_threadx: |
| 2 | |
Ewout van Bekkum | f4da489 | 2021-03-05 15:05:37 -0800 | [diff] [blame] | 3 | ================= |
Ewout van Bekkum | fe5b4a7 | 2021-02-01 17:03:58 -0800 | [diff] [blame] | 4 | pw_thread_threadx |
Ewout van Bekkum | f4da489 | 2021-03-05 15:05:37 -0800 | [diff] [blame] | 5 | ================= |
| 6 | This is a set of backends for pw_thread based on ThreadX. |
Ewout van Bekkum | fe5b4a7 | 2021-02-01 17:03:58 -0800 | [diff] [blame] | 7 | |
Ewout van Bekkum | f4da489 | 2021-03-05 15:05:37 -0800 | [diff] [blame] | 8 | .. Warning:: |
| 9 | This module is still under construction, the API is not yet stable. |
| 10 | |
| 11 | .. list-table:: |
| 12 | |
| 13 | * - :ref:`module-pw_thread` Facade |
| 14 | - Backend Target |
| 15 | - Description |
| 16 | * - ``pw_thread:id`` |
| 17 | - ``pw_thread_threadx:id`` |
| 18 | - Thread identification. |
| 19 | * - ``pw_thread:yield`` |
| 20 | - ``pw_thread_threadx:yield`` |
| 21 | - Thread scheduler yielding. |
| 22 | * - ``pw_thread:sleep`` |
| 23 | - ``pw_thread_threadx:sleep`` |
| 24 | - Thread scheduler sleeping. |
| 25 | * - ``pw_thread:thread`` |
| 26 | - ``pw_thread_threadx:thread`` |
| 27 | - Thread creation. |
Armando Montanez | fec572b | 2021-06-28 12:13:57 -0700 | [diff] [blame^] | 28 | |
| 29 | --------- |
| 30 | utilities |
| 31 | --------- |
| 32 | In cases where an operation must be performed for every thread, |
| 33 | ``ForEachThread()`` can be used to iterate over all the created thread TCBs. |
| 34 | Note that it's only safe to use this while the scheduler is disabled. |
| 35 | |
| 36 | -------------------- |
| 37 | Snapshot integration |
| 38 | -------------------- |
| 39 | This ``pw_thread`` backend provides helper functions that capture ThreadX thread |
| 40 | state to a ``pw::thread::Thread`` proto. |
| 41 | |
| 42 | SnapshotThread()/SnapshotThreads() |
| 43 | ================================== |
| 44 | ``SnapshotThread()`` captures the thread name, state, and stack information for |
| 45 | the provided RTX TCB to a ``pw::thread::Thread`` protobuf encoder. To ensure |
| 46 | the most up-to-date information is captured, the stack pointer for the currently |
| 47 | running thread must be provided for cases where the running thread is being |
| 48 | captured. For ARM Cortex-M CPUs, you can do something like this: |
| 49 | |
| 50 | .. Code:: cpp |
| 51 | |
| 52 | // Capture PSP. |
| 53 | void* stack_ptr = 0; |
| 54 | asm volatile("mrs %0, psp\n" : "=r"(stack_ptr)); |
| 55 | pw::thread::ProcessThreadStackCallback cb = |
| 56 | [](pw::thread::Thread::StreamEncoder& encoder, |
| 57 | pw::ConstByteSpan stack) -> pw::Status { |
| 58 | return encoder.WriteRawStack(stack); |
| 59 | }; |
| 60 | pw::thread::threadx::SnapshotThread(my_thread, stack_ptr, |
| 61 | snapshot_encoder, cb); |
| 62 | |
| 63 | ``SnapshotThreads()`` wraps the singular thread capture to instead captures |
| 64 | all created threads to a ``pw::thread::SnapshotThreadInfo`` message. This proto |
| 65 | message overlays a snapshot, so it is safe to static cast a |
| 66 | ``pw::snapshot::Snapshot::StreamEncoder`` to a |
| 67 | ``pw::thread::SnapshotThreadInfo::StreamEncoder`` when calling this function. |