1.\" $NetBSD: kthread.9,v 1.23 2010/05/13 13:04:56 jruoho 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 May 13, 2010 31.Dt KTHREAD 9 32.Os 33.Sh NAME 34.Nm kthread_create , 35.Nm kthread_destroy , 36.Nm kthread_exit , 37.Nm kthread_join 38.Nd kernel threads 39.Sh SYNOPSIS 40.In sys/kthread.h 41.Ft int 42.Fn kthread_create "pri_t pri" "int flags" "struct cpu_info *ci" \ 43"void (*func)(void *)" "void *arg" "lwp_t **newlp" "const char *fmt" "..." 44.Ft void 45.Fn kthread_destroy "lwp_t *l" 46.Ft void 47.Fn kthread_exit "int ecode" 48.Ft int 49.Fn kthread_join "lwp_t *l" 50.Sh DESCRIPTION 51Kernel threads are light-weight processes which execute entirely 52within the kernel. 53.Pp 54Any process can request the creation of a new kernel thread. 55Kernel threads are not swapped out during memory congestion. 56The VM space and limits are shared with proc0 (usually swapper). 57.Sh FUNCTIONS 58.Bl -tag -width compact 59.It Fn kthread_create "pri" "flags" "ci" "func" "arg" "newlp" "fmt" "..." 60Create a kernel thread. 61The arguments are as follows. 62.Bl -tag -width compact 63.It Fa pri 64Priority level for the thread. 65If no priority level is desired specify 66.Dv PRI_NONE , 67causing 68.Fn kthread_create 69to select the default priority level. 70.It Fa flags 71Flags that can be logically ORed together to alter the thread's behaviour. 72.It Fa ci 73If 74.No non- Ns Dv NULL , 75the thread will be created bound to the CPU specified by 76.Fa ci , 77meaning that it will only ever execute on that CPU. 78By default, the threads are free to execute on any CPU in the system. 79.It Fa func 80A function to be called when the thread begins executing. 81This function must not return. 82If the thread runs to completion, it must call 83.Fn kthread_exit 84to properly terminate itself. 85.It Fa arg 86An argument to be passed to 87.Fn func . 88May be 89.Dv NULL 90if not required. 91.It Fa newlp 92A pointer to receive the new lwp structure for the kernel thread. 93May not be 94.Dv NULL 95if 96.Dv KTHREAD_JOINABLE 97is specified in 98.Fa flags ; 99otherwise may be 100.Dv NULL 101if not required. 102.It Fa fmt 103A string containing format information used to display the kernel 104thread name. 105Must not be 106.Dv NULL . 107.El 108.Pp 109The following 110.Va flags 111are defined. 112.Bl -tag -width KTHREAD_JOINABLE 113.It Dv KTHREAD_IDLE 114Causes the thread to be created in the 115.Dv LSIDL 116(idle) state. 117By default, the threads are created in the 118.Dv LSRUN 119(runnable) state, meaning they will begin execution shortly after creation. 120.It Dv KTHREAD_MPSAFE 121Specifies that the thread does its own locking and so is multiprocessor safe. 122If not specified, the global kernel lock will be held whenever the thread is 123running (unless explicitly dropped by the thread). 124.It Dv KTHREAD_INTR 125Specifies that the thread services device interrupts. 126This flag is intended for kernel internal use and should not normally be 127specified. 128.It Dv KTHREAD_TS 129Causes the kthread to be created in the 130.Dv SCHED_OTHER 131class (timeshared). 132The threads' priority will be dynamically adjusted by the scheduler. 133Increased activity by the kthread will cause its priority to fall; 134decreased activity will cause its priority to rise. 135By default, kthreads are created in the 136.Dv SCHED_RR 137class, with a fixed 138priority specified by 139.Ar pri . 140Threads in the 141.Dv SCHED_RR 142class do not have their priority dynamically 143adjusted by the scheduler. 144.It Dv KTHREAD_JOINABLE 145Requests creation of joinable kthread. 146When this flag is specified, the 147.Fn kthread_join 148function can be called only once for the lwp structure returned in 149.Fa newlp . 150.El 151.It Fn kthread_destroy "l" 152From another thread executing in the kernel, cause a kthread to exit. 153The kthread must be in the 154.Dv LSIDL 155(idle) state. 156.It Fn kthread_exit "ecode" 157Exit from a kernel thread. 158Must only be called by a kernel thread. 159.It Fn kthread_join "l" 160Suspend execution of the LWP until the target kthread terminates. 161Conceptually the function can be compared to the user space 162.Xr pthread_join 3 . 163.El 164.Sh RETURN VALUES 165Upon successful completion, 166.Fn kthread_create 167returns 0. 168Otherwise, the following error values are returned: 169.Bl -tag -width [EAGAIN] 170.It Bq Er EAGAIN 171The limit on the total number of system processes would be exceeded. 172.It Bq Er EAGAIN 173The limit 174.Dv RLIMIT_NPROC 175on the total number of processes under execution by this 176user id would be exceeded. 177.El 178.Sh CODE REFERENCES 179This section describes places within the 180.Nx 181source tree where actual code implementing or using the kthread 182framework can be found. 183All pathnames are relative to 184.Pa /usr/src . 185.Pp 186The kthread framework itself is implemented within the file 187.Pa sys/kern/kern_kthread.c . 188Data structures and function prototypes for the framework are located in 189.Pa sys/sys/kthread.h . 190.Sh SEE ALSO 191.Xr condvar 9 , 192.Xr driver 9 , 193.Xr softint 9 , 194.Xr workqueue 9 195.Sh HISTORY 196The kthread framework appeared in 197.Nx 1.4 . 198