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