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