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 24, 2010
  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 "void"
  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 in order to check if the it has been asked to suspend.
 212 If it has, it will
 213 .Xr msleep 9
 214 until it is told to resume.
 215 Once it has been told to resume it will return allowing execution of the
 216 kernel thread to continue.
 217 The other two functions are used to notify a kernel thread of a suspend or
 218 resume request.
 219 The
 220 .Fa td
 221 argument points to the
 222 .Vt "struct thread"
 223 of the kernel thread to suspend or resume.
 224 For
 225 .Fn kthread_suspend ,
 226 the
 227 .Fa timo
 228 argument specifies a timeout to wait for the kernel thread to acknowledge the
 229 suspend request and suspend itself.
 230 .Pp
 231 The
 232 .Fn kthread_shutdown
 233 function is meant to be registered as a shutdown event for kernel threads that
 234 need to be suspended voluntarily during system shutdown so as not to interfere
 235 with system shutdown activities.
 236 The actual suspension of the kernel thread is done with
 237 .Fn kthread_suspend .
 238 .Sh RETURN VALUES
 239 The
 240 .Fn kthread_add ,
 241 .Fn kthread_resume ,
 242 and
 243 .Fn kthread_suspend
 244 functions return zero on success and non-zero on failure.
 245 .Sh EXAMPLES
 246 This example demonstrates the use of a
 247 .Vt "struct kthread_desc"
 248 and the functions
 249 .Fn kthread_start ,
 250 .Fn kthread_shutdown ,
 251 and
 252 .Fn kthread_suspend_check
 253 to run the
 254 .Nm bufdaemon
 255 process.
 256 .Bd -literal -offset indent
 257 static struct thread *bufdaemonthread;
 258
 259 static struct kthread_desc buf_kp = {
 260         "bufdaemon",
 261         buf_daemon,
 262         &bufdaemonthread
 263 };
 264 SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kthread_start,
 265     &buf_kp)
 266
 267 static void
 268 buf_daemon()
 269 {
 270         ...
 271         /*
 272          * This process needs to be suspended prior to shutdown sync.
 273          */
 274         EVENTHANDLER_REGISTER(shutdown_pre_sync, kthread_shutdown,
 275             bufdaemonthread, SHUTDOWN_PRI_LAST);
 276         ...
 277         for (;;) {
 278                 kthread_suspend_check(bufdaemonthread);
 279                 ...
 280         }
 281 }
 282 .Ed
 283 .Sh ERRORS
 284 The
 285 .Fn kthread_resume
 286 and
 287 .Fn kthread_suspend
 288 functions will fail if:
 289 .Bl -tag -width Er
 290 .It Bq Er EINVAL
 291 The
 292 .Fa td
 293 argument does not reference a kernel thread.
 294 .El
 295 .Pp
 296 The
 297 .Fn kthread_add
 298 function will fail if:
 299 .Bl -tag -width Er
 300 .It Bq Er ENOMEM
 301 Memory for a thread's stack could not be allocated.
 302 .El
 303 .Sh SEE ALSO
 304 .Xr kproc 9 ,
 305 .Xr SYSINIT 9 ,
 306 .Xr wakeup 9
 307 .Sh HISTORY
 308 The
 309 .Fn kthread_start
 310 function first appeared in
 311 .Fx 2.2
 312 where it created a whole process.
 313 It was converted to create threads in
 314 .Fx 8.0 .
 315 The
 316 .Fn kthread_shutdown ,
 317 .Fn kthread_exit ,
 318 .Fn kthread_resume ,
 319 .Fn kthread_suspend ,
 320 and
 321 .Fn kthread_suspend_check
 322 functions were introduced in
 323 .Fx 4.0
 324 and were converted to threads in
 325 .Fx 8.0 .
 326 The
 327 .Fn kthread_create
 328 call was renamed to
 329 .Fn kthread_add
 330 in
 331 .Fx 8.0 .
 332 The old functionality of creating a kernel process was renamed
 333 to
 334 .Xr kproc_create 9 .
 335 Prior to
 336 .Fx 5.0 ,
 337 the
 338 .Fn kthread_shutdown ,
 339 .Fn kthread_resume ,
 340 .Fn kthread_suspend ,
 341 and
 342 .Fn kthread_suspend_check
 343 functions were named
 344 .Fn shutdown_kproc ,
 345 .Fn resume_kproc ,
 346 .Fn shutdown_kproc ,
 347 and
 348 .Fn kproc_suspend_loop ,
 349 respectively.