.\"     $NetBSD: kthread.9,v 1.28 2015/04/21 11:10:29 pooka Exp $
.\"
.\" Copyright (c) 2000, 2007, 2008 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry, and by Andrew Doran.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 21, 2015
.Dt KTHREAD 9
.Os
.Sh NAME
.Nm kthread_create ,
.Nm kthread_exit ,
.Nm kthread_join
.Nd kernel threads
.Sh SYNOPSIS
.In sys/kthread.h
.Ft int
.Fn kthread_create "pri_t pri" "int flags" "struct cpu_info *ci" \
"void (*func)(void *)" "void *arg" "lwp_t **newlp" "const char *fmt" "..."
.Ft void
.Fn kthread_exit "int ecode"
.Ft int
.Fn kthread_join "lwp_t *l"
.Sh DESCRIPTION
Kernel threads are light-weight processes which execute entirely
within the kernel.
.Pp
Any process can request the creation of a new kernel thread.
Kernel threads are not swapped out during memory congestion.
The VM space and limits are shared with proc0 (usually swapper).
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn kthread_create "pri" "flags" "ci" "func" "arg" "newlp" "fmt" "..."
Create a kernel thread.
The arguments are as follows.
.Bl -tag -width compact
.It Fa pri
Priority level for the thread.
If no priority level is desired specify
.Dv PRI_NONE ,
causing
.Fn kthread_create
to select the default priority level.
.It Fa flags
Flags that can be logically ORed together to alter the thread's behaviour.
.It Fa ci
If
.No non- Ns Dv NULL ,
the thread will be created bound to the CPU specified by
.Fa ci ,
meaning that it will only ever execute on that CPU.
By default, the threads are free to execute on any CPU in the system.
.It Fa func
A function to be called when the thread begins executing.
This function must not return.
If the thread runs to completion, it must call
.Fn kthread_exit
to properly terminate itself.
.It Fa arg
An argument to be passed to
.Fn func .
May be
.Dv NULL
if not required.
.It Fa newlp
A pointer to receive the new LWP structure for the kernel thread.
May be
.Dv NULL ,
unless
.Dv KTHREAD_MUSTJOIN
is specified in
.Fa flags .
.It Fa fmt
A string containing format information used to display the kernel
thread name.
Must not be
.Dv NULL .
.El
.Pp
The following
.Va flags
are defined.
.Bl -tag -width KTHREAD_MUSTJOIN
.It Dv KTHREAD_IDLE
Causes the thread to be created in the
.Dv LSIDL
(idle) state.
By default, the threads are created in the
.Dv LSRUN
(runnable) state, meaning they will begin execution shortly after creation.
.It Dv KTHREAD_MPSAFE
Specifies that the thread does its own locking and so is multiprocessor safe.
If not specified, the global kernel lock will be held whenever the thread is
running (unless explicitly dropped by the thread).
.It Dv KTHREAD_INTR
Specifies that the thread services device interrupts.
This flag is intended for kernel internal use and should not normally be
specified.
.It Dv KTHREAD_TS
Causes the kthread to be created in the
.Dv SCHED_OTHER
class (timeshared).
The thread's priority will be dynamically adjusted by the scheduler.
Increased activity by the kthread will cause its priority to fall;
decreased activity will cause its priority to rise.
By default, kthreads are created in the
.Dv SCHED_RR
class, with a fixed
priority specified by
.Ar pri .
Threads in the
.Dv SCHED_RR
class do not have their priority dynamically
adjusted by the scheduler.
.It Dv KTHREAD_MUSTJOIN
Indicates that created kthread must be joined.
In such case
.Fn kthread_exit
will wait until
.Fn kthread_join
will be called.
.El
.It Fn kthread_exit "ecode"
Exit from a kernel thread.
Must only be called by a kernel thread.
.It Fn kthread_join "l"
Suspend execution of calling thread until the target kthread terminates.
Conceptually the function can be compared to the user space
.Xr pthread_join 3 ,
however it must be called only once for kernel thread which was
created using the
.Dv KTHREAD_MUSTJOIN
flag and would wait on
.Fa kthread_exit .
.El
.Sh RETURN VALUES
Upon successful completion,
.Fn kthread_create
returns 0.
Otherwise, the following error values are returned:
.Bl -tag -width [EAGAIN]
.It Bq Er EAGAIN
The limit on the total number of system processes would be exceeded.
.It Bq Er EAGAIN
The limit
.Dv RLIMIT_NPROC
on the total number of processes under execution by this
user id would be exceeded.
.El
.Sh CODE REFERENCES
The kthread framework itself is implemented within the file
.Pa sys/kern/kern_kthread.c .
Data structures and function prototypes for the framework are located in
.Pa sys/sys/kthread.h .
.Sh SEE ALSO
.Xr condvar 9 ,
.Xr driver 9 ,
.Xr softint 9 ,
.Xr workqueue 9
.Sh HISTORY
The kthread framework appeared in
.Nx 1.4 .