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