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.Dd October 19, 2007 27.Dt KPROC 9 28.Os 29.Sh NAME 30.Nm kproc_start , 31.Nm kproc_shutdown , 32.Nm kproc_create , 33.Nm kproc_exit , 34.Nm kproc_resume , 35.Nm kproc_suspend , 36.Nm kproc_suspend_check 37.Nd "kernel processes" 38.Sh SYNOPSIS 39.In sys/kthread.h 40.Ft void 41.Fn kproc_start "const void *udata" 42.Ft void 43.Fn kproc_shutdown "void *arg" "int howto" 44.Ft int 45.Fo kproc_create 46.Fa "void (*func)(void *)" "void *arg" "struct proc **newpp" 47.Fa "int flags" "int pages" 48.Fa "const char *fmt" ... 49.Fc 50.Ft void 51.Fn kproc_exit "int ecode" 52.Ft int 53.Fn kproc_resume "struct proc *p" 54.Ft int 55.Fn kproc_suspend "struct proc *p" "int timo" 56.Ft void 57.Fn kproc_suspend_check "struct proc *p" 58.Ft int 59.Fo kproc_kthread_add 60.Fa "void (*func)(void *)" "void *arg" 61.Fa "struct proc **procptr" "struct thread **tdptr" 62.Fa "int flags" "int pages" "char * procname" "const char *fmt" "..." 63.Fc 64.Sh DESCRIPTION 65In 66.Fx 8.0 , 67the 68.Fn kthread* 9 69family of functions was renamed to be the 70.Fn kproc* 9 71family of functions, as they were misnamed 72and actually produced kernel processes. 73A new family of 74.Em different 75.Fn kthread_* 9 76functions was added to produce 77.Em real 78kernel 79.Em threads . 80See the 81.Xr kthread 9 82man page for more information on those calls. 83Also note that the 84.Fn kproc_kthread_add 9 85function appears in both pages as its functionality is split. 86.Pp 87The function 88.Fn kproc_start 89is used to start 90.Dq internal 91daemons such as 92.Nm bufdaemon , pagedaemon , vmdaemon , 93and the 94.Nm syncer 95and is intended 96to be called from 97.Xr SYSINIT 9 . 98The 99.Fa udata 100argument is actually a pointer to a 101.Vt "struct kproc_desc" 102which describes the kernel process that should be created: 103.Bd -literal -offset indent 104struct kproc_desc { 105 char *arg0; 106 void (*func)(void); 107 struct proc **global_procpp; 108}; 109.Ed 110.Pp 111The structure members are used by 112.Fn kproc_start 113as follows: 114.Bl -tag -width ".Va global_procpp" -offset indent 115.It Va arg0 116String to be used for the name of the process. 117This string will be copied into the 118.Va p_comm 119member of the new process' 120.Vt "struct proc" . 121.It Va func 122The main function for this kernel process to run. 123.It Va global_procpp 124A pointer to a 125.Vt "struct proc" 126pointer that should be updated to point to the newly created process' process 127structure. 128If this variable is 129.Dv NULL , 130then it is ignored. 131.El 132.Pp 133The 134.Fn kproc_create 135function is used to create a kernel process. 136The new process shares its address space with process 0, the 137.Nm swapper 138process, 139and runs in kernel mode only. 140The 141.Fa func 142argument specifies the function that the process should execute. 143The 144.Fa arg 145argument is an arbitrary pointer that is passed in as the only argument to 146.Fa func 147when it is called by the new process. 148The 149.Fa newpp 150pointer points to a 151.Vt "struct proc" 152pointer that is to be updated to point to the newly created process. 153If this argument is 154.Dv NULL , 155then it is ignored. 156The 157.Fa flags 158argument specifies a set of flags as described in 159.Xr rfork 2 . 160The 161.Fa pages 162argument specifies the size of the new kernel process's stack in pages. 163If 0 is used, the default kernel stack size is allocated. 164The rest of the arguments form a 165.Xr printf 9 166argument list that is used to build the name of the new process and is stored 167in the 168.Va p_comm 169member of the new process's 170.Vt "struct proc" . 171.Pp 172The 173.Fn kproc_exit 174function is used to terminate kernel processes. 175It should be called by the main function of the kernel process rather than 176letting the main function return to its caller. 177The 178.Fa ecode 179argument specifies the exit status of the process. 180While exiting, the function 181.Xr exit1 9 182will initiate a call to 183.Xr wakeup 9 184on the process handle. 185.Pp 186The 187.Fn kproc_resume , 188.Fn kproc_suspend , 189and 190.Fn kproc_suspend_check 191functions are used to suspend and resume a kernel process. 192During the main loop of its execution, a kernel process that wishes to allow 193itself to be suspended should call 194.Fn kproc_suspend_check 195passing in 196.Va curproc 197as the only argument. 198This function checks to see if the kernel process has been asked to suspend. 199If it has, it will 200.Xr tsleep 9 201until it is told to resume. 202Once it has been told to resume it will return allowing execution of the 203kernel process to continue. 204The other two functions are used to notify a kernel process of a suspend or 205resume request. 206The 207.Fa p 208argument points to the 209.Vt "struct proc" 210of the kernel process to suspend or resume. 211For 212.Fn kproc_suspend , 213the 214.Fa timo 215argument specifies a timeout to wait for the kernel process to acknowledge the 216suspend request and suspend itself. 217.Pp 218The 219.Fn kproc_shutdown 220function is meant to be registered as a shutdown event for kernel processes that 221need to be suspended voluntarily during system shutdown so as not to interfere 222with system shutdown activities. 223The actual suspension of the kernel process is done with 224.Fn kproc_suspend . 225.Pp 226The 227.Fn kproc_kthread_add 228function is much like the 229.Fn kproc_create 230function above except that if the kproc already exists, 231then only a new thread (see 232.Xr kthread 9 ) 233is created on the existing process. 234The 235.Fa func 236argument specifies the function that the process should execute. 237The 238.Fa arg 239argument is an arbitrary pointer that is passed in as the only argument to 240.Fa func 241when it is called by the new process. 242The 243.Fa procptr 244pointer points to a 245.Vt "struct proc" 246pointer that is the location to be updated with the new proc pointer 247if a new process is created, or if not 248.Dv NULL , 249must contain the process pointer for the already existing process. 250If this argument points to 251.Dv NULL , 252then a new process is created and the field updated. 253If not NULL, the 254.Fa tdptr 255pointer points to a 256.Vt "struct thread" 257pointer that is the location to be updated with the new thread pointer. 258The 259.Fa flags 260argument specifies a set of flags as described in 261.Xr rfork 2 . 262The 263.Fa pages 264argument specifies the size of the new kernel thread's stack in pages. 265If 0 is used, the default kernel stack size is allocated. 266The procname argument is the name the new process should be given if it needs to be created. 267It is 268.Em NOT 269a printf style format specifier but a simple string. 270The rest of the arguments form a 271.Xr printf 9 272argument list that is used to build the name of the new thread and is stored 273in the 274.Va td_name 275member of the new thread's 276.Vt "struct thread" . 277.Sh RETURN VALUES 278The 279.Fn kproc_create , 280.Fn kproc_resume , 281and 282.Fn kproc_suspend 283functions return zero on success and non-zero on failure. 284.Sh EXAMPLES 285This example demonstrates the use of a 286.Vt "struct kproc_desc" 287and the functions 288.Fn kproc_start , 289.Fn kproc_shutdown , 290and 291.Fn kproc_suspend_check 292to run the 293.Nm bufdaemon 294process. 295.Bd -literal -offset indent 296static struct proc *bufdaemonproc; 297 298static struct kproc_desc buf_kp = { 299 "bufdaemon", 300 buf_daemon, 301 &bufdaemonproc 302}; 303SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start, 304 &buf_kp) 305 306static void 307buf_daemon() 308{ 309 ... 310 /* 311 * This process needs to be suspended prior to shutdown sync. 312 */ 313 EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown, 314 bufdaemonproc, SHUTDOWN_PRI_LAST); 315 ... 316 for (;;) { 317 kproc_suspend_check(bufdaemonproc); 318 ... 319 } 320} 321.Ed 322.Sh ERRORS 323The 324.Fn kproc_resume 325and 326.Fn kproc_suspend 327functions will fail if: 328.Bl -tag -width Er 329.It Bq Er EINVAL 330The 331.Fa p 332argument does not reference a kernel process. 333.El 334.Pp 335The 336.Fn kproc_create 337function will fail if: 338.Bl -tag -width Er 339.It Bq Er EAGAIN 340The system-imposed limit on the total 341number of processes under execution would be exceeded. 342The limit is given by the 343.Xr sysctl 3 344MIB variable 345.Dv KERN_MAXPROC . 346.It Bq Er EINVAL 347The 348.Dv RFCFDG 349flag was specified in the 350.Fa flags 351parameter. 352.El 353.Sh SEE ALSO 354.Xr rfork 2 , 355.Xr exit1 9 , 356.Xr kthread 9 , 357.Xr SYSINIT 9 , 358.Xr wakeup 9 359.Sh HISTORY 360The 361.Fn kproc_start 362function first appeared in 363.Fx 2.2 . 364The 365.Fn kproc_shutdown , 366.Fn kproc_create , 367.Fn kproc_exit , 368.Fn kproc_resume , 369.Fn kproc_suspend , 370and 371.Fn kproc_suspend_check 372functions were introduced in 373.Fx 4.0 . 374Prior to 375.Fx 5.0 , 376the 377.Fn kproc_shutdown , 378.Fn kproc_resume , 379.Fn kproc_suspend , 380and 381.Fn kproc_suspend_check 382functions were named 383.Fn shutdown_kproc , 384.Fn resume_kproc , 385.Fn shutdown_kproc , 386and 387.Fn kproc_suspend_loop , 388respectively. 389Originally they had the names 390.Fn kthread_* 391but were changed to 392.Fn kproc_* 393when real kthreads became available. 394