/share/man/man9/kthread.9

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