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