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