kernel/lwkt_msgport: Improve comments a bit.
[dragonfly.git] / sys / sys / msgport.h
CommitLineData
ece04fd0
MD
1/*
2 * SYS/MSGPORT.H
3 *
4 * Implements LWKT messages and ports.
5 *
f2c8b5a3 6 * $DragonFly: src/sys/sys/msgport.h,v 1.32 2008/11/26 15:05:42 sephe Exp $
ece04fd0
MD
7 */
8
9#ifndef _SYS_MSGPORT_H_
10#define _SYS_MSGPORT_H_
11
12#ifndef _SYS_QUEUE_H_
13#include <sys/queue.h> /* TAILQ_* macros */
14#endif
05220613
MD
15#ifndef _SYS_STDINT_H_
16#include <sys/stdint.h>
17#endif
fb0f29c4
MD
18#ifndef _SYS_SPINLOCK_H_
19#include <sys/spinlock.h>
20#endif
ece04fd0 21
6aad077d
MD
22#ifdef _KERNEL
23
24#ifndef _SYS_MALLOC_H_
25#include <sys/malloc.h>
26#endif
27
28#endif
29
ece04fd0
MD
30struct lwkt_msg;
31struct lwkt_port;
74208df3 32struct lwkt_serialize;
335dda38 33struct thread;
ece04fd0
MD
34
35typedef struct lwkt_msg *lwkt_msg_t;
36typedef struct lwkt_port *lwkt_port_t;
37
335dda38
MD
38typedef TAILQ_HEAD(lwkt_msg_queue, lwkt_msg) lwkt_msg_queue;
39
ece04fd0
MD
40/*
41 * The standard message and port structure for communications between
42 * threads. See kern/lwkt_msgport.c for documentation on how messages and
43 * ports work.
a64ba182 44 *
4599cf19
MD
45 * A message may only be manipulated by whomever currently owns it,
46 * which generally means the originating port if the message has
e7906ee5
MD
47 * not been sent yet or has been replied, and the target port if the message
48 * has been sent and/or is undergoing processing.
49 *
a64ba182 50 * NOTE! 64-bit-align this structure.
ece04fd0
MD
51 */
52typedef struct lwkt_msg {
ce280ce5 53 TAILQ_ENTRY(lwkt_msg) ms_node; /* link node */
df2244e3 54 lwkt_port_t ms_target_port; /* current target or relay port */
e7906ee5 55 lwkt_port_t ms_reply_port; /* async replies returned here */
4599cf19 56 void (*ms_abortfn)(struct lwkt_msg *);
df2244e3 57 int ms_flags; /* message flags */
df2244e3 58 int ms_error; /* positive error code or 0 */
a64ba182 59 union {
df2244e3 60 void *ms_resultp; /* misc pointer data or result */
90b9818c
MD
61 int ms_result; /* standard 'int'eger result */
62 long ms_lresult; /* long result */
63 int ms_fds[2]; /* two int bit results */
05220613
MD
64 __int32_t ms_result32; /* 32 bit result */
65 __int64_t ms_result64; /* 64 bit result */
66 __off_t ms_offset; /* off_t result */
a64ba182
MD
67 } u;
68 int ms_pad[2]; /* future use */
ece04fd0
MD
69} lwkt_msg;
70
4599cf19
MD
71/*
72 * Message state flags are manipulated by the current owner only.
73 *
74 * DONE Indicates completion of the reply. This flag is also set
75 * for unsent messages.
76 *
77 * REPLY Indicates message is being replied but may or may not
78 * have been queued or returned yet. This bit is left set
79 * when a message is retrieved from a reply port so the caller
80 * can distinguish between requests and replies.
81 *
82 * QUEUED Indicates message is queued on reply or target port, or
83 * some other port.
84 *
85 * SYNC Indicates that the originator is blocked directly on the
86 * message and that the message should be signaled on
87 * completion instead of queued.
88 *
89 * INTRANSIT Indicates that the message state is indeterminant (e.g.
90 * being passed through an IPI).
91 *
4599cf19 92 * ABORTABLE Static flag indicates that ms_abortfn is valid.
f5bcf2d5
MD
93 *
94 * High 16 bits are available to message handlers.
4599cf19
MD
95 */
96#define MSGF_DONE 0x0001 /* message is complete */
97#define MSGF_REPLY 0x0002 /* asynch message has been returned */
ece04fd0 98#define MSGF_QUEUED 0x0004 /* message has been queued sanitychk */
4599cf19
MD
99#define MSGF_SYNC 0x0008 /* synchronous message operation */
100#define MSGF_INTRANSIT 0x0010 /* in-transit (IPI) */
041e7b69 101#define MSGF_WAITING 0x0020 /* MSGF_SYNC being waited upon */
e2ff0223 102#define MSGF_DROPABLE 0x0040 /* message supports drop */
b44419cb 103#define MSGF_ABORTABLE 0x0080 /* message supports abort */
f2c8b5a3 104#define MSGF_PRIORITY 0x0100 /* priority message */
ece04fd0 105
f5bcf2d5
MD
106#define MSGF_USER0 0x00010000
107#define MSGF_USER1 0x00020000
108#define MSGF_USER2 0x00040000
109#define MSGF_USER3 0x00080000
110
335dda38
MD
111#define MSG_CMD_CDEV 0x00010000
112#define MSG_CMD_VFS 0x00020000
113#define MSG_CMD_SYSCALL 0x00030000
114#define MSG_SUBCMD_MASK 0x0000FFFF
115
9eeaa8a9 116#ifdef _KERNEL
9eeaa8a9
JH
117MALLOC_DECLARE(M_LWKTMSG);
118#endif
9eeaa8a9 119
3efe7008
MD
120/*
121 * Notes on port processing requirements:
122 *
123 * mp_putport():
124 * - may return synchronous error code (error != EASYNC) directly and
125 * does not need to check or set MSGF_DONE if so, or set ms_target_port
126 * - for asynch procesing should clear MSGF_DONE and set ms_target_port
127 * to port prior to initiation of the command.
128 *
a22c590e
MD
129 * mp_waitmsg():
130 * - wait for a particular message to be returned.
131 *
3efe7008 132 * mp_waitport():
a22c590e 133 * - wait for a new message on the specified port.
3efe7008
MD
134 *
135 * mp_replyport():
136 * - reply a message (executed on the originating port to return a
137 * message to it). This can be rather involved if abort is to be
138 * supported, see lwkt_default_replyport(). Generally speaking
1a0fa461
NA
139 * one sets MSGF_DONE and MSGF_REPLY. If MSGF_SYNC is set the message
140 * is not queued to the port and the reply code wakes up the waiter
fb0f29c4
MD
141 * directly.
142 *
143 * The use of mp_u.td and mp_u.spin is specific to the port callback function
144 * set. Default ports are tied to specific threads and use cpu locality
145 * of reference and mp_u.td (and not mp_u.spin at all). Descriptor ports
146 * assume access via descriptors, signal interruption, etc. Such ports use
147 * mp_u.spin (and not mp_u.td at all) and may be accessed by multiple threads.
3efe7008 148 */
ece04fd0
MD
149typedef struct lwkt_port {
150 lwkt_msg_queue mp_msgq;
f2c8b5a3 151 lwkt_msg_queue mp_msgq_prio;
ece04fd0 152 int mp_flags;
fb0f29c4
MD
153 union {
154 struct spinlock spin;
155 struct thread *td;
74208df3 156 struct lwkt_serialize *serialize;
fb0f29c4
MD
157 void *data;
158 } mp_u;
159 void * (*mp_getport)(lwkt_port_t);
df2244e3 160 int (*mp_putport)(lwkt_port_t, lwkt_msg_t);
a22c590e
MD
161 int (*mp_waitmsg)(lwkt_msg_t, int flags);
162 void * (*mp_waitport)(lwkt_port_t, int flags);
df2244e3 163 void (*mp_replyport)(lwkt_port_t, lwkt_msg_t);
e2ff0223 164 void (*mp_dropmsg)(lwkt_port_t, lwkt_msg_t);
ece04fd0
MD
165} lwkt_port;
166
fb0f29c4
MD
167#ifdef _KERNEL
168
169#define mpu_td mp_u.td
170#define mpu_spin mp_u.spin
74208df3 171#define mpu_serialize mp_u.serialize
fb0f29c4
MD
172#define mpu_data mp_u.data
173
174#endif
175
1a0fa461
NA
176/*
177 * Port state flags.
178 *
179 * WAITING The owner of the port is descheduled waiting for a message
180 * to be replied. In case this a spin port there can actually
181 * be more than one thread waiting on the port.
182 */
ece04fd0
MD
183#define MSGPORTF_WAITING 0x0001
184
df2244e3 185/*
1a0fa461 186 * These functions are good for userland as well as the kernel. The
df2244e3
MD
187 * messaging function support for userland is provided by the kernel's
188 * kern/lwkt_msgport.c. The port functions are provided by userland.
189 */
fb0f29c4
MD
190
191void lwkt_initport_thread(lwkt_port_t, struct thread *);
192void lwkt_initport_spin(lwkt_port_t);
74208df3 193void lwkt_initport_serialize(lwkt_port_t, struct lwkt_serialize *);
fb0f29c4
MD
194void lwkt_initport_panic(lwkt_port_t);
195void lwkt_initport_replyonly_null(lwkt_port_t);
196void lwkt_initport_replyonly(lwkt_port_t,
197 void (*rportfn)(lwkt_port_t, lwkt_msg_t));
198void lwkt_initport_putonly(lwkt_port_t,
199 int (*pportfn)(lwkt_port_t, lwkt_msg_t));
200
984ccc17 201void lwkt_sendmsg(lwkt_port_t, lwkt_msg_t);
a22c590e 202int lwkt_domsg(lwkt_port_t, lwkt_msg_t, int);
e7906ee5
MD
203int lwkt_forwardmsg(lwkt_port_t, lwkt_msg_t);
204void lwkt_abortmsg(lwkt_msg_t);
ece04fd0 205
ece04fd0 206#endif