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 September 24, 2004
  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 While exiting, the function
 145 .Xr exit1 9
 146 will initiate a call to
 147 .Xr wakeup 9
 148 on the thread handle.
 149 .Pp
 150 The
 151 .Fn kthread_resume ,
 152 .Fn kthread_suspend ,
 153 and
 154 .Fn kthread_suspend_check
 155 functions are used to suspend and resume a kernel thread.
 156 During the main loop of its execution, a kernel thread that wishes to allow
 157 itself to be suspended should call
 158 .Fn kthread_suspend_check
 159 passing in
 160 .Va curproc
 161 as the only argument.
 162 This function checks to see if the kernel thread has been asked to suspend.
 163 If it has, it will
 164 .Xr tsleep 9
 165 until it is told to resume.
 166 Once it has been told to resume it will return allowing execution of the
 167 kernel thread to continue.
 168 The other two functions are used to notify a kernel thread of a suspend or
 169 resume request.
 170 The
 171 .Fa p
 172 argument points to the
 173 .Li struct proc
 174 of the kernel thread to suspend or resume.
 175 For
 176 .Fn kthread_suspend ,
 177 the
 178 .Fa timo
 179 argument specifies a timeout to wait for the kernel thread to acknowledge the
 180 suspend request and suspend itself.
 181 .Pp
 182 The
 183 .Fn kproc_shutdown
 184 function is meant to be registered as a shutdown event for kernel threads that
 185 need to be suspended voluntarily during system shutdown so as not to interfere
 186 with system shutdown activities.
 187 The actual suspension of the kernel thread is done with
 188 .Fn kthread_suspend .
 189 .Sh RETURN VALUES
 190 The
 191 .Fn kthread_create ,
 192 .Fn kthread_resume ,
 193 and
 194 .Fn kthread_suspend
 195 functions return zero on success and non-zero on failure.
 196 .Sh EXAMPLES
 197 This example demonstrates the use of a
 198 .Li struct kproc_desc
 199 and the functions
 200 .Fn kproc_start ,
 201 .Fn kproc_shutdown ,
 202 and
 203 .Fn kthread_suspend_check
 204 to run the
 205 .Dq bufdaemon
 206 process.
 207 .Bd -literal -offset indent
 208 static struct proc *bufdaemonproc;
 209
 210 static struct kproc_desc buf_kp = {
 211         "bufdaemon",
 212         buf_daemon,
 213         &bufdaemonproc
 214 };
 215 SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start,
 216     &buf_kp)
 217
 218 static void
 219 buf_daemon()
 220 {
 221         ...
 222         /*
 223          * This process needs to be suspended prior to shutdown sync.
 224          */
 225         EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown,
 226             bufdaemonproc, SHUTDOWN_PRI_LAST);
 227         ...
 228         for (;;) {
 229                 kthread_suspend_check(bufdaemonproc);
 230                 ...
 231         }
 232 }
 233 .Ed
 234 .Sh ERRORS
 235 The
 236 .Fn kthread_resume
 237 and
 238 .Fn kthread_suspend
 239 functions will fail if:
 240 .Bl -tag -width Er
 241 .It Bq Er EINVAL
 242 The
 243 .Fa p
 244 argument does not reference a kernel thread.
 245 .El
 246 .Pp
 247 The
 248 .Fn kthread_create
 249 function will fail if:
 250 .Bl -tag -width Er
 251 .It Bq Er EAGAIN
 252 The system-imposed limit on the total
 253 number of processes under execution would be exceeded.
 254 The limit is given by the
 255 .Xr sysctl 3
 256 MIB variable
 257 .Dv KERN_MAXPROC .
 258 .It Bq Er EINVAL
 259 The
 260 .Dv RFCFDG
 261 flag was specified in the
 262 .Fa flags
 263 parameter.
 264 .El
 265 .Sh SEE ALSO
 266 .Xr rfork 2 ,
 267 .Xr exit1 9 ,
 268 .Xr SYSINIT 9 ,
 269 .Xr wakeup 9
 270 .Sh HISTORY
 271 The
 272 .Fn kproc_start
 273 function first appeared in
 274 .Fx 2.2 .
 275 The
 276 .Fn kproc_shutdown ,
 277 .Fn kthread_create ,
 278 .Fn kthread_exit ,
 279 .Fn kthread_resume ,
 280 .Fn kthread_suspend ,
 281 and
 282 .Fn kthread_suspend_check
 283 functions were introduced in
 284 .Fx 4.0 .
 285 Prior to
 286 .Fx 5.0 ,
 287 the
 288 .Fn kproc_shutdown ,
 289 .Fn kthread_resume ,
 290 .Fn kthread_suspend ,
 291 and
 292 .Fn kthread_suspend_check
 293 functions were named
 294 .Fn shutdown_kproc ,
 295 .Fn resume_kproc ,
 296 .Fn shutdown_kproc ,
 297 and
 298 .Fn kproc_suspend_loop ,
 299 respectively.