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