1.\" Copyright (c) 2000 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_suspend_loop , 34.Nm kthread_create , 35.Nm kthread_exit , 36.Nm resume_kproc , 37.Nm shutdown_kproc , 38.Nm suspend_kproc 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_suspend_loop "struct proc *p" 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 resume_kproc "struct proc *p" 52.Ft void 53.Fn shutdown_kproc "void *arg" "int howto" 54.Ft int 55.Fn suspend_kproc "struct proc *p" "int timo" 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 kproc_suspend_loop , 144.Fn resume_kproc , 145and 146.Fn suspend_kproc 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 kproc_suspend_loop 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 suspend_kproc , 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 shutdown_kproc 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 suspend_kproc . 181.Sh RETURN VALUES 182The 183.Fn kthread_create , 184.Fn resume_kproc , 185and 186.Fn suspend_kproc 187functions return zero on success and non-zero on failure. 188Upon failure, the global variable 189.Va errno 190is set to indicate the error. 191.Sh EXAMPLES 192This example demonstrates the use of a 193.Li struct kproc_desc 194and the functions 195.Fn kproc_start , 196.Fn shutdown_kproc, 197and 198.Fn kproc_suspend_loop 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, shutdown_kproc, 221 bufdaemonproc, SHUTDOWN_PRI_LAST); 222 ... 223 for (;;) { 224 kproc_suspend_loop(bufdaemonproc); 225 ... 226 } 227} 228.Ed 229.Sh ERRORS 230The 231.Fn resume_kproc 232and 233.Fn suspend_kproc 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.Sh SEE ALSO 260.Xr SYSINIT 9 , 261.Xr rfork 2 262.Sh HISTORY 263The 264.Fn kproc_start 265function first appeared in 266.Fx 2.2 . 267The 268.Fn kproc_suspend_loop , 269.Fn kthread_create , 270.Fn kthread_exit , 271.Fn resume_kproc , 272.Fn shutdown_kproc , 273and 274.Fn suspend_kproc 275functions were introducted in 276.Fx 4.0 . 277.Sh BUGS 278If a kernel thread exits its main function (specified as the 279.Fa func 280argument to 281.Fn kthread_create 282or in the 283.Li struct kproc_desc 284passed to 285.Fn kpoc_start ) 286then it will attempt to return backwards through the 287.Fn fork1 288trampoline code with unpredictable results. 289The code should instead use a trampoline function to launch 290.Fa func 291and call 292.Fn kthread_exit 293if 294.Fa func 295returns. 296