thread.h File Reference
Functions and types used for thread management. More...
#include <cdefs.h>#include <compartment.h>#include <riscvreg.h>#include <stddef.h>#include <stdint.h>#include <tick_macros.h>#include <timeout.h>Go to the source code of this file.
Classes | |
| struct | SystickReturn |
| the absolute system tick value since boot, 64-bit, assuming never overflows More... | |
Enumerations | |
| enum | ThreadSleepFlags : uint32_t { ThreadSleepNoEarlyWake = 1 << 0 } |
Functions | |
| SystickReturn | thread_systemtick_get (void) |
| int | thread_sleep (TimeoutArgument timeout, uint32_t flags) |
| Sleep for at most the specified timeout (see timeout.h). | |
| uint16_t __cheri_libcall | thread_id_get (__if_c(void)) |
| Return the thread ID of the current running thread. | |
| uint64_t | thread_elapsed_cycles_idle (void) |
| Returns the number of cycles accounted to the idle thread. | |
| uint64_t | thread_elapsed_cycles_current (void) |
| Returns the number of cycles accounted to the current thread. | |
| uint16_t | thread_count () |
| Returns the number of user threads (that is, those defined in the xmake firmware configuration), including threads that have exited. | |
| static uint64_t | thread_microsecond_spin (uint32_t microseconds) |
| Wait for the specified number of microseconds. | |
| static uint64_t | thread_millisecond_wait (uint32_t milliseconds) |
| Wait for the specified number of milliseconds. | |
| static void ** | invocation_state_slot (size_t index) |
| Compute a pointer to a Compartment-Invocation-Local Storage slot. | |
| template<typename T, size_t Index = 1> | |
| T *& | invocation_state () |
| Return a typed reference to a Compartment-Invocation-Local Storage slot. | |
Detailed Description
Functions and types used for thread management.
Definition in file thread.h.
Enumeration Type Documentation
◆ ThreadSleepFlags
| enum ThreadSleepFlags : uint32_t |
Function Documentation
◆ invocation_state()
template<typename T, size_t Index = 1>
| T *& invocation_state | ( | ) |
Return a typed reference to a Compartment-Invocation-Local Storage slot.
By convention, this area holds two pointers, with the 0th reserved for the unwind.h machinery. Most users of this function should thus use the default Index of 1.
Definition at line 216 of file thread.h.
References invocation_state_slot().
◆ invocation_state_slot()
|
inlinestatic |
Compute a pointer to a Compartment-Invocation-Local Storage slot.
By convention, this area holds two pointers, with the 0th reserved for the unwind.h machinery. Most users of this function should thus use index 1.
See sdk/core/switcher/misc-assembly.h STACK_ENTRY_RESERVED_SPACE and its usage in the switcher and the loader. Also see sdk/include/unwind-assembly.h INVOCATION_LOCAL_UNWIND_LIST_OFFSET and its uses.
Definition at line 195 of file thread.h.
Referenced by cleanup_list_head(), and invocation_state().
◆ thread_count()
| uint16_t thread_count | ( | ) |
Returns the number of user threads (that is, those defined in the xmake firmware configuration), including threads that have exited.
This API never fails, but if the trusted stack is exhausted and it cannot be called then it will return -1. Callers that have not probed the trusted stack should check for this value.
The result of this is safe to cache because it will never change over time.
References thread_count().
Referenced by thread_count().
◆ thread_elapsed_cycles_current()
| uint64_t thread_elapsed_cycles_current | ( | void | ) |
Returns the number of cycles accounted to the current thread.
This API is available only if the scheduler is built with accounting support enabled.
References thread_elapsed_cycles_current().
Referenced by thread_elapsed_cycles_current().
◆ thread_elapsed_cycles_idle()
| uint64_t thread_elapsed_cycles_idle | ( | void | ) |
Returns the number of cycles accounted to the idle thread.
This API is available only if the scheduler is built with accounting support enabled.
References thread_elapsed_cycles_idle().
Referenced by thread_elapsed_cycles_idle().
◆ thread_id_get()
| uint16_t __cheri_libcall thread_id_get | ( | __if_c(void) | ) |
Return the thread ID of the current running thread.
This is mostly useful where one compartment can run under different threads and it matters which thread entered this compartment.
User threads (that is, those defined in the xmake firmware configuration) are 1-indexed, with 0 indicating primordial idle and scheduling contexts. User code never runs in these contexts and so anything using this result to index into a per-thread array may wish to subtract one and avoid allocating an array element for the idle thread.
This is implemented in the switcher.
References thread_id_get().
Referenced by thread_id_get(), and xTaskGetCurrentTaskHandle().
◆ thread_microsecond_spin()
|
inlinestatic |
Wait for the specified number of microseconds.
This is a busy-wait loop, not a yield. If the thread is preempted then the wait will be longer than requested.
Returns the number of microseconds that the thread actually waited, with an error margin of the number of instructions used to compute the wait time and execute the function epilogue.
Definition at line 122 of file thread.h.
References thread_microsecond_spin().
Referenced by thread_microsecond_spin().
◆ thread_millisecond_wait()
|
inlinestatic |
Wait for the specified number of milliseconds.
This will yield for periods that are longer than a scheduler tick and then spin for the remainder of the time.
Returns the number of milliseconds that the thread actually waited.
Definition at line 152 of file thread.h.
References thread_sleep(), and ThreadSleepNoEarlyWake.
Referenced by Ksz8851Ethernet::Ksz8851Ethernet().
◆ thread_sleep()
| int thread_sleep | ( | TimeoutArgument | timeout, |
| uint32_t | flags ) |
Sleep for at most the specified timeout (see timeout.h).
The thread becomes runnable once the timeout has expired but a higher-priority thread may prevent it from actually being scheduled. The return value is a saturating count of the number of ticks that have elapsed.
A call of thread_sleep with a timeout of zero is equivalent to yield, but reports the time spent sleeping. This requires a cross-compartment call and return in addition to the overheads of yield and so yield should be preferred in contexts where the elapsed time is not required.
The flags parameter is a bitwise OR of ThreadSleepFlags.
A sleeping thread may be woken early if no other threads are runnable or have earlier timeouts. The thread with the earliest timeout will be woken first. This can cause a yielding thread to sleep when no other thread is runnable, but avoids a potential problem where a high-priority thread yields to allow a low-priority thread to make progress, but then the low-priority thread does a short sleep. In this case, the desired behaviour is not to wake the high-priority thread early, but to allow the low-priority thread to run for the full duration of the high-priority thread's yield.
If you are using thread_sleep to elapse real time, pass ThreadSleepNoEarlyWake as the flags argument to prevent early wakeups.
References thread_sleep().
Referenced by thread_millisecond_wait(), thread_sleep(), vTaskDelay(), and LockGuard< Lock >::yield().
Generated by
1.18.0