1.\" $NetBSD: kthread.9,v 1.27 2011/08/07 14:03:16 rmind 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 7, 2011 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 be 94.Dv NULL , 95unless 96.Dv KTHREAD_MUSTJOIN 97is specified in 98.Fa flags . 99.It Fa fmt 100A string containing format information used to display the kernel 101thread name. 102Must not be 103.Dv NULL . 104.El 105.Pp 106The following 107.Va flags 108are defined. 109.Bl -tag -width KTHREAD_MUSTJOIN 110.It Dv KTHREAD_IDLE 111Causes the thread to be created in the 112.Dv LSIDL 113(idle) state. 114By default, the threads are created in the 115.Dv LSRUN 116(runnable) state, meaning they will begin execution shortly after creation. 117.It Dv KTHREAD_MPSAFE 118Specifies that the thread does its own locking and so is multiprocessor safe. 119If not specified, the global kernel lock will be held whenever the thread is 120running (unless explicitly dropped by the thread). 121.It Dv KTHREAD_INTR 122Specifies that the thread services device interrupts. 123This flag is intended for kernel internal use and should not normally be 124specified. 125.It Dv KTHREAD_TS 126Causes the kthread to be created in the 127.Dv SCHED_OTHER 128class (timeshared). 129The thread's priority will be dynamically adjusted by the scheduler. 130Increased activity by the kthread will cause its priority to fall; 131decreased activity will cause its priority to rise. 132By default, kthreads are created in the 133.Dv SCHED_RR 134class, with a fixed 135priority specified by 136.Ar pri . 137Threads in the 138.Dv SCHED_RR 139class do not have their priority dynamically 140adjusted by the scheduler. 141.It Dv KTHREAD_MUSTJOIN 142Indicates that created kthread must be joined. 143In such case 144.Fn kthread_exit 145will wait until 146.Fn kthread_join 147will be called. 148.El 149.It Fn kthread_destroy "l" 150From another thread executing in the kernel, cause a kthread to exit. 151The kthread must be in the 152.Dv LSIDL 153(idle) state. 154.It Fn kthread_exit "ecode" 155Exit from a kernel thread. 156Must only be called by a kernel thread. 157.It Fn kthread_join "l" 158Suspend execution of calling thread until the target kthread terminates. 159Conceptually the function can be compared to the user space 160.Xr pthread_join 3 , 161however it must be called only once for kernel thread which was 162created using the 163.Dv KTHREAD_MUSTJOIN 164flag and would wait on 165.Fa kthread_exit . 166.El 167.Sh RETURN VALUES 168Upon successful completion, 169.Fn kthread_create 170returns 0. 171Otherwise, the following error values are returned: 172.Bl -tag -width [EAGAIN] 173.It Bq Er EAGAIN 174The limit on the total number of system processes would be exceeded. 175.It Bq Er EAGAIN 176The limit 177.Dv RLIMIT_NPROC 178on the total number of processes under execution by this 179user id would be exceeded. 180.El 181.Sh CODE REFERENCES 182The kthread framework itself is implemented within the file 183.Pa sys/kern/kern_kthread.c . 184Data structures and function prototypes for the framework are located in 185.Pa sys/sys/kthread.h . 186.Sh SEE ALSO 187.Xr condvar 9 , 188.Xr driver 9 , 189.Xr softint 9 , 190.Xr workqueue 9 191.Sh HISTORY 192The kthread framework appeared in 193.Nx 1.4 . 194