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