share/man/man9/kthread.9

   1 .\"     $NetBSD: kthread.9,v 1.19 2009/01/29 22:33:31 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2000, 2007, 2008 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Gregory McGarry, and by Andrew Doran.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd August 3, 2009
  31 .Dt KTHREAD 9
  32 .Os
  33 .Sh NAME
  34 .Nm kthread_create ,
  35 .Nm kthread_destroy ,
  36 .Nm kthread_exit
  37 .Nd kernel threads
  38 .Sh SYNOPSIS
  39 .In sys/kthread.h
  40 .Ft int
  41 .Fn kthread_create "pri_t pri" "int flags" "struct cpu_info *ci" \
  42 "void (*func)(void *)" "void *arg" "lwp_t **newlp" "const char *fmt" "..."
  43 .Ft void
  44 .Fn kthread_destroy "lwp_t *l"
  45 .Ft void
  46 .Fn kthread_exit "int ecode"
  47 .Sh DESCRIPTION
  48 Kernel threads are light-weight processes which execute entirely
  49 within the kernel.
  50 .Pp
  51 Any process can request the creation of a new kernel thread.
  52 Kernel threads are not swapped out during memory congestion.
  53 The VM space and limits are shared with proc0 (usually swapper).
  54 .Sh FUNCTIONS
  55 .Bl -tag -width compact
  56 .It Fn kthread_create "pri" "flags" "ci" "func" "arg" "newlp" "fmt" "..."
  57 Create a kernel thread.
  58 The arguments are as follows.
  59 .Bl -tag -width compact
  60 .It Fa pri
  61 Priority level for the thread.
  62 If no priority level is desired specify
  63 .Dv PRI_NONE ,
  64 causing
  65 .Fn kthread_create
  66 to select the default priority level.
  67 .It Fa flags
  68 Flags that can be logically ORed together to alter the thread's behaviour.
  69 .Pp
  70 .Dv KTHREAD_IDLE :
  71 causes the thread to be created in the
  72 .Dv LSIDL
  73 (idle) state.
  74 By default, the threads are created in the
  75 .Dv LSRUN
  76 (runnable) state, meaning they will begin execution shortly after creation.
  77 .Pp
  78 .Dv KTHREAD_MPSAFE :
  79 Specifies that the thread does its own locking and so is multiprocessor safe.
  80 If not specified, the global kernel lock will be held whenever the thread is
  81 running (unless explicitly dropped by the thread).
  82 .Pp
  83 .Dv KTHREAD_INTR :
  84 Specifies that the thread services device interrupts.
  85 This flag is intended for kernel internal use and should not normally be
  86 specified.
  87 .Pp
  88 .Dv KTHREAD_TS :
  89 Causes the kthread to be created in the
  90 .Dv SCHED_OTHER
  91 class (timeshared).
  92 The threads' priority will be dynamically adjusted by the scheduler.
  93 Increased activity by the kthread will cause its priority to fall;
  94 decreased activity will cause its priority to rise.
  95 By default, kthreads are created in the
  96 .Dv SCHED_RR
  97 class, with a fixed
  98 priority specified by
  99 .Ar pri .
 100 Threads in the
 101 .Dv SCHED_RR
 102 class do not have their priority dynamically
 103 adjusted by the scheduler.
 104 .It Fa ci
 105 If
 106 .No non- Ns Dv NULL ,
 107 the thread will be created bound to the CPU specified by
 108 .Fa ci ,
 109 meaning that it will only ever execute on that CPU.
 110 By default, the threads are free to execute on any CPU in the system.
 111 .It Fa func
 112 A function to be called when the thread begins executing.
 113 This function must not return.
 114 If the thread runs to completion, it must call
 115 .Fn kthread_exit
 116 to properly terminate itself.
 117 .It Fa arg
 118 An argument to be passed to
 119 .Fn func .
 120 May be
 121 .Dv NULL
 122 if not required.
 123 .It Fa newpl
 124 A pointer to receive the new lwp structure for the kernel thread.
 125 May be
 126 .Dv NULL
 127 if not required.
 128 .It Fa fmt
 129 A string containing format information used to display the kernel
 130 thread name.
 131 Must not be
 132 .Dv NULL .
 133 .El
 134 .It Fn kthread_destroy "l"
 135 From another thread executing in the kernel, cause a kthread to exit.
 136 The kthread must be in the
 137 .Dv LSIDL
 138 (idle) state.
 139 .It Fn kthread_exit "ecode"
 140 Exit from a kernel thread.
 141 Must only be called by a kernel thread.
 142 .El
 143 .Sh RETURN VALUES
 144 Upon successful completion,
 145 .Fn kthread_create
 146 returns 0.
 147 Otherwise, the following error values are returned:
 148 .Bl -tag -width [EAGAIN]
 149 .It Bq Er EAGAIN
 150 The limit on the total number of system processes would be exceeded.
 151 .It Bq Er EAGAIN
 152 The limit
 153 .Dv RLIMIT_NPROC
 154 on the total number of processes under execution by this
 155 user id would be exceeded.
 156 .El
 157 .Sh CODE REFERENCES
 158 This section describes places within the
 159 .Nx
 160 source tree where actual code implementing or using the kthread
 161 framework can be found.
 162 All pathnames are relative to
 163 .Pa /usr/src .
 164 .Pp
 165 The kthread framework itself is implemented within the file
 166 .Pa sys/kern/kern_kthread.c .
 167 Data structures and function prototypes for the framework are located in
 168 .Pa sys/sys/kthread.h .
 169 .Sh SEE ALSO
 170 .Xr condvar 9 ,
 171 .Xr driver 9 ,
 172 .Xr softint 9 ,
 173 .Xr workqueue 9
 174 .Sh HISTORY
 175 The kthread framework appeared in
 176 .Nx 1.4 .