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 January 27, 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 48Kernel threads are light-weight processes which execute entirely 49within the kernel. 50.Pp 51Any process can request the creation of a new kernel thread. 52Kernel threads are not swapped out during memory congestion. 53The 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" "..." 57Create a kernel thread. 58The arguments are as follows. 59.Bl -tag -width compact 60.It Fa pri 61Priority level for the thread. 62If no priority level is desired specify 63.Dv PRI_NONE , 64causing 65.Fn kthread_create 66to select the default priority level. 67.It Fa flags 68Flags that can be logically ORed together to alter the thread's behaviour. 69.Pp 70.Dv KTHREAD_IDLE : 71causes the thread to be created in the 72.Dv LSIDL 73(idle) state. 74By 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 : 79Specifies that the thread does its own locking and so is multiprocessor safe. 80If not specified, the global kernel lock will be held whenever the thread is 81running (unless explicitly dropped by the thread). 82.Pp 83.Dv KTHREAD_INTR : 84Specifies that the thread services device interrupts. 85This flag is intended for kernel internal use and should not normally be 86specified. 87.Pp 88.Dv KTHREAD_TS : 89Causes the kthread to be created in the 90.Dv SCHED_OTHER 91class (timeshared). 92The threads' priority will be dynamically adjusted by the scheduler. 93Increased activity by the kthread will cause its priority to fall; 94decreased activity will cause its priority to rise. 95By default, kthreads are created in the 96.Dv SCHED_RR 97class, with a fixed 98priority specified by 99.Ar pri . 100Threads in the 101.Dv SCHED_RR 102class do not have their priority dynamically 103adjusted by the scheduler. 104.It Fa ci 105If 106.No non- Ns Dv NULL , 107the thread will be created bound to the CPU specified by 108.Fa ci , 109meaning that it will only ever execute on that CPU. 110By default, the threads are free to execute on any CPU in the system. 111.It Fa func 112A function to be called when the thread begins executing. 113This function must not return. 114If the thread runs to completion, it must call 115.Fn kthread_exit 116to properly terminate itself. 117.It Fa arg 118An argument to be passed to 119.Fn func . 120May be 121.Dv NULL 122if not required. 123.It Fa newpl 124A pointer to receive the new lwp structure for the kernel thread. 125May be 126.Dv NULL 127if not required. 128.It Fa fmt 129A string containing format information used to display the kernel 130thread name. 131Must not be 132.Dv NULL . 133.El 134.It Fn kthread_destroy "l" 135From another thread executing in the kernel, cause a kthread to exit. 136The kthread must be in the 137.Dv LSIDL 138(idle) state. 139.It Fn kthread_exit "ecode" 140Exit from a kernel thread. 141Must only be called by a kernel thread. 142.El 143.Sh RETURN VALUES 144Upon successful completion, 145.Fn kthread_create 146returns 0. 147Otherwise, the following error values are returned: 148.Bl -tag -width [EAGAIN] 149.It Bq Er EAGAIN 150The limit on the total number of system processes would be exceeded. 151.It Bq Er EAGAIN 152The limit 153.Dv RLIMIT_NPROC 154on the total number of processes under execution by this 155user id would be exceeded. 156.El 157.Sh CODE REFERENCES 158This section describes places within the 159.Nx 160source tree where actual code implementing or using the kthread 161framework can be found. 162All pathnames are relative to 163.Pa /usr/src . 164.Pp 165The kthread framework itself is implemented within the file 166.Pa sys/kern/kern_kthread.c . 167Data structures and function prototypes for the framework are located in 168.Pa sys/sys/kthread.h . 169.Sh SEE ALSO 170.Xr driver 9 171.Sh HISTORY 172The kthread framework appeared in 173.Nx 1.4 . 174