PebbleOS v4.47.0-512-g5285d4236
Loading...
Searching...
No Matches
Threads

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.
 

Detailed Description

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.

PBL_THREAD_STACK_DEFINE(s_worker_stack, 1024);
static struct pbl_thread s_worker;
static void prv_worker(void *arg) {
for (;;) {
do_work(arg);
}
}
void worker_start(void) {
const struct pbl_thread_attr attr = {
.name = "Worker",
.entry = prv_worker,
.prio = 2,
.privileged = true,
.stack = s_worker_stack,
.stack_size = sizeof(s_worker_stack),
};
pbl_thread_create(&s_worker, &attr);
}
const char * name
Name, truncated to PBL_THREAD_NAME_LEN - 1 characters.
Definition thread.h:77
Definition thread.h:75
Thread object.
Definition thread.h:136
int pbl_thread_create(struct pbl_thread *t, const struct pbl_thread_attr *attr)
Create and start a thread.
void pbl_thread_sleep(pbl_timeout_t timeout)
Block the calling thread for a while.
#define PBL_THREAD_STACK_DEFINE(name, size)
Define a thread stack, with room for its guard.
Definition thread.h:180
#define PBL_MSEC(ms)
Timeout in milliseconds, rounded down to whole ticks.
Definition types.h:61

Data Structure Documentation

◆ pbl_thread_attr

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 CONFIG_USERSPACE every thread runs privileged.

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 CONFIG_KERNEL_STACK_GUARD_SIZE; the guard takes the bottom of it.

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.

◆ pbl_thread

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.

Macro Definition Documentation

◆ PBL_THREAD_MAX_MEM_REGIONS

#define PBL_THREAD_MAX_MEM_REGIONS   2

Number of MPU regions a thread can bring, on top of its stack guards.

◆ PBL_THREAD_NAME_LEN

#define PBL_THREAD_NAME_LEN   16

Size of a thread name, including the terminating NUL.

◆ PBL_THREAD_STACK_DEFINE

#define PBL_THREAD_STACK_DEFINE (   name,
  size 
)
Value:
static uint8_t name[(size) + CONFIG_KERNEL_STACK_GUARD_SIZE] PBL_ALIGNED( \
CONFIG_KERNEL_STACK_ALIGN)
#define PBL_ALIGNED(bytes)
Align the symbol or type.
Definition compiler.h:87

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.

Parameters
nameName of the stack array.
sizeUsable stack size in bytes.

Typedef Documentation

◆ pbl_thread_entry_t

typedef void(* pbl_thread_entry_t) (void *arg)

Thread entry function.

Parameters
argArgument given in pbl_thread_attr::arg.

Enumeration Type Documentation

◆ 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.

Function Documentation

◆ pbl_thread_abort()

void pbl_thread_abort ( struct pbl_thread *  t)

End a thread.

Mutexes it holds are not released.

Parameters
tThread to end, or NULL for the calling thread, in which case this does not return.

◆ pbl_thread_create()

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.

Parameters
[out]tThread object, caller-owned.
attrCreation attributes; only read during the call.
Returns
0.

◆ pbl_thread_current()

struct pbl_thread * pbl_thread_current ( void  )

Get the calling thread.

Callable from unprivileged code.

Returns
The running thread, or the interrupted thread when called from an ISR.

◆ pbl_thread_id()

static uint32_t pbl_thread_id ( const struct pbl_thread *  t)
inlinestatic

Get the creation ID of a thread.

Distinguishes successive threads created in the same struct.

Parameters
tThread.
Returns
ID, unique per creation and never 0.

References pbl_thread::id.

◆ pbl_thread_idle()

struct pbl_thread * pbl_thread_idle ( void  )

Get the kernel's idle thread.

Returns
The idle thread, which runs at PBL_PRIO_IDLE when nothing else is runnable.

◆ pbl_thread_name()

static const char * pbl_thread_name ( const struct pbl_thread *  t)
inlinestatic

Get the name of a thread.

Parameters
tThread.
Returns
NUL-terminated name, owned by t.

References pbl_thread::name.

◆ pbl_thread_prio_get()

pbl_prio_t pbl_thread_prio_get ( const struct pbl_thread *  t)

Get the base priority of a thread.

Parameters
tThread.
Returns
Priority set at creation or by pbl_thread_prio_set(), without inherited boosts.

◆ pbl_thread_prio_set()

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.

Parameters
tThread.
prioNew priority, at most PBL_PRIO_MAX.

◆ pbl_thread_regions_default_set()

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.

Parameters
regionsArray of PBL_THREAD_MAX_MEM_REGIONS regions, which must stay valid; NULL entries leave the slot empty.

◆ pbl_thread_resume()

void pbl_thread_resume ( struct pbl_thread *  t)

Make a suspended thread runnable again.

Has no effect if t is not suspended.

Parameters
tThread to resume.

◆ pbl_thread_sleep()

void pbl_thread_sleep ( pbl_timeout_t  timeout)

Block the calling thread for a while.

Parameters
timeoutTime to sleep; PBL_NO_WAIT yields instead.

◆ pbl_thread_stack_overflow()

void pbl_thread_stack_overflow ( struct pbl_thread *  t,
const char *  name 
)

Handle a thread that overran its stack.

Implemented by the application.

Parameters
tThread that overflowed.
nameIts name.

◆ pbl_thread_state()

enum pbl_thread_state pbl_thread_state ( const struct pbl_thread *  t)

Get the state of a thread.

Parameters
tThread.
Returns
Current state.

◆ pbl_thread_suspend()

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.

Parameters
tThread to suspend, or NULL for the calling thread.

◆ pbl_thread_tls_get()

static void * pbl_thread_tls_get ( const struct pbl_thread *  t,
unsigned int  slot 
)
inlinestatic

Read a thread-local pointer slot.

Parameters
tThread.
slotSlot index, below CONFIG_KERNEL_THREAD_TLS_SLOTS.
Returns
Stored pointer, NULL if never set.

References pbl_thread::tls.

◆ pbl_thread_tls_set()

static void pbl_thread_tls_set ( struct pbl_thread *  t,
unsigned int  slot,
void *  v 
)
inlinestatic

Write a thread-local pointer slot.

Parameters
tThread.
slotSlot index, below CONFIG_KERNEL_THREAD_TLS_SLOTS.
vPointer to store.

References pbl_thread::tls.

◆ pbl_thread_yield()

void pbl_thread_yield ( void  )

Let other ready threads of the same priority run.