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 24, 2000 29.Dt KTHREAD 9 30.Os 31.Sh NAME 32.Nm kproc_start , 33.Nm kproc_shutdown , 34.Nm kthread_create , 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 kproc_start "const void *udata" 44.Ft void 45.Fn kproc_shutdown "void *arg" "int howto" 46.Ft int 47.Fn kthread_create "void (*func)(void *)" "void *arg" "struct proc **newpp" "int flags" "const char *fmt" "..." 48.Ft void 49.Fn kthread_exit "int ecode" 50.Ft int 51.Fn kthread_resume "struct proc *p" 52.Ft int 53.Fn kthread_suspend "struct proc *p" "int timo" 54.Ft void 55.Fn kthread_suspend_check "struct proc *p" 56.Sh DESCRIPTION 57The function 58.Fn kproc_start 59is used to start 60.Dq internal 61daemons such as bufdaemon, pagedaemon, vmdaemon, and the syncer and is intended 62to be called from 63.Xr SYSINIT 9 . 64The 65.Fa udata 66argument is actually a pointer to a 67.Li struct kproc_desc 68which describes the kernel thread that should be created: 69.Bd -literal -offset indent 70struct kproc_desc { 71 char *arg0; 72 void (*func) __P((void)); 73 struct proc **global_procpp; 74}; 75.Ed 76.Pp 77The structure members are used by 78.Fn kproc_start 79as follows: 80.Bl -tag -width "global_procpp" -offset indent 81.It Va arg0 82String to be used for the name of the process. 83This string will be copied into the 84.Va p_comm 85member of the new process' 86.Li struct proc . 87.It Va func 88The main function for this kernel process to run. 89.It Va global_procpp 90A pointer to a 91.Li struct proc 92pointer that should be updated to point to the newly created process' process 93structure. 94If this variable is 95.Dv NULL , 96then it is ignored. 97.El 98.Pp 99The 100.Fn kthread_create 101function is used to create a kernel thread. 102The new thread shares its address space with process 0, the swapper process, 103and runs in kernel mode only. 104The 105.Fa func 106argument specifies the function that the thread should execute. 107The 108.Fa arg 109argument is an arbitrary pointer that is passed in as the only argument to 110.Fa func 111when it is called by the new process. 112The 113.Fa newpp 114pointer points to a 115.Li struct proc 116pointer that is to be updated to point to the newly created process. 117If this argument is 118.Dv NULL , 119then it is ignored. 120The 121.Fa flags 122argument specifies a set of flags as described in 123.Xr rfork 2 . 124The rest of the arguments form a 125.Xr printf 9 126argument list that is used to build the name of the new thread and is stored 127in the 128.Va p_comm 129member of the new thread's 130.Li struct proc . 131.Pp 132The 133.Fn kthread_exit 134function is used to terminate kernel threads. 135It should be called by the main function of the kernel thread rather than 136letting the main function return to its caller. 137The 138.Fa ecode 139argument specifies the exit status of the thread. 140.Pp 141The 142.Fn kthread_resume , 143.Fn kthread_suspend , 144and 145.Fn kthread_suspend_check 146functions are used to suspend and resume a kernel thread. 147During the main loop of its execution, a kernel thread that wishes to allow 148itself to be suspended should call 149.Fn kthread_suspend_check 150passing in 151.Va curproc 152as the only argument. 153This function checks to see if the kernel thread has been asked to suspend. 154If it has, it will 155.Xr tsleep 9 156until it is told to resume. 157Once it has been told to resume it will return allowing execution of the 158kernel thread to continue. 159The other two functions are used to notify a kernel thread of a suspend or 160resume request. 161The 162.Fa p 163argument points to the 164.Li struct proc 165of the kernel thread to suspend or resume. 166For 167.Fn kthread_suspend , 168the 169.Fa timo 170argument specifies a timeout to wait for the kernel thread to acknowledge the 171suspend request and suspend itself. 172.Pp 173The 174.Fn kproc_shutdown 175function is meant to be registered as a shutdown event for kernel threads that 176need to be suspended voluntarily during system shutdown so as not to interfere 177with system shutdown activities. 178The actual suspension of the kernel thread is done with 179.Fn kthread_suspend . 180.Sh RETURN VALUES 181The 182.Fn kthread_create , 183.Fn kthread_resume , 184and 185.Fn kthread_suspend 186functions return zero on success and non-zero on failure. 187.Sh EXAMPLES 188This example demonstrates the use of a 189.Li struct kproc_desc 190and the functions 191.Fn kproc_start , 192.Fn kproc_shutdown , 193and 194.Fn kthread_suspend_check 195to run the 196.Dq bufdaemon 197process. 198.Bd -literal -offset indent 199static struct proc *bufdaemonproc; 200 201static struct kproc_desc buf_kp = { 202 "bufdaemon", 203 buf_daemon, 204 &bufdaemonproc 205}; 206SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start, 207 &buf_kp) 208 209static void 210buf_daemon() 211{ 212 ... 213 /* 214 * This process needs to be suspended prior to shutdown sync. 215 */ 216 EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown, 217 bufdaemonproc, SHUTDOWN_PRI_LAST); 218 ... 219 for (;;) { 220 kthread_suspend_check(bufdaemonproc); 221 ... 222 } 223} 224.Ed 225.Sh ERRORS 226The 227.Fn kthread_resume 228and 229.Fn kthread_suspend 230functions will fail if: 231.Bl -tag -width Er 232.It Bq Er EINVAL 233The 234.Fa p 235argument does not reference a kernel thread. 236.El 237.Pp 238The 239.Fn kthread_create 240function will fail if: 241.Bl -tag -width Er 242.It Bq Er EAGAIN 243The system-imposed limit on the total 244number of processes under execution would be exceeded. 245The limit is given by the 246.Xr sysctl 3 247MIB variable 248.Dv KERN_MAXPROC . 249.It Bq Er EINVAL 250The 251.Dv RFCFDG 252flag was specified in the 253.Fa flags 254parameter. 255.El 256.Sh SEE ALSO 257.Xr rfork 2 , 258.Xr SYSINIT 9 259.Sh HISTORY 260The 261.Fn kproc_start 262function first appeared in 263.Fx 2.2 . 264The 265.Fn kproc_shutdown , 266.Fn kthread_create , 267.Fn kthread_exit , 268.Fn kthread_resume , 269.Fn kthread_suspend , 270and 271.Fn kthread_suspend_check 272functions were introduced in 273.Fx 4.0 . 274Prior to 275.Fx 5.0 , 276the 277.Fn kproc_shutdown , 278.Fn kthread_resume , 279.Fn kthread_suspend , 280and 281.Fn kthread_suspend_check 282functions were named 283.Fn shutdown_kproc , 284.Fn resume_kproc , 285.Fn shutdown_kproc , 286and 287.Fn kproc_suspend_loop , 288respectively. 289