| blob | 148a34e6db9f57eda80f3ade3e8522fa0c2af097 |
1 .\" Copyright (c) 2000-2001
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 .\"
26 .\" $FreeBSD$
27 .\"
28 .Dd October 26, 2007
29 .Dt KTHREAD 9
30 .Os
31 .Sh NAME
32 .Nm kthread_start ,
33 .Nm kthread_shutdown ,
34 .Nm kthread_add ,
35 .Nm kthread_exit ,
36 .Nm kthread_resume ,
37 .Nm kthread_suspend ,
38 .Nm kthread_suspend_check
39 .Nd "kernel threads"
40 .Sh SYNOPSIS
41 .In sys/kthread.h
42 .Ft void
43 .Fn kthread_start "const void *udata"
44 .Ft void
45 .Fn kthread_shutdown "void *arg" "int howto"
46 .Ft int
47 .Fo kthread_add
48 .Fa "void (*func)(void *)" "void *arg" "struct proc *procp"
49 .Fa "struct thread **newtdpp" "int flags" "int pages"
50 .Fa "const char *fmt" ...
51 .Fc
52 .Ft void
53 .Fn kthread_exit "void"
54 .Ft int
55 .Fn kthread_resume "struct thread *td"
56 .Ft int
57 .Fn kthread_suspend "struct thread *td" "int timo"
58 .Ft void
59 .Fn kthread_suspend_check "struct thread *td"
60 .Ft int
61 .Fo kproc_kthread_add
62 .Fa "void (*func)(void *)" "void *arg"
63 .Fa "struct proc **procptr" "struct thread **tdptr"
64 .Fa "int flags" "int pages" "char * procname" "const char *fmt" "..."
65 .Fc
66 .Sh DESCRIPTION
67 The function
68 .Fn kthread_start
69 is used to start
70 .Dq internal
71 daemons such as
72 .Nm bufdaemon , pagedaemon , vmdaemon ,
73 and the
74 .Nm syncer
75 and is intended
76 to be called from
77 .Xr SYSINIT 9 .
78 The
79 .Fa udata
80 argument is actually a pointer to a
81 .Vt "struct kthread_desc"
82 which describes the kernel thread that should be created:
83 .Bd -literal -offset indent
84 struct kthread_desc {
85 char *arg0;
86 void (*func)(void);
87 struct thread **global_threadpp;
88 };
89 .Ed
90 .Pp
91 The structure members are used by
92 .Fn kthread_start
93 as follows:
94 .Bl -tag -width ".Va global_threadpp" -offset indent
95 .It Va arg0
96 String to be used for the name of the thread.
97 This string will be copied into the
98 .Va td_name
99 member of the new threads'
100 .Vt "struct thread" .
101 .It Va func
102 The main function for this kernel thread to run.
103 .It Va global_threadpp
104 A pointer to a
105 .Vt "struct thread"
106 pointer that should be updated to point to the newly created thread's
107 .Vt thread
108 structure.
109 If this variable is
110 .Dv NULL ,
111 then it is ignored.
112 The thread will be a subthread of
113 .Va proc0
114 (PID 0).
115 .El
116 .Pp
117 The
118 .Fn kthread_add
119 function is used to create a kernel thread.
120 The new thread runs in kernel mode only.
121 It is added to the process specified by the
122 .Fa procp
123 argument, or if that is
124 .Dv NULL ,
125 to
126 .Va proc0 .
127 The
128 .Fa func
129 argument specifies the function that the thread should execute.
130 The
131 .Fa arg
132 argument is an arbitrary pointer that is passed in as the only argument to
133 .Fa func
134 when it is called by the new thread.
135 The
136 .Fa newtdpp
137 pointer points to a
138 .Vt "struct thread"
139 pointer that is to be updated to point to the newly created thread.
140 If this argument is
141 .Dv NULL ,
142 then it is ignored.
143 The
144 .Fa flags
145 argument specifies a set of flags as described in
146 .Xr rfork 2 .
147 The
148 .Fa pages
149 argument specifies the size of the new kernel thread's stack in pages.
150 If 0 is used, the default kernel stack size is allocated.
151 The rest of the arguments form a
152 .Xr printf 9
153 argument list that is used to build the name of the new thread and is stored
154 in the
155 .Va td_name
156 member of the new thread's
157 .Vt "struct thread" .
158 .Pp
159 The
160 .Fn kproc_kthread_add
161 function is much like the
162 .Fn kthread_add
163 function above except that if the kproc does not already
164 exist, it is created.
165 This function is better documented in the
166 .Xr kproc 9
167 manual page.
168 .Pp
169 The
170 .Fn kthread_exit
171 function is used to terminate kernel threads.
172 It should be called by the main function of the kernel thread rather than
173 letting the main function return to its caller.
174 .\" XXX "int ecode" argument isn't documented.
175 .Pp
176 The
177 .Fn kthread_resume ,
178 .Fn kthread_suspend ,
179 and
180 .Fn kthread_suspend_check
181 functions are used to suspend and resume a kernel thread.
182 During the main loop of its execution, a kernel thread that wishes to allow
183 itself to be suspended should call
184 .Fn kthread_suspend_check
185 passing in
186 .Va curthread
187 as the only argument.
188 This function checks to see if the kernel thread has been asked to suspend.
189 If it has, it will
190 .Xr tsleep 9
191 until it is told to resume.
192 Once it has been told to resume it will return allowing execution of the
193 kernel thread to continue.
194 The other two functions are used to notify a kernel thread of a suspend or
195 resume request.
196 The
197 .Fa td
198 argument points to the
199 .Vt "struct thread"
200 of the kernel thread to suspend or resume.
201 For
202 .Fn kthread_suspend ,
203 the
204 .Fa timo
205 argument specifies a timeout to wait for the kernel thread to acknowledge the
206 suspend request and suspend itself.
207 .Pp
208 The
209 .Fn kthread_shutdown
210 function is meant to be registered as a shutdown event for kernel threads that
211 need to be suspended voluntarily during system shutdown so as not to interfere
212 with system shutdown activities.
213 The actual suspension of the kernel thread is done with
214 .Fn kthread_suspend .
215 .Sh RETURN VALUES
216 The
217 .Fn kthread_add ,
218 .Fn kthread_resume ,
219 and
220 .Fn kthread_suspend
221 functions return zero on success and non-zero on failure.
222 .Sh EXAMPLES
223 This example demonstrates the use of a
224 .Vt "struct kthread_desc"
225 and the functions
226 .Fn kthread_start ,
227 .Fn kthread_shutdown ,
228 and
229 .Fn kthread_suspend_check
230 to run the
231 .Nm bufdaemon
232 process.
233 .Bd -literal -offset indent
234 static struct thread *bufdaemonthread;
236 static struct kthread_desc buf_kp = {
237 "bufdaemon",
238 buf_daemon,
239 &bufdaemonthread
240 };
241 SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kthread_start,
242 &buf_kp)
244 static void
245 buf_daemon()
246 {
247 ...
248 /*
249 * This process needs to be suspended prior to shutdown sync.
250 */
251 EVENTHANDLER_REGISTER(shutdown_pre_sync, kthread_shutdown,
252 bufdaemonthread, SHUTDOWN_PRI_LAST);
253 ...
254 for (;;) {
255 kthread_suspend_check(bufdaemonthread);
256 ...
257 }
258 }
259 .Ed
260 .Sh ERRORS
261 The
262 .Fn kthread_resume
263 and
264 .Fn kthread_suspend
265 functions will fail if:
266 .Bl -tag -width Er
267 .It Bq Er EINVAL
268 The
269 .Fa td
270 argument does not reference a kernel thread.
271 .El
272 .Pp
273 The
274 .Fn kthread_add
275 function will fail if:
276 .Bl -tag -width Er
277 .It Bq Er EAGAIN
278 The system-imposed limit on the total
279 number of processes under execution would be exceeded.
280 The limit is given by the
281 .Xr sysctl 3
282 MIB variable
283 .Dv KERN_MAXPROC .
284 .It Bq Er EINVAL
285 The
286 .Dv RFCFDG
287 flag was specified in the
288 .Fa flags
289 parameter.
290 .El
291 .Sh SEE ALSO
292 .Xr rfork 2 ,
293 .Xr exit1 9 ,
294 .Xr kproc 9 ,
295 .Xr SYSINIT 9 ,
296 .Xr wakeup 9
297 .Sh HISTORY
298 The
299 .Fn kthread_start
300 function first appeared in
301 .Fx 2.2
302 where it created a whole process.
303 It was converted to create threads in
304 .Fx 8.0 .
305 The
306 .Fn kthread_shutdown ,
307 .Fn kthread_exit ,
308 .Fn kthread_resume ,
309 .Fn kthread_suspend ,
310 and
311 .Fn kthread_suspend_check
312 functions were introduced in
313 .Fx 4.0
314 and were converted to threads in
315 .Fx 8.0 .
316 The
317 .Fn kthread_create
318 call was renamed to
319 .Fn kthread_add
320 in
321 .Fx 8.0 .
322 The old functionality of creating a kernel process was renamed
323 to
324 .Xr kproc_create 9 .
325 Prior to
326 .Fx 5.0 ,
327 the
328 .Fn kthread_shutdown ,
329 .Fn kthread_resume ,
330 .Fn kthread_suspend ,
331 and
332 .Fn kthread_suspend_check
333 functions were named
334 .Fn shutdown_kproc ,
335 .Fn resume_kproc ,
336 .Fn shutdown_kproc ,
337 and
338 .Fn kproc_suspend_loop ,
339 respectively.