NAME | SYNOPSIS | DESCRIPTION | WARNINGS | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO
#include <exec/chExec.h>int threadCreate(KnCap *actorcap, KnThreadLid *threadli, KnThreadStatus status, void *schedparam, void *startinfo);
threadCreate creates a new thread in the actor the capability of which 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 a 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 types of startinfo structures: KnDefaultStartInfo_f and KnStartInfo
These structures are machine-dependent (i.e. may contain machine-dependent fields).
For most conventional processors (eg. x86/Pentium, SPARC, etc.), 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 kernel of the supervisor stack size required by the thread. If dsSystemStackSize is equal to K_DEFAULT_STACK_SIZE, the default supervisor stack size will be used.
The dsEntry and dsUserStackPointer fields specify 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 the values of which may be directly provided upon thread creation. Other register values may be initialized by creating a thread in K_INACTIVE state and calling threadContext before resuming it (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 kernel calls. In the latter case, the dsUserStackPointer field is ignored.
Similarly, the KnStartInfo contains the following fields:
KnStartInfoType dsType ; unsigned dsSystemStackSize ; KnPc dsEntry ; void* dsUserStackPointer ; KnThreadPrivilege dsPrivilege ; unsigned int dsSoftReg ; void* dsSystemStackTop ; |
The dsType field must be K_START_INFO possibly or'ed with K_START_INFO_SOFTREG and/or K_START_INFO_SYS_STACK bits.
The meaning of dsSystemStackSize, dsEntry, dsUserStackPointer and dsPrivilege fields remains the same as in KnDefaultStartInfo_f structure.
The value dsSoftReg field is only meaningful if K_START_INFO_SOFTREG bit is set in the dsType filed. 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 gets this argument using threadLoadR(2K).
The value dsSystemStackTop field is only meaningful if K_START_INFO_SYS_STACK bit is set in the dsType field. It specifies the starting address of the memory area to be used as the created thread's system stack (while dsSystemStackSize gives, as usually, the size in bytes of this area).
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 are supported for compatibility reasons.
MEM_PROTECTED for ARM and i386 as well as MEM_VIRTUAL on i386 and ppc60x implementations do not support supervisor stacks greater than a tunable which is defined per platform. To get the default value of the system stack size, it is necessary to invoke the configuration tool (configurator).
The supervisor stack must be always allocated by a supervisor thread only. Consequently only supervisor threads are allowed to change the system stack.
Upon successful completion, K_OK is returned. Otherwise, a negative error code is returned.
actorcap is an inconsistent actor capability.
actorcap does not specify a reachable actor.
Some of the provided data are outside the current actor's address space.
The current thread is not allowed to create a SUPERVISOR thread.
schedparam requires a non-supported scheduling policy.
The system is out of resources.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | DESCRIPTION | WARNINGS | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO