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