ChorusOS man pages section 2K: Kernel System Calls

threadCreate(2K)

NAME

threadCreate- create a thread

SYNOPSIS

#include <exec/chExec.h>

actorcap

threadli

status

schedparam

startinfo

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

DESCRIPTION

threadCreate() creates a new thread in an actor whose capability is given by actorcap. If actorcap is K_MYACTOR, the thread is created within the current actor.

threadCreate() returns the local identifier of the new thread in threadli.

status is the thread's initial status. If status is K_INACTIVE, the thread will not execute until it is explicitly started using threadActivate(2K). If status is K_ACTIVE, the thread can run immediately (assuming that the actor is in the ACTIVE state (see actorStart(2K)).

schedparam points to a descriptor of thread scheduling attributes (see threadScheduler(2K). If schedparm is 0, the thread inherits the scheduling attributes of the parent thread.

startinfo points to a structure specifying the initial state of the new thread. The current implementation supports two startinfostructures: KnDefaultStartInfo_f and KnStartInfo.

These structures are machine-dependent (may contain machine-dependent fields).

For most conventional processors (such as SPARC and Intel architectures), KnDefaultStartInfo_f contains the following fields:

KnStartInfoType   dsType ;
unsigned          dsSystemStackSize ;
KnPc              dsEntry ;
void*             dsUserStackPointer ;
KnThreadPrivilege dsPrivilege ;

The dsType field must be set equal to K_DEFAULT_START_INFO.

The dsSystemStackSize field provides a hint to the microkernel of the supervisor stack size required by the thread. If dsSystemStackSize is equal to K_DEFAULT_STACK_SIZE, the default supervisor stack size is used.

The dsEntry and dsUserStackPointer fields specify the initial values of the program counter and the user stack pointer of the thread when activated. The program counter and the stack pointer are the only machine registers whose values may be directly provided upon thread creation. Other register values may be initialized by creating a thread in K_INACTIVE state and calling threadContext(2K) before resuming (see threadActivate(2K)). Otherwise, these registers are initialized with arbitrary values.

If the dsPrivilege field is equal to K_USERTHREAD, the thread is activated as a user mode thread with user privileges. If the dsPrivilege field is equal to K_SUPTHREAD, the thread is activated at supervisor privilege level and has access to restricted machine instructions and microkernel calls. In the latter case, the dsUserStackPointer field is ignored.

Similarly, KnStartInfo contains the following fields:

KnStartInfoType   dsType ;
unsigned          dsSystemStackSize ;
KnPc              dsEntry ;
void*             dsUserStackPointer ;
KnThreadPrivilege dsPrivilege ;
unsigned int	  dsSoftReg ;
void*             dsSystemStackTop ;
KnFpuCtx*              dsFpuCtx

The dsType field must be K_START_INFO possibly OR'ed with K_START_INFO_SOFTREG or K_START_INFO_SYS_STACK bits.

The meaning of the dsSystemStackSize, dsEntry, dsUserStackPointer and dsPrivilege fields remains the same as for the KnDefaultStartInfo_f structure.

The value of the dsSoftReg field is only meaningful if the K_START_INFO_SOFTREG bit is set in the dsType field. It specifies the initial value of the thread's software register corresponding to its privilege level. This is used to pass an argument to the created thread, which obtains the argument using threadLoadR(2K).

The value of the dsSystemStackTop field is only meaningful if the K_START_INFO_SYS_STACK bit is set in the dsType field. It specifies the start address of the memory area to be used as the created thread's system stack (while dsSystemStackSize gives the size, in bytes, of this area).

The value of the dsFpuCtx is only meaningful if the dsType field contains the K_START_INFO_FPU_CTX flag. It specifies the initial FPU context for this thread.

WARNINGS

Note that in the current version, K_SUSPENDED is equivalent to K_INACTIVE and threadResume(2K) is equivalent to threadActivate(2K). K_SUSPENDED and threadResume(2K) are supported for compatibility reasons.

MEM_PROTECTED and MEM_VIRTUAL on Intel Architecture and MEM_VIRTUAL for PowerPC implementations do not support supervisor stacks greater than a tunable which is defined per platform. To obtain the default value of the system stack size, use the configuration tool (configurator(1CC)).

The supervisor stack must always be allocated by a supervisor thread only. Consequently, only supervisor threads are allowed to change the system stack.

RETURN VALUE

On successful completion, K_OK is returned. Otherwise, a negative error code is returned.

ERRORS

K_EINVAL: actorcap is an inconsistent actor capability.
K_EUNKNOWN: actorcap does not specify a reachable actor.
K_EFAULT: Some of the data provided are outside the current actor's address space.
K_EPRIV: The current thread is not allowed to create a SUPERVISOR thread.
K_ENOTIMP: schedparam requires a non-supported scheduling policy.
K_ENOMEM: The system is out of resources.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving