diff options
Diffstat (limited to 'pw_thread_threadx/docs.rst')
| -rw-r--r-- | pw_thread_threadx/docs.rst | 224 |
1 files changed, 112 insertions, 112 deletions
diff --git a/pw_thread_threadx/docs.rst b/pw_thread_threadx/docs.rst index 026ed2bff..d49c133ca 100644 --- a/pw_thread_threadx/docs.rst +++ b/pw_thread_threadx/docs.rst @@ -6,7 +6,7 @@ pw_thread_threadx This is a set of backends for pw_thread based on ThreadX. .. Warning:: - This module is still under construction, the API is not yet stable. + This module is still under construction, the API is not yet stable. ----------------------- Thread Creation Backend @@ -21,48 +21,48 @@ be created as follows: .. code-block:: cpp - #include "pw_thread/detached_thread.h" - #include "pw_thread_threadx/config.h" - #include "pw_thread_threadx/context.h" - #include "pw_thread_threadx/options.h" - #include "tx_api.h" - - constexpr UINT kFooPriority = - pw::thread::threadx::config::kDefaultPriority; - constexpr ULONG kFooTimeSliceInterval = - pw::thread::threadx::config::kDefaultTimeSliceInterval; - constexpr size_t kFooStackSizeWords = - pw::thread::threadx::config::kDefaultStackSizeWords; - - pw::thread::threadx::ContextWithStack<kFooStackSizeWords> - example_thread_context; - void StartExampleThread() { - pw::thread::DetachedThread( - pw::thread::threadx::Options() - .set_name("example_thread") - .set_priority(kFooPriority) - .set_time_slice_interval(kFooTimeSliceInterval) - .set_context(example_thread_context), - example_thread_function); - } + #include "pw_thread/detached_thread.h" + #include "pw_thread_threadx/config.h" + #include "pw_thread_threadx/context.h" + #include "pw_thread_threadx/options.h" + #include "tx_api.h" + + constexpr UINT kFooPriority = + pw::thread::threadx::config::kDefaultPriority; + constexpr ULONG kFooTimeSliceInterval = + pw::thread::threadx::config::kDefaultTimeSliceInterval; + constexpr size_t kFooStackSizeWords = + pw::thread::threadx::config::kDefaultStackSizeWords; + + pw::thread::threadx::ContextWithStack<kFooStackSizeWords> + example_thread_context; + void StartExampleThread() { + pw::thread::DetachedThread( + pw::thread::threadx::Options() + .set_name("example_thread") + .set_priority(kFooPriority) + .set_time_slice_interval(kFooTimeSliceInterval) + .set_context(example_thread_context), + example_thread_function); + } .. list-table:: - * - :ref:`module-pw_thread` Facade - - Backend Target - - Description - * - ``pw_thread:id`` - - ``pw_thread_threadx:id`` - - Thread identification. - * - ``pw_thread:yield`` - - ``pw_thread_threadx:yield`` - - Thread scheduler yielding. - * - ``pw_thread:sleep`` - - ``pw_thread_threadx:sleep`` - - Thread scheduler sleeping. - * - ``pw_thread:thread`` - - ``pw_thread_threadx:thread`` - - Thread creation. + * - :ref:`module-pw_thread` Facade + - Backend Target + - Description + * - ``pw_thread:id`` + - ``pw_thread_threadx:id`` + - Thread identification. + * - ``pw_thread:yield`` + - ``pw_thread_threadx:yield`` + - Thread scheduler yielding. + * - ``pw_thread:sleep`` + - ``pw_thread_threadx:sleep`` + - Thread scheduler sleeping. + * - ``pw_thread:thread`` + - ``pw_thread_threadx:thread`` + - Thread creation. Module Configuration Options ============================ @@ -73,111 +73,111 @@ more details. .. c:macro:: PW_THREAD_THREADX_CONFIG_JOINING_ENABLED - Whether thread joining is enabled. By default this is disabled. + Whether thread joining is enabled. By default this is disabled. - We suggest only enabling this when thread joining is required to minimize - the RAM and ROM cost of threads. + We suggest only enabling this when thread joining is required to minimize + the RAM and ROM cost of threads. - Enabling this grows the RAM footprint of every pw::thread::Thread as it adds - a TX_EVENT_FLAGS_GROUP to every thread's pw::thread::threadx::Context. In - addition, there is a minute ROM cost to construct and destroy this added - object. + Enabling this grows the RAM footprint of every pw::thread::Thread as it adds + a TX_EVENT_FLAGS_GROUP to every thread's pw::thread::threadx::Context. In + addition, there is a minute ROM cost to construct and destroy this added + object. - PW_THREAD_JOINING_ENABLED gets set to this value. + PW_THREAD_JOINING_ENABLED gets set to this value. .. c:macro:: PW_THREAD_THREADX_CONFIG_DEFAULT_STACK_SIZE_WORDS - The default stack size in words. By default this uses the minimal ThreadX - stack size. + The default stack size in words. By default this uses the minimal ThreadX + stack size. .. c:macro:: PW_THREAD_THREADX_CONFIG_MAX_THREAD_NAME_LEN - The maximum length of a thread's name, not including null termination. By - default this is arbitrarily set to 15. This results in an array of characters - which is this length + 1 bytes in every pw::thread::Thread's context. + The maximum length of a thread's name, not including null termination. By + default this is arbitrarily set to 15. This results in an array of characters + which is this length + 1 bytes in every pw::thread::Thread's context. .. c:macro:: PW_THREAD_THREADX_CONFIG_DEFAULT_TIME_SLICE_INTERVAL - The round robin time slice tick interval for threads at the same priority. - By default this is disabled as not all ports support this, using a value of 0 - ticks. + The round robin time slice tick interval for threads at the same priority. + By default this is disabled as not all ports support this, using a value of 0 + ticks. .. c:macro:: PW_THREAD_THREADX_CONFIG_MIN_PRIORITY - The minimum priority level, this is normally based on the number of priority - levels. + The minimum priority level, this is normally based on the number of priority + levels. .. c:macro:: PW_THREAD_THREADX_CONFIG_DEFAULT_PRIORITY - The default priority level. By default this uses the minimal ThreadX - priority level, given that 0 is the highest priority. + The default priority level. By default this uses the minimal ThreadX + priority level, given that 0 is the highest priority. .. c:macro:: PW_THREAD_THREADX_CONFIG_LOG_LEVEL - The log level to use for this module. Logs below this level are omitted. + The log level to use for this module. Logs below this level are omitted. ThreadX Thread Options ====================== .. cpp:class:: pw::thread::threadx::Options - .. cpp:function:: set_name(const char* name) + .. cpp:function:: set_name(const char* name) - Sets the name for the ThreadX thread, note that this will be deep copied - into the context and may be truncated based on - ``PW_THREAD_THREADX_CONFIG_MAX_THREAD_NAME_LEN``. + Sets the name for the ThreadX thread, note that this will be deep copied + into the context and may be truncated based on + ``PW_THREAD_THREADX_CONFIG_MAX_THREAD_NAME_LEN``. - .. cpp:function:: set_priority(UINT priority) + .. cpp:function:: set_priority(UINT priority) - Sets the priority for the ThreadX thread from 0 through 31, where a value - of 0 represents the highest priority, see ThreadX tx_thread_create for - more detail. + Sets the priority for the ThreadX thread from 0 through 31, where a value + of 0 represents the highest priority, see ThreadX tx_thread_create for + more detail. - **Precondition**: priority <= ``PW_THREAD_THREADX_CONFIG_MIN_PRIORITY``. + **Precondition**: priority <= ``PW_THREAD_THREADX_CONFIG_MIN_PRIORITY``. - .. cpp:function:: set_preemption_threshold(UINT preemption_threshold) + .. cpp:function:: set_preemption_threshold(UINT preemption_threshold) - Optionally sets the preemption threshold for the ThreadX thread from 0 - through 31. + Optionally sets the preemption threshold for the ThreadX thread from 0 + through 31. - Only priorities higher than this level (i.e. lower number) are allowed to - preempt this thread. In other words this allows the thread to specify the - priority ceiling for disabling preemption. Threads that have a higher - priority than the ceiling are still allowed to preempt while those with - less than the ceiling are not allowed to preempt. + Only priorities higher than this level (i.e. lower number) are allowed to + preempt this thread. In other words this allows the thread to specify the + priority ceiling for disabling preemption. Threads that have a higher + priority than the ceiling are still allowed to preempt while those with + less than the ceiling are not allowed to preempt. - Not setting the preemption threshold or explicitly specifying a value - equal to the priority disables preemption threshold. + Not setting the preemption threshold or explicitly specifying a value + equal to the priority disables preemption threshold. - Time slicing is disabled while the preemption threshold is enabled, i.e. - not equal to the priority, even if a time slice interval was specified. + Time slicing is disabled while the preemption threshold is enabled, i.e. + not equal to the priority, even if a time slice interval was specified. - The preemption threshold can be adjusted at run time, this only sets the - initial threshold. + The preemption threshold can be adjusted at run time, this only sets the + initial threshold. - **Precondition**: preemption_threshold <= priority + **Precondition**: preemption_threshold <= priority - .. cpp:function:: set_time_slice_interval(UINT time_slice_interval) + .. cpp:function:: set_time_slice_interval(UINT time_slice_interval) - Sets the number of ticks this thread is allowed to run before other ready - threads of the same priority are given a chance to run. + Sets the number of ticks this thread is allowed to run before other ready + threads of the same priority are given a chance to run. - Time slicing is disabled while the preemption threshold is enabled, i.e. - not equal to the priority, even if a time slice interval was specified. + Time slicing is disabled while the preemption threshold is enabled, i.e. + not equal to the priority, even if a time slice interval was specified. - A value of ``TX_NO_TIME_SLICE`` (a value of 0) disables time-slicing of - this thread. + A value of ``TX_NO_TIME_SLICE`` (a value of 0) disables time-slicing of + this thread. - Using time slicing results in a slight amount of system overhead, threads - with a unique priority should consider ``TX_NO_TIME_SLICE``. + Using time slicing results in a slight amount of system overhead, threads + with a unique priority should consider ``TX_NO_TIME_SLICE``. - .. cpp:function:: set_context(pw::thread::embos::Context& context) + .. cpp:function:: set_context(pw::thread::embos::Context& context) - Set the pre-allocated context (all memory needed to run a thread). Note - that this is required for this thread creation backend! The Context can - either be constructed with an externally provided ``pw::span<ULONG>`` - stack or the templated form of ``ContextWihtStack<kStackSizeWords`` can be - used. + Set the pre-allocated context (all memory needed to run a thread). Note + that this is required for this thread creation backend! The Context can + either be constructed with an externally provided ``pw::span<ULONG>`` + stack or the templated form of ``ContextWihtStack<kStackSizeWords`` can be + used. ----------------------------- Thread Identification Backend @@ -234,18 +234,18 @@ the most up-to-date information is captured, the stack pointer for the currently running thread must be provided for cases where the running thread is being captured. For ARM Cortex-M CPUs, you can do something like this: -.. Code:: cpp - - // Capture PSP. - void* stack_ptr = 0; - asm volatile("mrs %0, psp\n" : "=r"(stack_ptr)); - pw::thread::ProcessThreadStackCallback cb = - [](pw::thread::proto::Thread::StreamEncoder& encoder, - pw::ConstByteSpan stack) -> pw::Status { - return encoder.WriteRawStack(stack); - }; - pw::thread::threadx::SnapshotThread(my_thread, stack_ptr, - snapshot_encoder, cb); +.. code-block:: cpp + + // Capture PSP. + void* stack_ptr = 0; + asm volatile("mrs %0, psp\n" : "=r"(stack_ptr)); + pw::thread::ProcessThreadStackCallback cb = + [](pw::thread::proto::Thread::StreamEncoder& encoder, + pw::ConstByteSpan stack) -> pw::Status { + return encoder.WriteRawStack(stack); + }; + pw::thread::threadx::SnapshotThread(my_thread, stack_ptr, + snapshot_encoder, cb); ``SnapshotThreads()`` wraps the singular thread capture to instead captures all created threads to a ``pw::thread::proto::SnapshotThreadInfo`` message. |