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