207 lines
5.6 KiB
Groff
207 lines
5.6 KiB
Groff
.\" $NetBSD: kcont.9,v 1.9 2005/11/24 08:24:01 yamt Exp $
|
|
.\"
|
|
.\" The author of this man page is Jonathan Stone (jonathan@dsg.stanford.edu)
|
|
.\"
|
|
.\" Copyright (c) 2003, 2004 Jonathan STone
|
|
.\"
|
|
.\" Permission to use, copy, and modify this software with or without fee
|
|
.\" is hereby granted, provided that this entire notice is included in
|
|
.\" all source code copies of any software which is or includes a copy or
|
|
.\" modification of this software.
|
|
.\"
|
|
.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY
|
|
.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
|
|
.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
|
|
.\" PURPOSE.
|
|
.\"
|
|
.\"
|
|
.\"
|
|
.Dd November 17, 2005
|
|
.Dt KCONT 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm kcont
|
|
.Nd continuation-passing framework for deferring execution and for
|
|
notification of asynchronous events
|
|
.Sh SYNOPSIS
|
|
.In sys/kcont.h
|
|
.\"
|
|
.Ft struct kc *
|
|
.Fo kcont
|
|
.Fa "struct kc *"
|
|
.Fa "void (*fn) (void *kernel_obj, void *env_arg, int status)"
|
|
.Fa "void *env_arg"
|
|
.Fa "int desired_ipl"
|
|
.Fc
|
|
.\"
|
|
.Ft struct kc *
|
|
.Fo kcont_malloc
|
|
.Fa "int mallocflags"
|
|
.Fa "void (*fn) (void *kernel_obj, void *env_arg, int status)"
|
|
.Fa "void *env_arg"
|
|
.Fa "int desired_ipl"
|
|
.Fc
|
|
.\"
|
|
.Ft void
|
|
.Fo kcont_defer
|
|
.Fa "struct kc *kc"
|
|
.Fa "void (*fn) (void *kernel_obj, void *env_arg, int status)"
|
|
.Fa "void *kernel_obj"
|
|
.Fa "void *env_arg"
|
|
.Fa "int status"
|
|
.Fa "int desired_ipl"
|
|
.Fc
|
|
.Ft void
|
|
.Fo kcont_defer_malloc
|
|
.Fa "int mallocflags"
|
|
.Fa "void (*fn) (void *kernel_obj, void *env_arg, int status)"
|
|
.Fa "void *kernel_obj"
|
|
.Fa "void *env_arg"
|
|
.Fa "int status"
|
|
.Fa "int desired_ipl"
|
|
.Fc
|
|
.\"
|
|
.Ft void
|
|
.Fn kcont_enqueue "struct kcq *kcont_queue" "struct kc* kcont"
|
|
.\" "void (*fn) (void *kernel_obj, void *env_arg, int status)" "void *env_arg" "int desired_ipl"
|
|
.Ft void
|
|
.Fn kcont_run "kcq_t *kcq" "void *obj" "int status" "int curipl"
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
provides a method of asynchronous notification of kernel events
|
|
(such as I/O completion events) loosely modelled on the
|
|
continuation-passing model associated with functional languages such as
|
|
Scheme.
|
|
In the context of C and Unix kernels, a continuation can
|
|
be thought of as a combination of three items:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
a function pointer, or
|
|
.Dq callback
|
|
function;
|
|
.It
|
|
an argument (or arguments) to that function; and
|
|
.It
|
|
other
|
|
.Dq environment
|
|
state which is passed into the function.
|
|
.El
|
|
.Pp
|
|
The continuations supported by
|
|
.Nm
|
|
can be used to defer execution from a high-priority context
|
|
(such as a hardware-priority interrupt handler) to a lower-priority
|
|
context (such as a software-interrupt callout queue specifically for
|
|
executing
|
|
.Nm
|
|
functions).
|
|
The
|
|
.Nm
|
|
mechanism can also be used to deliver notification of asynchronous
|
|
events, such as I/O completion.
|
|
.Sh TRADITIONAL I/O COMPLETION NOTIFICATION
|
|
The traditional Unix methods for asynchronous notification are
|
|
.Xr ltsleep 9 ,
|
|
.Xr tsleep 9 ,
|
|
and
|
|
.Xr wakeup 9 ,
|
|
which assume the operation or I/O request are being issued from process
|
|
context.
|
|
Once the I/O operation is actually issued, the requesting process
|
|
is suspended by issuing a
|
|
.Xr tsleep 9
|
|
on the address of the I/O buffer.
|
|
When the I/O operation completes, the I/O subsystem issues a
|
|
.Xr wakeup 9
|
|
call on the address of the I/O buffer.
|
|
The process is then awakened, rescheduled, and continues execution
|
|
from the
|
|
.Fn tsleep
|
|
function call, eventually returning to the function which requested I/O.
|
|
.Sh CONTINUATIONS
|
|
In contrast,
|
|
.Nm
|
|
constructs an object called a continuation -- a function representing
|
|
.Dq the rest of the program to be performed .
|
|
Continuations are constructed via the
|
|
.Fn kcont
|
|
and
|
|
.Fn kcont_malloc
|
|
functions, which use caller-supplied or dynamically-allocated space,
|
|
respectively.
|
|
In addition to the continuation-function, argument-object,
|
|
and environment, the constructor of each continuation specifies an
|
|
target interrupt priority (IPL) above which the continuation should not be run.
|
|
.Pp
|
|
Once constructed, the continuation can be destined for execution
|
|
in one of two ways.
|
|
First,
|
|
.Fn kcont_defer
|
|
or
|
|
.Fn kcont_defer_malloc
|
|
schedule a continuation for execution as soon as interrupt priority
|
|
falls to or below the target IPL of the continuation.
|
|
Alternatively, a
|
|
.Nm
|
|
can be passed by its creator across kernel interfaces which accept
|
|
.Nm
|
|
objects as methods for notifying the caller (i.e., the
|
|
.Nm
|
|
creator) on completion of an asynchronous operation.
|
|
.Sh DATA TYPES
|
|
.Ss Deferral Priorities
|
|
Arguments shown above with the name
|
|
.Ar desired_ipl
|
|
are drawn from the following namespace:
|
|
.Bl -tag -offset indent -width KC_IPL_DEFER_SOFTSERIALXX
|
|
.It Dv KC_IPL_IMMED
|
|
Execute the continuation as soon as possible, without regard to current IPL.
|
|
.It Dv KC_IPL_DEFER_SOFTSERIAL
|
|
Execute the continuation once IPL falls to
|
|
.Dv IPL_SOFTSERIAL
|
|
or below.
|
|
.It Dv KC_IPL_DEFER_SOFTCLOCK
|
|
Execute the continuation once IPL falls to
|
|
.Dv IPL_SOFTCLOCK
|
|
or below.
|
|
.It Dv KC_IPL_DEFER_SOFTNET
|
|
Execute the continuation once IPL falls to
|
|
.Dv IPL_SOFTNET
|
|
or below.
|
|
.It Dv KC_IPL_DEFER_PROCESS
|
|
Defer execution of the continuation to process context.
|
|
.El
|
|
.Sh NOTES
|
|
The
|
|
.Ar desired_ipl
|
|
argument should be interpreted as an upper-bound:
|
|
the continuation will not be executed before interrupt priority drops
|
|
to, or below, the requested level.
|
|
In particular, the current implementation uses
|
|
.Nx
|
|
generic software callouts.
|
|
On
|
|
.Nx
|
|
ports which lack generic software callouts, all
|
|
.Nm
|
|
continuations will always be deferred all the way to the context
|
|
of a
|
|
.Dq helper
|
|
kernel thread.
|
|
.Sh SEE ALSO
|
|
.Xr kthread 9 ,
|
|
.Xr spl 9 ,
|
|
.Xr tsleep 9 ,
|
|
.Xr wakeup 9 ,
|
|
.Xr workqueue 9
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
interface was designed and implemented by
|
|
.An Jonathan Stone .
|
|
Additional input on the
|
|
.Nm
|
|
design was provided by Jason Thorpe and Nathan Williams.
|