share/man/man9/kproc.9

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