|
PebbleOS v4.47.0-512-g5285d4236
|
Thread creation, lifecycle and per-thread state. More...
Data Structures | |
| struct | pbl_thread_attr |
| struct | pbl_thread |
| Thread object. More... | |
Macros | |
| #define | PBL_THREAD_NAME_LEN 16 |
| Size of a thread name, including the terminating NUL. | |
| #define | PBL_THREAD_MAX_MEM_REGIONS 2 |
| Number of MPU regions a thread can bring, on top of its stack guards. | |
| #define | PBL_THREAD_STACK_DEFINE(name, size) |
| Define a thread stack, with room for its guard. | |
Typedefs | |
| typedef void(* | pbl_thread_entry_t) (void *arg) |
| Thread entry function. | |
Enumerations | |
| enum | pbl_thread_state { PBL_THREAD_READY , PBL_THREAD_RUNNING , PBL_THREAD_BLOCKED , PBL_THREAD_SUSPENDED , PBL_THREAD_DEAD } |
| Thread state. More... | |
Functions | |
| int | pbl_thread_create (struct pbl_thread *t, const struct pbl_thread_attr *attr) |
| Create and start a thread. | |
| void | pbl_thread_abort (struct pbl_thread *t) |
| End a thread. | |
| void | pbl_thread_suspend (struct pbl_thread *t) |
| Stop scheduling a thread until pbl_thread_resume(). | |
| void | pbl_thread_resume (struct pbl_thread *t) |
| Make a suspended thread runnable again. | |
| void | pbl_thread_yield (void) |
| Let other ready threads of the same priority run. | |
| void | pbl_thread_sleep (pbl_timeout_t timeout) |
| Block the calling thread for a while. | |
| struct pbl_thread * | pbl_thread_current (void) |
| Get the calling thread. | |
| struct pbl_thread * | pbl_thread_idle (void) |
| Get the kernel's idle thread. | |
| void | pbl_thread_prio_set (struct pbl_thread *t, pbl_prio_t prio) |
| Change the base priority of a thread. | |
| pbl_prio_t | pbl_thread_prio_get (const struct pbl_thread *t) |
| Get the base priority of a thread. | |
| enum pbl_thread_state | pbl_thread_state (const struct pbl_thread *t) |
| Get the state of a thread. | |
| static const char * | pbl_thread_name (const struct pbl_thread *t) |
| Get the name of a thread. | |
| static uint32_t | pbl_thread_id (const struct pbl_thread *t) |
| Get the creation ID of a thread. | |
| void | pbl_thread_regions_default_set (const struct pbl_mpu_region *const *regions) |
| Set the regions of threads that do not specify their own. | |
| static void * | pbl_thread_tls_get (const struct pbl_thread *t, unsigned int slot) |
| Read a thread-local pointer slot. | |
| static void | pbl_thread_tls_set (struct pbl_thread *t, unsigned int slot, void *v) |
| Write a thread-local pointer slot. | |
| void | pbl_thread_stack_overflow (struct pbl_thread *t, const char *name) |
| Handle a thread that overran its stack. | |
Thread creation, lifecycle and per-thread state.
Threads are scheduled by fixed priority, highest first; threads of equal priority round-robin on every tick and on pbl_thread_yield(). The thread struct and its stack are owned by the caller and must outlive the thread. Returning from the entry function ends the thread, after which the struct may be reused for a new one.
| struct pbl_thread_attr |
| Data Fields | ||
|---|---|---|
| void * | arg | Argument passed to entry. |
| pbl_thread_entry_t | entry | Entry function. |
| const char * | name | Name, truncated to PBL_THREAD_NAME_LEN - 1 characters. |
| pbl_prio_t | prio | Priority, PBL_PRIO_IDLE to PBL_PRIO_MAX. |
| bool | privileged |
Run in privileged mode; unprivileged threads are confined by the MPU. Without |
| const struct pbl_mpu_region * | regions[PBL_THREAD_MAX_MEM_REGIONS] |
MPU regions switched in with the thread, which only need to be valid during pbl_thread_create(). NULL entries take the default region. |
| void * | stack |
Lowest address of the stack buffer, aligned to its guard size; the caller owns the memory. The guard takes the bottom of it. |
| size_t | stack_size | Stack buffer size in bytes, guard included; the rest must be at least 128. |
| void * | syscall_stack |
Privileged stack the thread's syscalls run on, or NULL to run them on its own stack. Lowest address of the buffer, aligned to |
| size_t | syscall_stack_size | Size of the syscall_stack buffer in bytes, guard included. |
| uintptr_t | user_end | End of the thread's syscall-accessible memory. |
| bool | user_stack |
The thread only uses stack unprivileged once it has started, with nothing it can write below the stack, so it takes the smaller CONFIG_KERNEL_USER_STACK_GUARD_SIZE guard. |
| uintptr_t | user_start |
Memory the thread's syscalls may read and write, [user_start, user_end); empty for none. The thread's stack must sit at its bottom. |
| struct pbl_work_pool * | work_pool |
Slots for the thread's calls to the background system work queue, which it waits for when they are all taken, or NULL to share the system's. Keeps a thread that floods the queue, such as an app's, from taking the slots the system needs. |
| struct pbl_thread |
Thread object.
Caller-owned; set up by pbl_thread_create(). Read fields through the accessor functions.
| Data Fields | ||
|---|---|---|
| struct pbl_thread_backend | backend | Backend state; first, the arch code relies on its offset. |
| uint32_t | id | Unique per creation, never 0. |
| char | name[PBL_THREAD_NAME_LEN] | NUL-terminated name. |
| bool | own_regions | Created with regions of its own, so the defaults leave it alone. |
| pbl_prio_t | prio | Effective priority, including any boost inherited through a mutex. |
| bool | privileged | Runs in privileged mode. |
| void * | stack | Lowest address of the usable stack, above the guard. |
| size_t | stack_guard_size | Size in bytes of the guard below stack. |
| size_t | stack_size | Usable stack size in bytes. |
| void * | syscall_stack | Privileged syscall stack, or NULL. |
| size_t | syscall_stack_size | Size of the syscall stack in bytes. |
| void * | tls[CONFIG_KERNEL_THREAD_TLS_SLOTS] | Thread-local pointer slots, see pbl_thread_tls_get(). |
| uintptr_t | user_end | End of the syscall-accessible memory. |
| uintptr_t | user_start | Start of the syscall-accessible memory. |
| struct pbl_work_pool * | work_pool | Slots for its system work queue calls, see pbl_thread_attr. |
| #define PBL_THREAD_MAX_MEM_REGIONS 2 |
Number of MPU regions a thread can bring, on top of its stack guards.
| #define PBL_THREAD_NAME_LEN 16 |
Size of a thread name, including the terminating NUL.
| #define PBL_THREAD_STACK_DEFINE | ( | name, | |
| size | |||
| ) |
Define a thread stack, with room for its guard.
Expands to a static array. Pass it and its sizeof to pbl_thread_create() through pbl_thread_attr.
| name | Name of the stack array. |
| size | Usable stack size in bytes. |
| typedef void(* pbl_thread_entry_t) (void *arg) |
Thread entry function.
| arg | Argument given in pbl_thread_attr::arg. |
| enum pbl_thread_state |
Thread state.
| Enumerator | |
|---|---|
| PBL_THREAD_READY | Runnable, waiting for the CPU. |
| PBL_THREAD_RUNNING | Currently executing. |
| PBL_THREAD_BLOCKED | Waiting on an object or sleeping. |
| PBL_THREAD_SUSPENDED | Stopped by pbl_thread_suspend() until pbl_thread_resume(). |
| PBL_THREAD_DEAD | Ended or aborted; the struct may be reused. |
| void pbl_thread_abort | ( | struct pbl_thread * | t | ) |
End a thread.
Mutexes it holds are not released.
| t | Thread to end, or NULL for the calling thread, in which case this does not return. |
| int pbl_thread_create | ( | struct pbl_thread * | t, |
| const struct pbl_thread_attr * | attr | ||
| ) |
Create and start a thread.
The stack is filled with a pattern for high-water tracking. The new thread runs as soon as it is the highest priority runnable thread, possibly before this call returns. Returning from the entry function ends the thread. Asserts if t still holds a live thread.
| [out] | t | Thread object, caller-owned. |
| attr | Creation attributes; only read during the call. |
| struct pbl_thread * pbl_thread_current | ( | void | ) |
Get the calling thread.
Callable from unprivileged code.
|
inlinestatic |
Get the creation ID of a thread.
Distinguishes successive threads created in the same struct.
| t | Thread. |
References pbl_thread::id.
| struct pbl_thread * pbl_thread_idle | ( | void | ) |
Get the kernel's idle thread.
|
inlinestatic |
Get the name of a thread.
| t | Thread. |
t. References pbl_thread::name.
| pbl_prio_t pbl_thread_prio_get | ( | const struct pbl_thread * | t | ) |
Get the base priority of a thread.
| t | Thread. |
| void pbl_thread_prio_set | ( | struct pbl_thread * | t, |
| pbl_prio_t | prio | ||
| ) |
Change the base priority of a thread.
A priority boost inherited through a mutex is kept until the mutex is released.
| t | Thread. |
| prio | New priority, at most PBL_PRIO_MAX. |
| void pbl_thread_regions_default_set | ( | const struct pbl_mpu_region *const * | regions | ) |
Set the regions of threads that do not specify their own.
Threads that already exist get them too, the caller when it is next switched in.
| regions | Array of PBL_THREAD_MAX_MEM_REGIONS regions, which must stay valid; NULL entries leave the slot empty. |
| void pbl_thread_resume | ( | struct pbl_thread * | t | ) |
Make a suspended thread runnable again.
Has no effect if t is not suspended.
| t | Thread to resume. |
| void pbl_thread_sleep | ( | pbl_timeout_t | timeout | ) |
Block the calling thread for a while.
| timeout | Time to sleep; PBL_NO_WAIT yields instead. |
| void pbl_thread_stack_overflow | ( | struct pbl_thread * | t, |
| const char * | name | ||
| ) |
Handle a thread that overran its stack.
Implemented by the application.
| t | Thread that overflowed. |
| name | Its name. |
| enum pbl_thread_state pbl_thread_state | ( | const struct pbl_thread * | t | ) |
Get the state of a thread.
| t | Thread. |
| void pbl_thread_suspend | ( | struct pbl_thread * | t | ) |
Stop scheduling a thread until pbl_thread_resume().
A thread suspended while blocked sees the blocking call fail with -EINTR once resumed. Has no effect on a suspended or dead thread.
| t | Thread to suspend, or NULL for the calling thread. |
|
inlinestatic |
Read a thread-local pointer slot.
| t | Thread. |
| slot | Slot index, below CONFIG_KERNEL_THREAD_TLS_SLOTS. |
References pbl_thread::tls.
|
inlinestatic |
Write a thread-local pointer slot.
| t | Thread. |
| slot | Slot index, below CONFIG_KERNEL_THREAD_TLS_SLOTS. |
| v | Pointer to store. |
References pbl_thread::tls.
| void pbl_thread_yield | ( | void | ) |
Let other ready threads of the same priority run.