kthread(9) - NetBSD Manual Pages

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


NAME

     kthread_create, kthread_destroy, kthread_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_destroy(lwp_t *l);

     void
     kthread_exit(int ecode);


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


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.

                       KTHREAD_IDLE: causes the thread to be created in the
                       LSIDL (idle) state.  By default, the threads are cre-
                       ated 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 speci-
                       fied, 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 threads' priority
                       will be dynamically adjusted by the scheduler.
                       Increased activity by the kthread will cause its prior-
                       ity 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 prior-
                       ity dynamically adjusted by the scheduler.

              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 execut-
                       ing.  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.

              newpl    A pointer to receive the new lwp structure for the ker-
                       nel thread.  May be NULL if not required.

              fmt      A string containing format information used to display
                       the kernel thread name.  Must not be NULL.

     kthread_destroy(l)
              From another thread executing in the kernel, cause a kthread to
              exit.  The kthread must be in the LSIDL (idle) state.

     kthread_exit(ecode)
              Exit from a kernel thread.  Must only be called by a kernel
              thread.


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.

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


CODE REFERENCES

     This section describes places within the NetBSD source tree where actual
     code implementing or using the kthread framework can be found.  All path-
     names are relative to /usr/src.

     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

     driver(9)


HISTORY

     The kthread framework appeared in NetBSD 1.4.

NetBSD 5.0.1                   January 27, 2009                   NetBSD 5.0.1