KTHREAD(9)

KTHREAD(9) | Kernel Developer's Manual | KTHREAD(9)

# NAME

`kthread_create`, `kthread_exit`, `kthread_join`, `kthread_fpu_enter`, `kthread_fpu_exit` —
kernel threads

# SYNOPSIS

`#include <sys/kthread.h>`

int
`kthread_create`(pri_t pri, int flags, struct cpu_info *ci, void (*func)(void *), void *arg, lwp_t **newlp, const char *fmt, ...);

void
`kthread_exit`(int ecode);

int
`kthread_join`(lwp_t *l);

int
`kthread_fpu_enter`();

void
`kthread_fpu_exit`(int s);

# DESCRIPTION

Kernel threads are light-weight processes which execute entirely within the kernel.

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).

If the machine has any per-CPU floating-point units or SIMD vector units that are normally available to user threads, they can be used by kthreads between `kthread_fpu_enter`() and `kthread_fpu_exit`().

# FUNCTIONS

`kthread_create`(pri, flags, ci, func, arg, newlp, fmt, ...)
  Create a kernel thread. The arguments are as follows.
  pri
    Priority level for the thread. If no priority level is desired specify `PRI_NONE`, causing `kthread_create`() to select the default priority level.
  flags
    Flags that can be logically ORed together to alter the thread's behaviour.
  ci
    If non-`NULL`, the thread will be created bound to the CPU specified by 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.
  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 `kthread_exit`() to properly terminate itself.
  arg
    An argument to be passed to `func`(). May be `NULL` if not required.
  newlp
    A pointer to receive the new LWP structure for the kernel thread. May be `NULL`, unless `KTHREAD_MUSTJOIN` is specified in flags.
  fmt
    A string containing format information used to display the kernel thread name. Must not be `NULL`.

  The following flags are defined.

  `KTHREAD_IDLE`
    Causes the thread to be created in the `LSIDL` (idle) state. By default, the threads are created in the `LSRUN` (runnable) state, meaning they will begin execution shortly after creation.
  `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).
  `KTHREAD_INTR`
    Specifies that the thread services device interrupts. This flag is intended for kernel internal use and should not normally be specified.
  `KTHREAD_TS`
    Causes the kthread to be created in the `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 `SCHED_RR` class, with a fixed priority specified by pri. Threads in the `SCHED_RR` class do not have their priority dynamically adjusted by the scheduler.
  `KTHREAD_MUSTJOIN`
    Indicates that created kthread must be joined. In such case `kthread_exit`() will wait until `kthread_join`() will be called.
`kthread_exit`(ecode)
  Exit from a kernel thread. Must only be called by a kernel thread.
`kthread_join`(l)
  Suspend execution of calling thread until the target kthread terminates. Conceptually the function can be compared to the user space pthread_join(3), however it must be called only once for kernel thread which was created using the `KTHREAD_MUSTJOIN` flag and would wait on kthread_exit.
`kthread_fpu_enter`()
  Allow the current kthread to use any machine-dependent per-CPU floating-point units or SIMD vector units normally available to user threads. Returns a cookie that must be passed to `kthread_fpu_exit`() when done.

  Matching pairs of `kthread_fpu_enter`() and `kthread_fpu_exit`() may be nested.

`kthread_fpu_exit`(s)
  Restore the current kthread's access to machine-dependent per-CPU floating-point units or SIMD vector units to what it was before the call to `kthread_fpu_enter`() that returned s.

  On the last `kthread_fpu_exit`(), zero all the units' registers to avoid leaking secrets — such units are often used for cryptography.

# RETURN VALUES

Upon successful completion, `kthread_create`() returns 0. Otherwise, the following error values are returned:

[`EAGAIN`]
  The limit on the total number of system processes would be exceeded; or the limit `RLIMIT_NPROC` on the total number of processes under execution by this user id would be exceeded.

# CODE REFERENCES

The kthread framework itself is implemented within the file sys/kern/kern_kthread.c. Data structures and function prototypes for the framework are located in sys/sys/kthread.h.

# SEE ALSO

condvar(9), driver(9), softint(9), workqueue(9)

# HISTORY

The kthread framework appeared in NetBSD 1.4.

April 21, 2015 | NetBSD 10.0