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