Module sunrise_libuser::threads

Low-level api to create threads and start them.

This module defines the low-level representation of a thread, kind to pthread on Unix. You will want to abstract it in the libstd.

Threads on SunriseOS

The sunrise kernel provides only three syscalls of interest relative to threads:

• svcCreateThread : allocates kernel resources for a thread and returns a handle to it.
• svcStartThread : starts a thread created by svcCreateThread.
• svcExitThread : terminates the current thread.

Note that it is impossible to terminate another thread but our own.

The first thread of a process (referred later in this doc as "main thread") gets the handle to its own thread in one of its registers when it is started by the kernel.

TLS region

Every thread possesses a small memory region called Thread Local Storage region which the kernel allocates, and puts its address in a ro register so it can be accessed from the userspace.

There lives the IpcBuffer, and a userspace controlled pointer where the user can store a user-defined context. We use it to to keep a pointer to a ThreadContext (see below).

Threads in libuser

The main thread will always live for the entire life of the process. When its routine returns, it calls svcExitProcess and every other thread will be killed.

It can create other threads, which are represented by the Thread struct. A Thread detaches (read "leak") the associated thread when it is dropped, which means that there is no longer any handle to thread and no way to join on it.

This is analog to the way the libstd threads work.

Thread context

For every thread we create (and also for the main thread), we allocate a ThreadContext structure on the heap, which holds its stack, its thread handle so it will be able to use mutexes, the routine we want it to execute, and the argument to pass to it.

Thread entry point

We tell the kernel the entry of the thread is thread_trampoline. This function will set-up a valid environment for the routine (mainly handle ELF thread local variables), call the routine with its argument, and finally call svcExitThread when the routine has returned.

Structs

StackContext	Stack allocation informations
Thread	Libuser's representation of a thread.
ThreadContext	Structure holding the thread local context of a thread. Allocated at thread creation by the creator of the thread.

Constants

DEFAULT_STACK_SIZE

Default size of a thread's stack, in bytes.

Statics

MAIN_THREAD_CONTEXT

Context of the main thread. Instead of allocating it at startup, this one lives in the .data.

Functions

get_my_ipc_buffer	Get a pointer to this thread's IPCBuffer, from the TLS region pointed to by fs.
get_my_thread_context	Get a reference to this thread's ThreadContext, from the TLS region pointed to by fs.
get_my_tls_region	Get a pointer to this thread's TLS region pointed to by fs, translated to the flat-memory model.
init_main_thread	Initialisation of the main thread's thread local structures:
thread_trampoline	Small stub executed by every thread but the main thread when they start.