1 |
2 |
drasko |
.TH L4_THREAD_CONTROL 7 2009-11-02 "Codezero" "Codezero Programmer's Manual"
|
2 |
|
|
.SH NAME
|
3 |
|
|
.nf
|
4 |
|
|
.BR "l4_thread_control" " - create, destroy, suspend, resume, recycle and wait on threads."
|
5 |
|
|
|
6 |
|
|
.SH SYNOPSIS
|
7 |
|
|
.nf
|
8 |
|
|
.B #include
|
9 |
|
|
.B #include
|
10 |
|
|
|
11 |
|
|
.BI "int l4_thread_control(unsigned int " "action" ", struct task_ids *" "ids" ")"
|
12 |
|
|
|
13 |
|
|
|
14 |
|
|
.SH DESCRIPTION
|
15 |
|
|
.BR l4_thread_control()
|
16 |
|
|
system call manipulates threads in the system. Pagers may create, destroy, recycle, suspend and resume threads via this call. While Codezero Microkernel aims to provide dynamic privilege and resource management in the form of capabilities, this system call inherently assumes a hierarchical parent-child relationship between the caller and the target thread, such that the caller should be the pager of the targeted thread. See the
|
17 |
|
|
.B THREAD RELATIONSHIPS
|
18 |
|
|
subsection below for a detailed explanation of the matter.
|
19 |
|
|
.fi
|
20 |
|
|
|
21 |
|
|
.IR "ids " "field specifies the thread, address space, and thread group ids of the targeted thread. Below is the declaration for this structure:"
|
22 |
|
|
|
23 |
|
|
.nf
|
24 |
|
|
.TP
|
25 |
|
|
.BI "struct" " task_ids { "
|
26 |
|
|
.in 15
|
27 |
|
|
.BI "int " "tid" "; /* Fully qualified thread id */"
|
28 |
|
|
.BI "int " "spid" "; /* Address space id (local to container) */"
|
29 |
|
|
.BI "int " "tgid" "; /* Thread group id (local, defined by userspace protocol) */"
|
30 |
|
|
.ti 7
|
31 |
|
|
};
|
32 |
|
|
.ti 7
|
33 |
|
|
.TP
|
34 |
|
|
.fi
|
35 |
|
|
.I tid
|
36 |
|
|
argument may have different meanings for different thread control actions. For an existing thread, this argument specifies the thread on which the action is to be performed. On a thread creation request, this argument would specify the thread whose context is to be copied from for creating the new thread. See
|
37 |
|
|
.I actions
|
38 |
|
|
below for a more detailed explanation.
|
39 |
|
|
|
40 |
|
|
.TP
|
41 |
|
|
.fi
|
42 |
|
|
.I spid
|
43 |
|
|
field has meaning only on a
|
44 |
|
|
.B THREAD_CREATE
|
45 |
|
|
request, in conjunction with one of
|
46 |
|
|
.B TC_SHARE_SPACE,
|
47 |
|
|
.B TC_NEW_SPACE
|
48 |
|
|
or
|
49 |
|
|
.B TC_COPY_SPACE
|
50 |
|
|
flags
|
51 |
|
|
.TP
|
52 |
|
|
.fi
|
53 |
|
|
.I tgid
|
54 |
|
|
field is provided as an extra id slot for the thread. The pager of the thread may designate a group of threads to be in the same thread group, defining the group by a userspace protocol. This field has no meaning from the kernel's perspective, and may be removed in future releases.
|
55 |
|
|
|
56 |
|
|
.I action
|
57 |
|
|
field is the main action specifier where one of the following may be supplied as valid actions:
|
58 |
|
|
.TP
|
59 |
|
|
|
60 |
|
|
.TP
|
61 |
|
|
.B THREAD_CREATE
|
62 |
|
|
Creates a new thread in a new or existing space depending on the provided space flags.
|
63 |
|
|
.RI "A thread create request requires valid " "tid" " and " "spid" " fields in order to specify which thread context and address space to copy from or use."
|
64 |
|
|
Following are the action flags that are associated with a
|
65 |
|
|
.B THREAD_CREATE
|
66 |
|
|
request:
|
67 |
|
|
|
68 |
|
|
.in 14
|
69 |
|
|
.B TC_SHARE_UTCB
|
70 |
|
|
Sets the new thread's utcb as the creator's utcb. Threads may validly share UTCBs by making sure that they don't initiate IPC at the same time, or ensure synchronized access to UTCB fields.
|
71 |
|
|
|
72 |
|
|
.B TC_SHARE_GROUP
|
73 |
|
|
Sets the new thread's thread group id as the id specified by
|
74 |
|
|
.I tgid field.
|
75 |
|
|
|
76 |
|
|
.B TC_SHARE_SPACE
|
77 |
|
|
Places the new thread into the address space specified by
|
78 |
|
|
.IR "spid" ", and copies the thread context from thread specified by " "tid" " field. The thread represented by the " "tid " "argument is said to represent a "
|
79 |
|
|
.BR "parent " " relationship to the newly created thread."
|
80 |
|
|
|
81 |
|
|
.B TC_COPY_SPACE
|
82 |
|
|
Copies all page tables of the address space specified by
|
83 |
|
|
.I spid
|
84 |
|
|
to the new thread's newly created address space.
|
85 |
|
|
.RI "Also copies the thread context from thread specified by the " "tid " "field, who is said to represent a " "parent" " relationship to the newly created thread. This flag is particularly useful for implementing the"
|
86 |
|
|
.B POSIX fork()
|
87 |
|
|
system call.
|
88 |
|
|
|
89 |
|
|
.B TC_NEW_SPACE
|
90 |
|
|
Creates the new thread in a brand new address space.
|
91 |
|
|
.TP
|
92 |
|
|
.B THREAD_DESTROY
|
93 |
|
|
Destroys a thread, and its address space if the thread destroyed is the only thread left in that address space.
|
94 |
|
|
.TP
|
95 |
|
|
.B THREAD_SUSPEND
|
96 |
|
|
Suspends execution of a thread. The thread goes into a dormant state.
|
97 |
|
|
.TP
|
98 |
|
|
.B THREAD_RUN
|
99 |
|
|
Runs or resumes execution of a thread.
|
100 |
|
|
.TP
|
101 |
|
|
.B THREAD_RECYCLE
|
102 |
|
|
Clears all existing state of a thread, but does not deallocate the thread, leaving it dormant. The only information retained is the existing thread ids of the original thread. This is particularly useful for implementing the execve() POSIX system call.
|
103 |
|
|
.TP
|
104 |
|
|
.B THREAD_WAIT
|
105 |
|
|
Waits on a thread to exit, with exit status.
|
106 |
|
|
|
107 |
|
|
On a system setup where a pager is responsible for creating threads in separate address spaces and communicating with them via IPC, the children may send an exit IPC message to their pager. This way, a pager may synchronously receive exit status of a child in the form of IPC, and take action to destroy it as part of handling the IPC. However, on systems where the application is a multi-threaded, single address space application, a thread wait call provides a simple synchronous channel for the parent to wait on its child's exit status, without requiring any extra set up for IPC handling.
|
108 |
|
|
|
109 |
|
|
.ti 7
|
110 |
|
|
|
111 |
|
|
.in 7
|
112 |
|
|
.RB "See " "l4_getid" "(7) for more details on resource ids in Codezero."
|
113 |
|
|
|
114 |
|
|
.SH THREAD RELATIONSHIPS
|
115 |
|
|
Codezero aims to provide fine-grain privilege levels to threads in the system in the form of capabilities. Capabilities enable privileges of threads over each other to become highly configurable, resulting in the hierarchical relationship between them to become blurry. However, even though such a relationship is not enforced by the architecture, often it comes natural that threads are created by other threads. As a result, even though a thread hierarchy is not enforced by the capability design, it is implicitly catered for by a
|
116 |
|
|
.I pagerid
|
117 |
|
|
field inside the kernel, to denote the relationship that a thread has create or destroy rights on another thread. The relationship is only a one-level relationship, and it may be manipulated upon thread creation by
|
118 |
|
|
.B TC_AS_PAGER
|
119 |
|
|
or
|
120 |
|
|
.B TC_SHARE_PAGER
|
121 |
|
|
fields.
|
122 |
|
|
|
123 |
|
|
|
124 |
|
|
.SH L4 USERSPACE LIBRARY
|
125 |
|
|
.nf
|
126 |
|
|
N/A
|
127 |
|
|
|
128 |
|
|
.SH RETURN VALUE
|
129 |
|
|
.IR "l4_thread_control"()
|
130 |
|
|
Returns 0 on success, and negative value on failure. See below for error codes.
|
131 |
|
|
|
132 |
|
|
.SH ERRORS
|
133 |
|
|
|
134 |
|
|
.B -EINVAL
|
135 |
|
|
returned when
|
136 |
|
|
.IR "req"
|
137 |
|
|
field has an invalid value.
|
138 |
|
|
|
139 |
|
|
.B -ENOCAP
|
140 |
|
|
returned when capabilities required don't exist or do not have sufficient privileges.
|
141 |
|
|
|
142 |
|
|
.B -EFAULT
|
143 |
|
|
returned when
|
144 |
|
|
.I ids
|
145 |
|
|
argument would cause a page fault.
|
146 |
|
|
|
147 |
|
|
.B -ESRCH
|
148 |
|
|
returned when a given thread id has not been found in the container.
|
149 |
|
|
|
150 |
|
|
.SH SEE ALSO
|
151 |
|
|
.BR "capability"(7), " l4_exchange_registers" "(7), " "l4_getid" "(7)"
|