1.\" $NetBSD: kthread.9,v 1.17 2008/04/30 13:10:58 martin Exp $ 2.\" 3.\" Copyright (c) 2000, 2007 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 November 22, 2007 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.It Fa ci 88If non-NULL, the thread will be created bound to the CPU specified 89by 90.Fa ci , 91meaning that it will only ever execute on that CPU. 92By default, the threads are free to execute on any CPU in the system. 93.It Fa func 94A function to be called when the thread begins executing. 95This function must not return. 96If the thread runs to completion, it must call 97.Fn kthread_exit 98to properly terminate itself. 99.It Fa arg 100An argument to be passed to 101.Fn func . 102May be NULL if not required. 103.It Fa newpl 104A pointer to receive the new lwp structure for the kernel thread. 105May be NULL if not required. 106.It Fa fmt 107A string containing format information used to display the kernel 108thread name. 109Must not be NULL. 110.El 111.It Fn kthread_destroy "l" 112From another thread executing in the kernel, cause a kthread to exit. 113The kthread must be in the 114.Dv LSIDL 115(idle) state. 116.It Fn kthread_exit "ecode" 117Exit from a kernel thread. 118Must only be called by a kernel thread. 119.El 120.Sh RETURN VALUES 121Upon successful completion, 122.Fn kthread_create 123returns 0. 124Otherwise, the following error values are returned: 125.Bl -tag -width [EAGAIN] 126.It Bq Er EAGAIN 127The limit on the total number of system processes would be exceeded. 128.It Bq Er EAGAIN 129The limit 130.Dv RLIMIT_NPROC 131on the total number of processes under execution by this 132user id would be exceeded. 133.El 134.Sh CODE REFERENCES 135This section describes places within the 136.Nx 137source tree where actual code implementing or using the kthread 138framework can be found. 139All pathnames are relative to 140.Pa /usr/src . 141.Pp 142The kthread framework itself is implemented within the file 143.Pa sys/kern/kern_kthread.c . 144Data structures and function prototypes for the framework are located in 145.Pa sys/sys/kthread.h . 146.Sh SEE ALSO 147.Xr driver 9 148.Sh HISTORY 149The kthread framework appeared in 150.Nx 1.4 . 151