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 July 15, 2014 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(); 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. 350