share/man/man9/kthread.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 26, 2007
  29 .Dt KTHREAD 9
  30 .Os
  31 .Sh NAME
  32 .Nm kthread_start ,
  33 .Nm kthread_shutdown ,
  34 .Nm kthread_add ,
  35 .Nm kthread_exit ,
  36 .Nm kthread_resume ,
  37 .Nm kthread_suspend ,
  38 .Nm kthread_suspend_check
  39 .Nd "kernel threads"
  40 .Sh SYNOPSIS
  41 .In sys/kthread.h
  42 .Ft void
  43 .Fn kthread_start "const void *udata"
  44 .Ft void
  45 .Fn kthread_shutdown "void *arg" "int howto"
  46 .Ft int
  47 .Fo kthread_add
  48 .Fa "void (*func)(void *)" "void *arg" "struct proc *procp"
  49 .Fa "struct thread **newtdpp" "int flags" "int pages"
  50 .Fa "const char *fmt" ...
  51 .Fc
  52 .Ft void
  53 .Fn kthread_exit "void"
  54 .Ft int
  55 .Fn kthread_resume "struct thread *td"
  56 .Ft int
  57 .Fn kthread_suspend "struct thread *td" "int timo"
  58 .Ft void
  59 .Fn kthread_suspend_check "struct thread *td"
  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 kthread_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 kthread_desc"
  82 which describes the kernel thread that should be created:
  83 .Bd -literal -offset indent
  84 struct kthread_desc {
  85         char            *arg0;
  86         void            (*func)(void);
  87         struct thread   **global_threadpp;
  88 };
  89 .Ed
  90 .Pp
  91 The structure members are used by
  92 .Fn kthread_start
  93 as follows:
  94 .Bl -tag -width ".Va global_threadpp" -offset indent
  95 .It Va arg0
  96 String to be used for the name of the thread.
  97 This string will be copied into the
  98 .Va td_name
  99 member of the new threads'
 100 .Vt "struct thread" .
 101 .It Va func
 102 The main function for this kernel thread to run.
 103 .It Va global_threadpp
 104 A pointer to a
 105 .Vt "struct thread"
 106 pointer that should be updated to point to the newly created thread's
 107 .Vt thread
 108 structure.
 109 If this variable is
 110 .Dv NULL ,
 111 then it is ignored.
 112 The thread will be a subthread of
 113 .Va proc0
 114 (PID 0).
 115 .El
 116 .Pp
 117 The
 118 .Fn kthread_add
 119 function is used to create a kernel thread.
 120 The new thread runs in kernel mode only.
 121 It is added to the process specified by the
 122 .Fa procp
 123 argument, or if that is
 124 .Dv NULL ,
 125 to
 126 .Va proc0 .
 127 The
 128 .Fa func
 129 argument specifies the function that the thread should execute.
 130 The
 131 .Fa arg
 132 argument is an arbitrary pointer that is passed in as the only argument to
 133 .Fa func
 134 when it is called by the new thread.
 135 The
 136 .Fa newtdpp
 137 pointer points to a
 138 .Vt "struct thread"
 139 pointer that is to be updated to point to the newly created thread.
 140 If this argument is
 141 .Dv NULL ,
 142 then it is ignored.
 143 The
 144 .Fa flags
 145 argument specifies a set of flags as described in
 146 .Xr rfork 2 .
 147 The
 148 .Fa pages
 149 argument specifies the size of the new kernel thread's stack in pages.
 150 If 0 is used, the default kernel stack size is allocated.
 151 The rest of the arguments form a
 152 .Xr printf 9
 153 argument list that is used to build the name of the new thread and is stored
 154 in the
 155 .Va td_name
 156 member of the new thread's
 157 .Vt "struct thread" .
 158 .Pp
 159 The
 160 .Fn kproc_kthread_add
 161 function is much like the
 162 .Fn kthread_add
 163 function above except that if the kproc does not already
 164 exist, it is created.
 165 This function is better documented in the
 166 .Xr kproc 9
 167 manual page.
 168 .Pp
 169 The
 170 .Fn kthread_exit
 171 function is used to terminate kernel threads.
 172 It should be called by the main function of the kernel thread rather than
 173 letting the main function return to its caller.
 174 .\" XXX "int ecode" argument isn't documented.
 175 .Pp
 176 The
 177 .Fn kthread_resume ,
 178 .Fn kthread_suspend ,
 179 and
 180 .Fn kthread_suspend_check
 181 functions are used to suspend and resume a kernel thread.
 182 During the main loop of its execution, a kernel thread that wishes to allow
 183 itself to be suspended should call
 184 .Fn kthread_suspend_check
 185 passing in
 186 .Va curthread
 187 as the only argument.
 188 This function checks to see if the kernel thread has been asked to suspend.
 189 If it has, it will
 190 .Xr tsleep 9
 191 until it is told to resume.
 192 Once it has been told to resume it will return allowing execution of the
 193 kernel thread to continue.
 194 The other two functions are used to notify a kernel thread of a suspend or
 195 resume request.
 196 The
 197 .Fa td
 198 argument points to the
 199 .Vt "struct thread"
 200 of the kernel thread to suspend or resume.
 201 For
 202 .Fn kthread_suspend ,
 203 the
 204 .Fa timo
 205 argument specifies a timeout to wait for the kernel thread to acknowledge the
 206 suspend request and suspend itself.
 207 .Pp
 208 The
 209 .Fn kthread_shutdown
 210 function is meant to be registered as a shutdown event for kernel threads that
 211 need to be suspended voluntarily during system shutdown so as not to interfere
 212 with system shutdown activities.
 213 The actual suspension of the kernel thread is done with
 214 .Fn kthread_suspend .
 215 .Sh RETURN VALUES
 216 The
 217 .Fn kthread_add ,
 218 .Fn kthread_resume ,
 219 and
 220 .Fn kthread_suspend
 221 functions return zero on success and non-zero on failure.
 222 .Sh EXAMPLES
 223 This example demonstrates the use of a
 224 .Vt "struct kthread_desc"
 225 and the functions
 226 .Fn kthread_start ,
 227 .Fn kthread_shutdown ,
 228 and
 229 .Fn kthread_suspend_check
 230 to run the
 231 .Nm bufdaemon
 232 process.
 233 .Bd -literal -offset indent
 234 static struct thread *bufdaemonthread;
 235
 236 static struct kthread_desc buf_kp = {
 237         "bufdaemon",
 238         buf_daemon,
 239         &bufdaemonthread
 240 };
 241 SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kthread_start,
 242     &buf_kp)
 243
 244 static void
 245 buf_daemon()
 246 {
 247         ...
 248         /*
 249          * This process needs to be suspended prior to shutdown sync.
 250          */
 251         EVENTHANDLER_REGISTER(shutdown_pre_sync, kthread_shutdown,
 252             bufdaemonthread, SHUTDOWN_PRI_LAST);
 253         ...
 254         for (;;) {
 255                 kthread_suspend_check(bufdaemonthread);
 256                 ...
 257         }
 258 }
 259 .Ed
 260 .Sh ERRORS
 261 The
 262 .Fn kthread_resume
 263 and
 264 .Fn kthread_suspend
 265 functions will fail if:
 266 .Bl -tag -width Er
 267 .It Bq Er EINVAL
 268 The
 269 .Fa td
 270 argument does not reference a kernel thread.
 271 .El
 272 .Pp
 273 The
 274 .Fn kthread_add
 275 function will fail if:
 276 .Bl -tag -width Er
 277 .It Bq Er EAGAIN
 278 The system-imposed limit on the total
 279 number of processes under execution would be exceeded.
 280 The limit is given by the
 281 .Xr sysctl 3
 282 MIB variable
 283 .Dv KERN_MAXPROC .
 284 .It Bq Er EINVAL
 285 The
 286 .Dv RFCFDG
 287 flag was specified in the
 288 .Fa flags
 289 parameter.
 290 .El
 291 .Sh SEE ALSO
 292 .Xr rfork 2 ,
 293 .Xr exit1 9 ,
 294 .Xr kproc 9 ,
 295 .Xr SYSINIT 9 ,
 296 .Xr wakeup 9
 297 .Sh HISTORY
 298 The
 299 .Fn kthread_start
 300 function first appeared in
 301 .Fx 2.2
 302 where it created a whole process.
 303 It was converted to create threads in
 304 .Fx 8.0 .
 305 The
 306 .Fn kthread_shutdown ,
 307 .Fn kthread_exit ,
 308 .Fn kthread_resume ,
 309 .Fn kthread_suspend ,
 310 and
 311 .Fn kthread_suspend_check
 312 functions were introduced in
 313 .Fx 4.0
 314 and were converted to threads in
 315 .Fx 8.0 .
 316 The
 317 .Fn kthread_create
 318 call was renamed to
 319 .Fn kthread_add
 320 in
 321 .Fx 8.0 .
 322 The old functionality of creating a kernel process was renamed
 323 to
 324 .Xr kproc_create 9 .
 325 Prior to
 326 .Fx 5.0 ,
 327 the
 328 .Fn kthread_shutdown ,
 329 .Fn kthread_resume ,
 330 .Fn kthread_suspend ,
 331 and
 332 .Fn kthread_suspend_check
 333 functions were named
 334 .Fn shutdown_kproc ,
 335 .Fn resume_kproc ,
 336 .Fn shutdown_kproc ,
 337 and
 338 .Fn kproc_suspend_loop ,
 339 respectively.