Threads implementation. More...

Macros
#define	MAX_THREADS 256
	Maximum number of threads in a domain, used to size VM region for thread structures.

#define	STACK_ALIGNMENT (sizeof(uint64_t) * 2)
	16-byte alignment required for x86-64

Functions
void	thread_enqueue (struct thread thread, struct thread *queue)
	Enqueue a thread in the given queue. More...

struct thread *	thread_dequeue (struct thread **queue)
	Dequeue the first thread on the given queue. More...

void	thread_remove_from_queue (struct thread *queue, struct thread thread)
	Remove a specific thread from a queue. More...

void	thread_run_disabled (dispatcher_handle_t handle)
	Schedule and run the next active thread, or yield the dispatcher. More...

struct thread *	thread_create_unrunnable (thread_func_t start_func, void *arg, size_t stacksize)
	Creates a new thread that will not be runnable. More...

struct thread *	thread_create_varstack (thread_func_t start_func, void *arg, size_t stacksize)
	Creates a new thread, and makes it runnable. More...

struct thread *	thread_create (thread_func_t start_func, void *arg)
	Creates a new thread, and makes it runnable. More...

errval_t	thread_join (struct thread thread, int retval)
	Wait for termination of another thread. More...

errval_t	thread_detach (struct thread *thread)
	Detach a thread. Free its state when it terminates. More...

struct thread *	thread_self (void)
	Returns the thread pointer to the currently-running thread.

void	thread_set_local_trigger (struct waitset_chanstate *trigger)
	Set/get a local trigger for currently processed event channel.

void	thread_store_recv_slot (struct capref recv_slot)
	Store receive slot provided by rpc in thread state.

void	thread_set_status (int status)
	Set a thread's exit status. More...

void	thread_yield (void)
	Yield the calling thread. More...

void	thread_yield_dispatcher (struct capref endpoint)
	Yield both the calling thread, and the dispatcher to another domain. More...

void	thread_exit (int status)
	Terminate the calling thread.

void *	thread_block_and_release_spinlock_disabled (dispatcher_handle_t handle, struct thread *queue, spinlock_t spinlock)
	Block the caller, and optionally release a spinlock, while disabled. More...

void *	thread_block_disabled (dispatcher_handle_t disp, struct thread **queue)
	Block the calling thread, while disabled. More...

void *	thread_block (struct thread **queue)
	Block the calling thread, while enabled. More...

struct thread *	thread_unblock_one_disabled (dispatcher_handle_t handle, struct thread *queue, void reason)
	Unblock a single thread from a given queue, while disabled. More...

struct thread *	thread_unblock_one (struct thread *queue, void reason)
	Unblock a single thread from a given queue, while enabled. More...

struct thread *	thread_unblock_all_disabled (dispatcher_handle_t handle, struct thread *queue, void reason)
	Unblock all threads on a given queue, while disabled. More...

void	thread_init_disabled (dispatcher_handle_t handle, bool init_domain)
	Initialise thread system while still disabled. More...

void	thread_init_remote (dispatcher_handle_t handle, struct thread *thread)
	Called on the remote core when spanning a domain across cores. More...

void	threads_prepare_to_span (dispatcher_handle_t newdh)
	Prepare to span the current domain. More...

void	thread_pause_and_capture_state (struct thread thread, arch_registers_state_t ret_regs, arch_registers_fpu_state_t *ret_fpuregs)
	Pause (suspend execution of) the given thread, and optionally capture its register state. More...

void	thread_pause (struct thread *thread)
	Pause (suspend execution of) the given thread. More...

void	thread_resume (struct thread *thread)
	Resume execution of a thread previously suspended by thread_pause()

void	thread_set_tls (void *p)
	Set old-style thread-local storage pointer. More...

void *	thread_get_tls (void)
	Return old-style thread-local storage pointer. More...

errval_t	thread_set_exception_handler (exception_handler_fn newhandler, exception_handler_fn oldhandler, void new_stack_base, void new_stack_top, void old_stack_base, void *old_stack_top)
	Set the exception handler function for the current thread. Optionally also change its stack, and return the old values. More...

void	thread_deliver_exception_disabled (dispatcher_handle_t handle, enum exception_type type, int subtype, void addr, arch_registers_state_t regs)
	Deliver an exception to the current thread, and resume. More...

Detailed Description

Threads implementation.

Function Documentation

void* thread_block ( struct thread ** queue )

Block the calling thread, while enabled.

The caller is unconditionally blocked, and placed into the given queue pending a call that will unblock it. This function must only be called while enabled.

Parameters

queue Queue of threads in which to place caller

Returns: Argument passed to thread_unblock, when unblocked

void* thread_block_and_release_spinlock_disabled	(	dispatcher_handle_t	handle,
		struct thread **	queue,
		spinlock_t *	spinlock
	)

Block the caller, and optionally release a spinlock, while disabled.

The caller is unconditionally blocked, and placed into the given queue pending a call that will unblock it. After manipulating the queues, and before switching threds, the given spinlock, if specified, is unlocked. This function must only be called while disabled.

This function is intended for use by multi-processor thread synchronisation functions.

Parameters

disp	Dispatcher pointer
queue	(Optional) Queue of threads in which to place caller
spinlock	(Optional) pointer to spinlock

Returns: Argument passed to thread_unblock, when unblocked

void* thread_block_disabled	(	dispatcher_handle_t	disp,
		struct thread **	queue
	)

Block the calling thread, while disabled.

The caller is unconditionally blocked, and placed into the given queue pending a call that will unblock it. This function must only be called while disabled.

Parameters

disp	Dispatcher pointer
queue	Queue of threads in which to place caller

Returns: Argument passed to thread_unblock, when unblocked

struct thread* thread_create	(	thread_func_t	start_func,
		void *	arg
	)

Creates a new thread, and makes it runnable.

Parameters

start_func	Function to run on the new thread
arg	Argument to pass to function

Returns: Thread pointer on success, NULL on failure

struct thread* thread_create_unrunnable	(	thread_func_t	start_func,
		void *	arg,
		size_t	stacksize
	)

Creates a new thread that will not be runnable.

Parameters

start_func	Function to run on the new thread
arg	Argument to pass to function
stacksize	Size of stack, in bytes

Returns: Thread pointer on success, NULL on failure

struct thread* thread_create_varstack	(	thread_func_t	start_func,
		void *	arg,
		size_t	stacksize
	)

Creates a new thread, and makes it runnable.

Parameters

start_func	Function to run on the new thread
arg	Argument to pass to function
stacksize	Size of stack, in bytes

Returns: Thread pointer on success, NULL on failure

void thread_deliver_exception_disabled	(	dispatcher_handle_t	handle,
		enum exception_type	type,
		int	subtype,
		void *	addr,
		arch_registers_state_t *	regs
	)

Deliver an exception to the current thread, and resume.

This may only be called from the dispatcher (on its stack and while disabled!).

Parameters

handle	Dispatcher handle
type	Exception type
subtype	Exception subtype
addr	Exception address
regs	CPU register state at time of exception

struct thread* thread_dequeue ( struct thread ** queue )

Dequeue the first thread on the given queue.

For safety, should only happen while disabled.

Returns: Pointer to thread that was dequeued

errval_t thread_detach ( struct thread * thread )

Detach a thread. Free its state when it terminates.

Parameters

thread Pointer to thread to detach

Returns: SYS_ERR_OK on success.

void thread_enqueue	(	struct thread *	thread,
		struct thread **	queue
	)

Enqueue a thread in the given queue.

For safety, should only happen while disabled.

void* thread_get_tls ( void )

Return old-style thread-local storage pointer.

Returns: User's pointer, previously passed to thread_set_tls()

void thread_init_disabled	(	dispatcher_handle_t	handle,
		bool	init_domain
	)

Initialise thread system while still disabled.

This function initialises the thread system while the dispatcher is still disabled, before enabling the dispatcher, running the general initialisation code, and calling main().

Parameters

disp	Dispatcher pointer
init_domain	True if we are a bootstrap domain

void thread_init_remote	(	dispatcher_handle_t	handle,
		struct thread *	thread
	)

Called on the remote core when spanning a domain across cores.

Runs the provided thread after enqueuing it and enabling the dispatcher

errval_t thread_join	(	struct thread *	thread,
		int *	retval
	)

Wait for termination of another thread.

Parameters

thread	Pointer to thread to wait for
retval	Pointer to variable to hold return value of thread, or NULL

Returns: SYS_ERR_OK on success, error code on error.

void thread_pause ( struct thread * thread )

Pause (suspend execution of) the given thread.

The thread will not be run, until a subsequent call to thread_resume()

void thread_pause_and_capture_state	(	struct thread *	thread,
		arch_registers_state_t **	ret_regs,
		arch_registers_fpu_state_t **	ret_fpuregs
	)

Pause (suspend execution of) the given thread, and optionally capture its register state.

The thread will not be run, until a subsequent call to thread_resume()

void thread_remove_from_queue	(	struct thread **	queue,
		struct thread *	thread
	)

Remove a specific thread from a queue.

Does not check that the thread is in the given queue, which it must be. For safety, should only happen while disabled.

void thread_run_disabled ( dispatcher_handle_t handle )

Schedule and run the next active thread, or yield the dispatcher.

This may only be called from the dispatcher (on its stack and while disabled!).

Parameters

disp	Dispatcher pointer

errval_t thread_set_exception_handler	(	exception_handler_fn	newhandler,
		exception_handler_fn *	oldhandler,
		void *	new_stack_base,
		void *	new_stack_top,
		void **	old_stack_base,
		void **	old_stack_top
	)

Set the exception handler function for the current thread. Optionally also change its stack, and return the old values.

Parameters

newhandler	New exception handler. Pass NULL to disable an existing handler.
oldhandler	If non-NULL, returns previous exception handler
new_stack_base	If non-NULL, sets a new exception handler stack (base)
new_stack_top	If non-NULL, sets a new exception handler stack (top)
old_stack_base	If non-NULL, returns previous stack base
old_stack_top	If non-NULL, returns previous stack top

void thread_set_status ( int status )

Set a thread's exit status.

Parameters

status The status.

void thread_set_tls ( void * p )

Set old-style thread-local storage pointer.

Parameters

p	User's pointer

struct thread* thread_unblock_all_disabled	(	dispatcher_handle_t	handle,
		struct thread **	queue,
		void *	reason
	)

Unblock all threads on a given queue, while disabled.

All threads on the queue of blocked threads are awoken. This function must only be called while disabled.

Parameters

disp	Dispatcher pointer
queue	Queue of threads to unblock
reason	Value to be returned from thread_block()

Returns: Pointer to list of threads to be woken on a foreign dispatcher

struct thread* thread_unblock_one	(	struct thread **	queue,
		void *	reason
	)

Unblock a single thread from a given queue, while enabled.

A single thread is removed from the queue of blocked threads, and awoken. This function must only be called while enabled.

Parameters

queue	Queue of threads from which to unblock one
reason	Value to be returned from thread_block()

Returns: Pointer to thread to be woken on a foreign dispatcher

struct thread* thread_unblock_one_disabled	(	dispatcher_handle_t	handle,
		struct thread **	queue,
		void *	reason
	)

Unblock a single thread from a given queue, while disabled.

A single thread is removed from the queue of blocked threads, and awoken. This function must only be called while disabled.

Parameters

disp	Dispatcher pointer
queue	Queue of threads from which to unblock one
reason	Value to be returned from thread_block()

Returns: Pointer to thread to be woken on a foreign dispatcher

void thread_yield ( void )

Yield the calling thread.

Switches to the next runnable thread in this dispatcher, or if none is available, yields the dispatcher.

void thread_yield_dispatcher ( struct capref endpoint )

Yield both the calling thread, and the dispatcher to another domain.

Parameters

endpoint Endpoint cap to which we wish to yield, or #CAP_NULL for an undirected yield

Yields the dispatcher, optionally to another specified dispatcher.

void threads_prepare_to_span ( dispatcher_handle_t newdh )

Prepare to span the current domain.

This is a kludge. It is called from domain.c when creating a new dispatcher, and is responsible for pre-allocating all the storage that might be needed for thread metadata in the slab allocator. It can go away once we sanely manage the vspace across multiple dispatchers in a domain.

Macros

Functions

Detailed Description

Function Documentation