71988c68a9d04f312fa1acf7ce725d009bf5e87e
[dragonfly.git] / sys / sys / msgport.h
1 /*
2  * SYS/MSGPORT.H
3  *
4  *      Implements LWKT messages and ports.
5  * 
6  * $DragonFly: src/sys/sys/msgport.h,v 1.32 2008/11/26 15:05:42 sephe Exp $
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
15 #ifndef _SYS_STDINT_H_
16 #include <sys/stdint.h>
17 #endif
18 #ifndef _SYS_SPINLOCK_H_
19 #include <sys/spinlock.h>
20 #endif
21
22 #ifdef _KERNEL
23
24 #ifndef _SYS_MALLOC_H_
25 #include <sys/malloc.h>
26 #endif
27
28 #endif
29
30 struct lwkt_msg;
31 struct lwkt_port;
32 struct lwkt_serialize;
33 struct thread;
34
35 typedef struct lwkt_msg         *lwkt_msg_t;
36 typedef struct lwkt_port        *lwkt_port_t;
37
38 typedef TAILQ_HEAD(lwkt_msg_queue, lwkt_msg) lwkt_msg_queue;
39
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.
44  *
45  * A message may only be manipulated by whomever currently owns it,
46  * which generally means the originating port if the message has
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  *
50  * NOTE! 64-bit-align this structure.
51  */
52 typedef struct lwkt_msg {
53     TAILQ_ENTRY(lwkt_msg) ms_node;      /* link node */
54     lwkt_port_t ms_target_port;         /* current target or relay port */
55     lwkt_port_t ms_reply_port;          /* async replies returned here */
56     void        (*ms_abortfn)(struct lwkt_msg *);
57     int         ms_flags;               /* message flags */
58     int         ms_error;               /* positive error code or 0 */
59     union {
60         void    *ms_resultp;            /* misc pointer data or result */
61         int     ms_result;              /* standard 'int'eger result */
62         long    ms_lresult;             /* long result */
63         int     ms_fds[2];              /* two int bit results */
64         __int32_t ms_result32;          /* 32 bit result */
65         __int64_t ms_result64;          /* 64 bit result */
66         __off_t ms_offset;              /* off_t result */
67     } u;
68     int         ms_pad[2];              /* future use */
69 } lwkt_msg;
70
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  *
92  * ABORTABLE    Static flag indicates that ms_abortfn is valid.
93  *
94  * High 16 bits are available to message handlers.
95  */
96 #define MSGF_DONE       0x0001          /* message is complete */
97 #define MSGF_REPLY      0x0002          /* asynch message has been returned */
98 #define MSGF_QUEUED     0x0004          /* message has been queued sanitychk */
99 #define MSGF_SYNC       0x0008          /* synchronous message operation */
100 #define MSGF_INTRANSIT  0x0010          /* in-transit (IPI) */
101 #define MSGF_NORESCHED  0x0020          /* do not reschedule target lwkt */
102 #define MSGF_DROPABLE   0x0040          /* message supports drop */
103 #define MSGF_ABORTABLE  0x0080          /* message supports abort */
104 #define MSGF_PRIORITY   0x0100          /* priority message */
105
106 #define MSGF_USER0      0x00010000
107 #define MSGF_USER1      0x00020000
108 #define MSGF_USER2      0x00040000
109 #define MSGF_USER3      0x00080000
110
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
116 #ifdef _KERNEL
117 MALLOC_DECLARE(M_LWKTMSG);
118 #endif
119
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  *
129  * mp_waitmsg():
130  *      - wait for a particular message to be returned.
131  *
132  * mp_waitport():
133  *      - wait for a new message on the specified port.
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
139  *        one sets MSGF_DONE.  If MSGF_SYNC is set the message is not
140  *        queued to the port and the reply code wakes up the waiter
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.
148  */
149 typedef struct lwkt_port {
150     lwkt_msg_queue      mp_msgq;
151     lwkt_msg_queue      mp_msgq_prio;
152     int                 mp_flags;
153     union {
154         struct spinlock spin;
155         struct thread   *td;
156         struct lwkt_serialize *serialize;
157         void            *data;
158     } mp_u;
159     void *              (*mp_getport)(lwkt_port_t);
160     int                 (*mp_putport)(lwkt_port_t, lwkt_msg_t);
161     int                 (*mp_waitmsg)(lwkt_msg_t, int flags);
162     void *              (*mp_waitport)(lwkt_port_t, int flags);
163     void                (*mp_replyport)(lwkt_port_t, lwkt_msg_t);
164     void                (*mp_dropmsg)(lwkt_port_t, lwkt_msg_t);
165 } lwkt_port;
166
167 #ifdef _KERNEL
168
169 #define mpu_td          mp_u.td
170 #define mpu_spin        mp_u.spin
171 #define mpu_serialize   mp_u.serialize
172 #define mpu_data        mp_u.data
173
174 #endif
175
176 #define MSGPORTF_WAITING        0x0001
177
178 /*
179  * These functions are good for userland as well as the kernel.  The 
180  * messaging function support for userland is provided by the kernel's
181  * kern/lwkt_msgport.c.  The port functions are provided by userland.
182  */
183
184 void lwkt_initport_thread(lwkt_port_t, struct thread *);
185 void lwkt_initport_spin(lwkt_port_t);
186 void lwkt_initport_serialize(lwkt_port_t, struct lwkt_serialize *);
187 void lwkt_initport_panic(lwkt_port_t);
188 void lwkt_initport_replyonly_null(lwkt_port_t);
189 void lwkt_initport_replyonly(lwkt_port_t,
190                                 void (*rportfn)(lwkt_port_t, lwkt_msg_t));
191 void lwkt_initport_putonly(lwkt_port_t,
192                                 int (*pportfn)(lwkt_port_t, lwkt_msg_t));
193
194 void lwkt_sendmsg(lwkt_port_t, lwkt_msg_t);
195 int lwkt_domsg(lwkt_port_t, lwkt_msg_t, int);
196 int lwkt_forwardmsg(lwkt_port_t, lwkt_msg_t);
197 void lwkt_abortmsg(lwkt_msg_t);
198
199 #endif