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