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