xref: /freebsd/share/man/man9/kthread.9 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
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.Sh DESCRIPTION
61The function
62.Fn kthread_start
63is used to start
64.Dq internal
65daemons such as
66.Nm bufdaemon , pagedaemon , vmdaemon ,
67and the
68.Nm syncer
69and is intended
70to be called from
71.Xr SYSINIT 9 .
72The
73.Fa udata
74argument is actually a pointer to a
75.Vt "struct kthread_desc"
76which describes the kernel thread that should be created:
77.Bd -literal -offset indent
78struct kthread_desc {
79	char		*arg0;
80	void		(*func)(void);
81	struct thread	**global_threadpp;
82};
83.Ed
84.Pp
85The structure members are used by
86.Fn kthread_start
87as follows:
88.Bl -tag -width ".Va global_threadpp" -offset indent
89.It Va arg0
90String to be used for the name of the thread.
91This string will be copied into the
92.Va td_name
93member of the new threads'
94.Vt "struct thread" .
95.It Va func
96The main function for this kernel thread to run.
97.It Va global_threadpp
98A pointer to a
99.Vt "struct thread"
100pointer that should be updated to point to the newly created thread's
101.Vt thread
102structure.
103If this variable is
104.Dv NULL ,
105then it is ignored.
106The thread will be a subthread of
107.Va proc0
108(PID 0).
109.El
110.Pp
111The
112.Fn kthread_add
113function is used to create a kernel thread.
114The new thread runs in kernel mode only.
115It is added to the process specified by the
116.Fa procp
117argument, or if that is
118.Dv NULL ,
119to
120.Va proc0 .
121The
122.Fa func
123argument specifies the function that the thread should execute.
124The
125.Fa arg
126argument is an arbitrary pointer that is passed in as the only argument to
127.Fa func
128when it is called by the new thread.
129The
130.Fa newtdpp
131pointer points to a
132.Vt "struct thread"
133pointer that is to be updated to point to the newly created thread.
134If this argument is
135.Dv NULL ,
136then it is ignored.
137The
138.Fa flags
139argument specifies a set of flags as described in
140.Xr rfork 2 .
141The
142.Fa pages
143argument specifies the size of the new kernel thread's stack in pages.
144If 0 is used, the default kernel stack size is allocated.
145The rest of the arguments form a
146.Xr printf 9
147argument list that is used to build the name of the new thread and is stored
148in the
149.Va td_name
150member of the new thread's
151.Vt "struct thread" .
152.Pp
153The
154.Fn kthread_exit
155function is used to terminate kernel threads.
156It should be called by the main function of the kernel thread rather than
157letting the main function return to its caller.
158.\" XXX "int ecode" argument isn't documented.
159.Pp
160The
161.Fn kthread_resume ,
162.Fn kthread_suspend ,
163and
164.Fn kthread_suspend_check
165functions are used to suspend and resume a kernel thread.
166During the main loop of its execution, a kernel thread that wishes to allow
167itself to be suspended should call
168.Fn kthread_suspend_check
169passing in
170.Va curthread
171as the only argument.
172This function checks to see if the kernel thread has been asked to suspend.
173If it has, it will
174.Xr tsleep 9
175until it is told to resume.
176Once it has been told to resume it will return allowing execution of the
177kernel thread to continue.
178The other two functions are used to notify a kernel thread of a suspend or
179resume request.
180The
181.Fa td
182argument points to the
183.Vt "struct thread"
184of the kernel thread to suspend or resume.
185For
186.Fn kthread_suspend ,
187the
188.Fa timo
189argument specifies a timeout to wait for the kernel thread to acknowledge the
190suspend request and suspend itself.
191.Pp
192The
193.Fn kthread_shutdown
194function is meant to be registered as a shutdown event for kernel threads that
195need to be suspended voluntarily during system shutdown so as not to interfere
196with system shutdown activities.
197The actual suspension of the kernel thread is done with
198.Fn kthread_suspend .
199.Sh RETURN VALUES
200The
201.Fn kthread_add ,
202.Fn kthread_resume ,
203and
204.Fn kthread_suspend
205functions return zero on success and non-zero on failure.
206.Sh EXAMPLES
207This example demonstrates the use of a
208.Vt "struct kthread_desc"
209and the functions
210.Fn kthread_start ,
211.Fn kthread_shutdown ,
212and
213.Fn kthread_suspend_check
214to run the
215.Nm bufdaemon
216process.
217.Bd -literal -offset indent
218static struct thread *bufdaemonthread;
219
220static struct kthread_desc buf_kp = {
221	"bufdaemon",
222	buf_daemon,
223	&bufdaemonthread
224};
225SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kthread_start,
226    &buf_kp)
227
228static void
229buf_daemon()
230{
231	...
232	/*
233	 * This process needs to be suspended prior to shutdown sync.
234	 */
235	EVENTHANDLER_REGISTER(shutdown_pre_sync, kthread_shutdown,
236	    bufdaemonthread, SHUTDOWN_PRI_LAST);
237	...
238	for (;;) {
239		kthread_suspend_check(bufdaemonthread);
240		...
241	}
242}
243.Ed
244.Sh ERRORS
245The
246.Fn kthread_resume
247and
248.Fn kthread_suspend
249functions will fail if:
250.Bl -tag -width Er
251.It Bq Er EINVAL
252The
253.Fa td
254argument does not reference a kernel thread.
255.El
256.Pp
257The
258.Fn kthread_add
259function will fail if:
260.Bl -tag -width Er
261.It Bq Er EAGAIN
262The system-imposed limit on the total
263number of processes under execution would be exceeded.
264The limit is given by the
265.Xr sysctl 3
266MIB variable
267.Dv KERN_MAXPROC .
268.It Bq Er EINVAL
269The
270.Dv RFCFDG
271flag was specified in the
272.Fa flags
273parameter.
274.El
275.Sh SEE ALSO
276.Xr rfork 2 ,
277.Xr exit1 9 ,
278.Xr kproc 9 ,
279.Xr SYSINIT 9 ,
280.Xr wakeup 9
281.Sh HISTORY
282The
283.Fn kthread_start
284function first appeared in
285.Fx 2.2
286where it created a whole process.
287It was converted to create threads in
288.Fx 8.0 .
289The
290.Fn kthread_shutdown ,
291.Fn kthread_exit ,
292.Fn kthread_resume ,
293.Fn kthread_suspend ,
294and
295.Fn kthread_suspend_check
296functions were introduced in
297.Fx 4.0
298and were converted to threads in
299.Fx 8.0 .
300The
301.Fn kthread_create
302call was renamed to
303.Fn kthread_add
304in
305.Fx 8.0 .
306The old functionality of creating a kernel process was renamed
307to
308.Xr kproc_create 9 .
309Prior to
310.Fx 5.0 ,
311the
312.Fn kthread_shutdown ,
313.Fn kthread_resume ,
314.Fn kthread_suspend ,
315and
316.Fn kthread_suspend_check
317functions were named
318.Fn shutdown_kproc ,
319.Fn resume_kproc ,
320.Fn shutdown_kproc ,
321and
322.Fn kproc_suspend_loop ,
323respectively.
324