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 September 24, 2004 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" "int pages" "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)(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 125.Fa pages 126argument specifies the size of the new kernel thread's stack in pages. 127If 0 is used, the default kernel stack size is allocated. 128The rest of the arguments form a 129.Xr printf 9 130argument list that is used to build the name of the new thread and is stored 131in the 132.Va p_comm 133member of the new thread's 134.Li struct proc . 135.Pp 136The 137.Fn kthread_exit 138function is used to terminate kernel threads. 139It should be called by the main function of the kernel thread rather than 140letting the main function return to its caller. 141The 142.Fa ecode 143argument specifies the exit status of the thread. 144While exiting, the function 145.Xr exit1 9 146will initiate a call to 147.Xr wakeup 9 148on the thread handle. 149.Pp 150The 151.Fn kthread_resume , 152.Fn kthread_suspend , 153and 154.Fn kthread_suspend_check 155functions are used to suspend and resume a kernel thread. 156During the main loop of its execution, a kernel thread that wishes to allow 157itself to be suspended should call 158.Fn kthread_suspend_check 159passing in 160.Va curproc 161as the only argument. 162This function checks to see if the kernel thread has been asked to suspend. 163If it has, it will 164.Xr tsleep 9 165until it is told to resume. 166Once it has been told to resume it will return allowing execution of the 167kernel thread to continue. 168The other two functions are used to notify a kernel thread of a suspend or 169resume request. 170The 171.Fa p 172argument points to the 173.Li struct proc 174of the kernel thread to suspend or resume. 175For 176.Fn kthread_suspend , 177the 178.Fa timo 179argument specifies a timeout to wait for the kernel thread to acknowledge the 180suspend request and suspend itself. 181.Pp 182The 183.Fn kproc_shutdown 184function is meant to be registered as a shutdown event for kernel threads that 185need to be suspended voluntarily during system shutdown so as not to interfere 186with system shutdown activities. 187The actual suspension of the kernel thread is done with 188.Fn kthread_suspend . 189.Sh RETURN VALUES 190The 191.Fn kthread_create , 192.Fn kthread_resume , 193and 194.Fn kthread_suspend 195functions return zero on success and non-zero on failure. 196.Sh EXAMPLES 197This example demonstrates the use of a 198.Li struct kproc_desc 199and the functions 200.Fn kproc_start , 201.Fn kproc_shutdown , 202and 203.Fn kthread_suspend_check 204to run the 205.Dq bufdaemon 206process. 207.Bd -literal -offset indent 208static struct proc *bufdaemonproc; 209 210static struct kproc_desc buf_kp = { 211 "bufdaemon", 212 buf_daemon, 213 &bufdaemonproc 214}; 215SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start, 216 &buf_kp) 217 218static void 219buf_daemon() 220{ 221 ... 222 /* 223 * This process needs to be suspended prior to shutdown sync. 224 */ 225 EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown, 226 bufdaemonproc, SHUTDOWN_PRI_LAST); 227 ... 228 for (;;) { 229 kthread_suspend_check(bufdaemonproc); 230 ... 231 } 232} 233.Ed 234.Sh ERRORS 235The 236.Fn kthread_resume 237and 238.Fn kthread_suspend 239functions will fail if: 240.Bl -tag -width Er 241.It Bq Er EINVAL 242The 243.Fa p 244argument does not reference a kernel thread. 245.El 246.Pp 247The 248.Fn kthread_create 249function will fail if: 250.Bl -tag -width Er 251.It Bq Er EAGAIN 252The system-imposed limit on the total 253number of processes under execution would be exceeded. 254The limit is given by the 255.Xr sysctl 3 256MIB variable 257.Dv KERN_MAXPROC . 258.It Bq Er EINVAL 259The 260.Dv RFCFDG 261flag was specified in the 262.Fa flags 263parameter. 264.El 265.Sh SEE ALSO 266.Xr rfork 2 , 267.Xr exit1 9 , 268.Xr SYSINIT 9 , 269.Xr wakeup 9 270.Sh HISTORY 271The 272.Fn kproc_start 273function first appeared in 274.Fx 2.2 . 275The 276.Fn kproc_shutdown , 277.Fn kthread_create , 278.Fn kthread_exit , 279.Fn kthread_resume , 280.Fn kthread_suspend , 281and 282.Fn kthread_suspend_check 283functions were introduced in 284.Fx 4.0 . 285Prior to 286.Fx 5.0 , 287the 288.Fn kproc_shutdown , 289.Fn kthread_resume , 290.Fn kthread_suspend , 291and 292.Fn kthread_suspend_check 293functions were named 294.Fn shutdown_kproc , 295.Fn resume_kproc , 296.Fn shutdown_kproc , 297and 298.Fn kproc_suspend_loop , 299respectively. 300