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