Create new threads
[L4 Thread Library API Reference]

Defines
#define	L4THREAD_INVALID_ID   (-1)
	Invalid thread id.
#define	L4THREAD_DEFAULT_PRIO   (-1)
	Use default priority.
#define	L4THREAD_INVALID_SP   (l4_addr_t)(-1)
	Invalid stack pointer.
#define	L4THREAD_DEFAULT_SIZE   (l4_size_t)(-1)
	Use default stack size.
#define	L4THREAD_CREATE_SYNC   0x00000001
	Wait for thread startup.
#define	L4THREAD_CREATE_ASYNC   0x00000002
	Don't wait for thread startup.
#define	L4THREAD_CREATE_PINNED   0x20000000
	Create stack on pinned memory.
#define	L4THREAD_CREATE_MAP   0x40000000
	Premap thread stack.
#define	L4THREAD_NAME_LEN   16
	max len of a thread name including ''
Typedefs
typedef l4_int32_t	l4thread_t
	Thread id type.
typedef L4_CV void(*	l4thread_fn_t )(void *data)
	Thread function type.
Functions
L4_CV l4thread_t	l4thread_create (l4thread_fn_t func, void *data, l4_uint32_t flags)
	Create new thread (standard short form).
L4_CV l4thread_t	l4thread_create_named (l4thread_fn_t func, const char *name, void *data, l4_uint32_t flags)
	Create new thread with name.
L4_CV l4thread_t	l4thread_create_long (l4thread_t thread, l4thread_fn_t func, const char *name, l4_addr_t stack_pointer, l4_size_t stack_size, l4_prio_t prio, void *data, l4_uint32_t flags)
	Create new thread (long form).
L4_CV int	l4thread_started (void *data)
	Send startup notification.
L4_CV void *	l4thread_startup_return (l4thread_t thread)
	Get startup return data.
L4_CV l4thread_t	l4thread_setup (l4_threadid_t l4_id, const char *name, l4_addr_t stack_low, l4_addr_t stack_high)
	Setup thread.

---

Typedef Documentation

typedef L4_CV void(* l4thread_fn_t)(void *data)

Thread function type.

Parameters:

data

Argument pointer, a user can specify a data argument on l4thread_create() / l4thread_create_long(), it is passed to the new thread in this data pointer.

---

Function Documentation

L4_CV l4thread_t l4thread_create	(	l4thread_fn_t	func,
		void *	data,
		l4_uint32_t	flags
	)

Create new thread (standard short form).

Parameters:

	func	thread function
	data	data argument which is passed to the new thread
	flags	create flags L4THREAD_CREATE_SYNC wait until the new thread is started, the new thread must confirm its startup by calling the l4thread_started() function. L4THREAD_CREATE_ASYNC return immediately after creating the thread, the new thread might not be completely initialized when l4thread_create returns L4THREAD_CREATE_PINNED use pinned (non-paged) memory to alloacte stack L4THREAD_CREATE_MAP immediately map stack memory L4THREAD_CREATE_SETUP use direct calls to the region mapper. Note: This flag is inteded to be used by the startup code of a task. It must not be used by application threads.

Returns:

Thread id on success (> 0), error code otherwise:

• -L4_ENOTHREAD no thread available

l4thread_create() creates a new thread using the default values for the stack size an priority of the new thread. The name of the thread will be generated from l4thread_basename by adding a dot (.) and the 0-padded id of the generated thread in hex notation.

When func returns, the created thread will exit.

L4_CV l4thread_t l4thread_create_named	(	l4thread_fn_t	func,
		const char *	name,
		void *	data,
		l4_uint32_t	flags
	)

Create new thread with name.

Parameters:

	func	thread function
	name	thread name
	data	data argument which is passed to the new thread
	flags	create flags L4THREAD_CREATE_SYNC wait until the new thread is started, the new thread must confirm its startup by calling the l4thread_started() function. L4THREAD_CREATE_ASYNC return immediately after creating the thread, the new thread might not be completely initialized when l4thread_create returns L4THREAD_CREATE_PINNED use pinned (non-paged) memory to alloacte stack L4THREAD_CREATE_MAP immediately map stack memory L4THREAD_CREATE_SETUP use direct calls to the region mapper. Note: This flag is inteded to be used by the startup code of a task. It must not be used by application threads.

Returns:

Thread id on success (> 0), error code otherwise:

• -L4_ENOTHREAD no thread available

l4thread_create() creates a new thread using the default values for the stack size and priority of the new thread.

When func returns, the created thread will exit.

L4_CV l4thread_t l4thread_create_long	(	l4thread_t	thread,
		l4thread_fn_t	func,
		const char *	name,
		l4_addr_t	stack_pointer,
		l4_size_t	stack_size,
		l4_prio_t	prio,
		void *	data,
		l4_uint32_t	flags
	)

Create new thread (long form).

Parameters:

	thread	thread id of the new thread, if set to L4THREAD_INVALID_ID, l4thread_create_long will choose an unused thread.
	name	name of the thread. If 0, a name will be generated. If starting with ".", will be padded to basename. Otherwise contents will be copied.
	func	thread function
	name	name of the thread. If 0, a name will be generated. If starting with ".", will be padded to basename. Otherwise contents will be copied. Additionally, one "%d" or "%x" in the string is substituted by sprintf, withh the thread-id as one argument.
	stack_pointer	stack pointer, if set to L4THREAD_INVALID_SP, a stack will be allocated
	stack_size	size of the stack (bytes), if set to L4THREAD_DEFAULT_SIZE the default size will be used Note: if a stack pointer is specified, a valid stack size must be given.
	prio	L4 priority of the thread, if set to L4THREAD_DEFAULT_PRIO, the default priority will be used.
	data	data argument which is passed to the new thread
	flags	create flags L4THREAD_CREATE_SYNC wait until the new thread is started, the new thread must confirm its startup by calling the l4thread_started() function. L4THREAD_CREATE_ASYNC return immediately after creating the thread, the new thread might not be completely initialized when l4thread_create_long returns L4THREAD_CREATE_PINNED use pinned (non-paged) memory to alloacte stack L4THREAD_CREATE_MAP immediately map stack memory L4THREAD_CREATE_SETUP use direct calls to the region mapper. Note: This flag is inteded to be used by the startup code of a task. It must not be used by application threads.

Returns:

Thread id on success (> 0), error code otherwise:

• -L4_EINVAL invalid argument
• -L4_EUSED thread already used
• -L4_ENOTHREAD no thread available
• -L4_ENOMEM out of memory allocating stack
• -L4_ENOMAP no area found to map stack

When func returns, the created thread will exit.

L4_CV int l4thread_started

(

void *

data

)

Send startup notification.

Parameters:

data

Startup return data, it is stored internally and can be read at any time using l4thread_startup_return().

Returns:

0 on success, error code otherwise:

• -L4_EIPC IPC error sending startup notification

Send startup notification to parent thread. This function must be used to notify the parent thread about the startup of a child thread if the L4THREAD_CREATE_SYNC flag was set in l4thread_create() / l4thread_create_long().

L4_CV void* l4thread_startup_return

(

l4thread_t

thread

)

Get startup return data.

Parameters:

thread

Thread id

Returns:

Startup data (set with l4thread_started()), NULL if invalid thread id

L4_CV l4thread_t l4thread_setup	(	l4_threadid_t	l4_id,
		const char *	name,
		l4_addr_t	stack_low,
		l4_addr_t	stack_high
	)

Setup thread.

Parameters:

	l4_id	L4 thread id of the thread
	name	name of the thread. If 0, a name will be generated. If starting with ".", will be padded to basename. Otherwise contents will be copied. Additionally, one "%d" or "%x" in the string is substituted by
	stack_low	stack start address
	stack_high	stack end address

Returns:

Thread id on success (> 0), error code otherwise:

• -L4_EINVAL invalid L4 thread id
• -L4_EUSED thread specified by l4_id already used by the thread lib, or error registering the new name

Setup thread descriptor for thread l4_id. It must be used to register threads which are not created by the thread library.