FreeBSD/Linux Kernel Cross Reference
sys/sys/kcont.h
1 /* $NetBSD: kcont.h,v 1.3 2004/03/25 23:02:58 enami Exp $ */
2
3 /*
4 * Copyright (c) 2003 The NetBSD Foundation, Inc.
5 * All rights reserved.
6 *
7 * This code is derived from software contributed to The NetBSD Foundation
8 * by Jonathan Stone, currently employed by Decru, Inc.
9 *
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
12 * are met:
13 * 1. Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in the
17 * documentation and/or other materials provided with the distribution.
18 * 3. Neither the name of The NetBSD Foundation nor the names of its
19 * contributors may be used to endorse or promote products derived
20 * from this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
23 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
24 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
25 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
26 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 * POSSIBILITY OF SUCH DAMAGE.
33 */
34
35 /*
36 * Copyright 2003 Jonathan Stone.
37 * All rights reserved.
38 */
39
40 #ifndef _SYS_KCONT_H_
41 #define _SYS_KCONT_H_
42
43 #include <sys/queue.h>
44
45 /*
46 * kcont -- Continuation-passing for BSD kernels.
47 *
48 * This module defines structures that implement a
49 * continuation-passing model in C which can be used as a
50 * ``callback''-like alternative to using a process context to
51 * tsleep() on an object address, waiting for some event or status
52 * change on that object. Since ANSI C provides neither
53 * lexically-nested functions nor heap allocation of activation
54 * records, we implement a continuation as a struct containing:
55 * 1. A function pointer, pointing to the continuation.
56 * 2. A object pointer: the object being "slept" upon.
57 * 3. An argument pointer: a pointer to private storage containing
58 * other arguments to the continuation function, including any
59 * additional state beyond the "slept-upon" object.
60 */
61
62 typedef struct kc {
63 SIMPLEQ_ENTRY(kc) kc_next; /* next kc in object's callback list */
64
65 void (*kc_fn) (void * /*obj*/, void * /*env_arg*/, int /*status*/);
66
67 void *kc_env_arg; /* caller-supplied continuation argument */
68 void *kc_obj; /* saved object, used for deferred calls */
69 int kc_status; /* saved status, used for deferred calls */
70 ushort kc_ipl; /* IPL at which to call kc_func */
71 ushort kc_flags; /* Flags, private to kcont implementation */
72 } kc_t;
73
74 /* kc_flags values. */
75 #define KC_AUTOFREE 0x01 /* This struct kc * was malloc'ed by
76 * the kcont module; free it immediately
77 * after calling the continuation function.
78 */
79 #define KC_DEFERRED 0x02 /* Deferral has already saved object, status */
80
81 /* kcont IPL values. */
82 #define KC_IPL_DEFER_PROCESS 0x00 /* Hand off continuation fn to a
83 * full process context (kthread).
84 */
85
86 #define KC_IPL_DEFER_SOFTCLOCK 0x01
87 #define KC_IPL_DEFER_SOFTNET 0x02 /* Run continuation in an
88 * IPL_SOFTNET software callout. */
89 #define KC_IPL_DEFER_SOFTSERIAL 0x03
90
91 #define KC_IPL_IMMED 0x10 /*
92 * Execute continuation fn immediately,
93 * in the context of the object event,
94 * with no completion. Continuation
95 * assumed to be very quick.
96 */
97
98 /*
99 * Head of a list of pending continuations.
100 * For example, for continuation-based buffer I/O,
101 * add a kcq_t to struct buf, and pass a struct kc *
102 * down through VFS and strategy layers.
103 */
104 typedef SIMPLEQ_HEAD(kcqueue, kc) kcq_t;
105
106
107 /*
108 * Prepare a struct kc continuation using caller-supplied memory
109 */
110 struct kc *kcont(struct kc *,
111 void (* /*fn*/)(void * /*obj*/, void */*arg*/, int /*sts*/),
112 void * /*env_arg*/, int /*continue_ipl*/);
113
114 /*
115 * Prepare a struct kc continuation using malloc'ed memory.
116 * The malloc'ed memory will be automatically freed after the continuation
117 * is finally called.
118 */
119 struct kc *kcont_malloc(int /*allocmflags*/,
120 void (* /*fn*/)(void * /*obj*/, void */*arg*/, int /*sts*/),
121 void * /*env_arg*/, int /*continue_ipl*/);
122
123
124 /*
125 * Use a caller-supplied, already-constructed kcont to defer execution
126 * from the current context to some lower interrupt priority.
127 * Caller must supply the preallocated kcont (possibly via kcont_malloc()).
128 */
129 void kcont_defer(struct kc * /*kc*/, void * /*obj*/,
130 int /*status*/);
131 /*
132 * Use a kcont to defer execution from the current context to some
133 * lower interrupt priority. Space is malloc'ed and freed as for
134 * kcont_malloc(). Deprecated; use kcont_defer() and kcont_malloc().
135 */
136 void kcont_defer_malloc(int, /* mallocflags */
137 void (* /*fn*/)(void * /*obj*/, void */*arg*/, int /*sts*/),
138 void * /*obj*/,
139 void * /*env_arg*/, int /*status*/, int /*continue_ipl*/);
140
141 /*
142 * Enqueue a struct kc * into the kc_queue* field of some kernel struct.
143 * The struct kc * argument is typically passed as an argument to
144 * a function which requests an asynchronous operation on that kernel object.
145 * When the operation completes, or the object otherwise decides to
146 * invoke a wakeup() on itself, all continuations on the object's
147 * kcqueue will be called, either immediately or if a continuation
148 * requested it) after deferring to a kc_queue * served at
149 * software-interrupt priority.
150 */
151 void kcont_enqueue(kcq_t * /*kcqueue*/, struct kc * /*kc*/);
152
153
154 /*
155 * Execute (or defer) all continuations on an object's kcqueue
156 * when an asynchronous operation completes. Runs through the
157 * struct kc_queue * of struct kcs, either running the continuations
158 * with the given object and status; or saving the object and status
159 * and deferring the kconts to a software-interrupt priority kc_queue.
160 */
161 void kcont_run(kcq_t * /*kcq*/, void * /*obj*/,
162 int /*status*/, int /*cur_ipl*/);
163
164
165 /* Initialize kcont framework at boot time. */
166 void kcont_init(void);
167 #endif /* !_SYS_KCONT_H_ */
Cache object: b67bbc0f8d7c05cac90da1998cae9101
|