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