1 | /* |
2 | * Copyright (c) 2000-2007 Apple Inc. All rights reserved. |
3 | * |
4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
5 | * |
6 | * This file contains Original Code and/or Modifications of Original Code |
7 | * as defined in and that are subject to the Apple Public Source License |
8 | * Version 2.0 (the 'License'). You may not use this file except in |
9 | * compliance with the License. The rights granted to you under the License |
10 | * may not be used to create, or enable the creation or redistribution of, |
11 | * unlawful or unlicensed copies of an Apple operating system, or to |
12 | * circumvent, violate, or enable the circumvention or violation of, any |
13 | * terms of an Apple operating system software license agreement. |
14 | * |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. |
17 | * |
18 | * The Original Code and all software distributed under the License are |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
23 | * Please see the License for the specific language governing rights and |
24 | * limitations under the License. |
25 | * |
26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
27 | */ |
28 | /* |
29 | * @OSF_COPYRIGHT@ |
30 | */ |
31 | /* |
32 | * Mach Operating System |
33 | * Copyright (c) 1991,1990,1989 Carnegie Mellon University |
34 | * All Rights Reserved. |
35 | * |
36 | * Permission to use, copy, modify and distribute this software and its |
37 | * documentation is hereby granted, provided that both the copyright |
38 | * notice and this permission notice appear in all copies of the |
39 | * software, derivative works or modified versions, and any portions |
40 | * thereof, and that both notices appear in supporting documentation. |
41 | * |
42 | * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" |
43 | * CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR |
44 | * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. |
45 | * |
46 | * Carnegie Mellon requests users of this software to return to |
47 | * |
48 | * Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU |
49 | * School of Computer Science |
50 | * Carnegie Mellon University |
51 | * Pittsburgh PA 15213-3890 |
52 | * |
53 | * any improvements or extensions that they make and grant Carnegie Mellon |
54 | * the rights to redistribute these changes. |
55 | */ |
56 | /* |
57 | */ |
58 | /* |
59 | * File: ipc/ipc_mqueue.h |
60 | * Author: Rich Draves |
61 | * Date: 1989 |
62 | * |
63 | * Definitions for message queues. |
64 | */ |
65 | |
66 | #ifndef _IPC_IPC_MQUEUE_H_ |
67 | #define _IPC_IPC_MQUEUE_H_ |
68 | |
69 | #include <mach_assert.h> |
70 | |
71 | #include <mach/message.h> |
72 | |
73 | #include <kern/assert.h> |
74 | #include <kern/macro_help.h> |
75 | #include <kern/kern_types.h> |
76 | #include <kern/waitq.h> |
77 | |
78 | #include <ipc/ipc_kmsg.h> |
79 | #include <ipc/ipc_object.h> |
80 | #include <ipc/ipc_types.h> |
81 | |
82 | #include <sys/event.h> |
83 | |
84 | typedef struct ipc_mqueue { |
85 | union { |
86 | struct { |
87 | struct waitq waitq; |
88 | struct ipc_kmsg_queue messages; |
89 | mach_port_seqno_t seqno; |
90 | mach_port_name_t receiver_name; |
91 | uint16_t msgcount; |
92 | uint16_t qlimit; |
93 | #if MACH_FLIPC |
94 | struct flipc_port *fport; // Null for local port, or ptr to flipc port |
95 | #endif |
96 | } port; |
97 | struct { |
98 | struct waitq_set setq; |
99 | } pset; |
100 | } data; |
101 | union { |
102 | struct klist imq_klist; |
103 | uintptr_t imq_inheritor; |
104 | }; |
105 | } *ipc_mqueue_t; |
106 | |
107 | #define IMQ_NULL ((ipc_mqueue_t) 0) |
108 | |
109 | /* |
110 | * When a receive right is in flight, before it can ever be registered with |
111 | * a new knote, its imq_klist field can be overloaded to hold a pointer |
112 | * to the knote that the port is pushing on through his turnstile. |
113 | * |
114 | * if IMQ_KLIST_VALID() returns true, then the imq_klist field can be used, |
115 | * else IMQ_INHERITOR() can be used to get the pointer to the knote currently |
116 | * being the port turnstile inheritor. |
117 | */ |
118 | #define IMQ_KLIST_VALID(imq) (((imq)->imq_inheritor & 1) == 0) |
119 | #define IMQ_INHERITOR(imq) ((struct turnstile *)((imq)->imq_inheritor ^ 1)) |
120 | #define IMQ_SET_INHERITOR(imq, inheritor) \ |
121 | MACRO_BEGIN \ |
122 | assert(((imq)->imq_inheritor & 1) || SLIST_EMPTY(&(imq)->imq_klist)); \ |
123 | ((imq)->imq_inheritor = (uintptr_t)(inheritor) | 1); \ |
124 | MACRO_END |
125 | |
126 | #define imq_wait_queue data.port.waitq |
127 | #define imq_messages data.port.messages |
128 | #define imq_msgcount data.port.msgcount |
129 | #define imq_qlimit data.port.qlimit |
130 | #define imq_seqno data.port.seqno |
131 | #define imq_receiver_name data.port.receiver_name |
132 | #if MACH_FLIPC |
133 | #define imq_fport data.port.fport |
134 | #endif |
135 | |
136 | /* |
137 | * we can use the 'eventmask' bits of the waitq b/c |
138 | * they are only used by global queues |
139 | */ |
140 | #define imq_fullwaiters data.port.waitq.waitq_eventmask |
141 | #define imq_in_pset data.port.waitq.waitq_set_id |
142 | #define imq_preposts data.port.waitq.waitq_prepost_id |
143 | |
144 | #define imq_set_queue data.pset.setq |
145 | #define imq_is_set(mq) waitqs_is_set(&(mq)->imq_set_queue) |
146 | #define imq_is_queue(mq) waitq_is_queue(&(mq)->imq_wait_queue) |
147 | #define imq_is_valid(mq) waitq_is_valid(&(mq)->imq_wait_queue) |
148 | |
149 | #define imq_lock(mq) waitq_lock(&(mq)->imq_wait_queue) |
150 | #define imq_lock_try(mq) waitq_lock_try(&(mq)->imq_wait_queue) |
151 | #define imq_unlock(mq) waitq_unlock(&(mq)->imq_wait_queue) |
152 | #define imq_held(mq) waitq_held(&(mq)->imq_wait_queue) |
153 | #define imq_valid(mq) waitq_valid(&(mq)->imq_wait_queue) |
154 | |
155 | /* |
156 | * Get an ipc_mqueue pointer from a waitq pointer. These are traditionally the |
157 | * same pointer, but this conversion makes no assumptions on union structure |
158 | * member positions - it should allow the waitq to move around in either the |
159 | * port-set mqueue or the port mqueue independently. |
160 | */ |
161 | #define imq_from_waitq(waitq) (waitq_is_set(waitq) ? \ |
162 | ((struct ipc_mqueue *)((void *)( \ |
163 | (uintptr_t)(waitq) - \ |
164 | __offsetof(struct ipc_mqueue, imq_set_queue)) \ |
165 | )) : \ |
166 | ((struct ipc_mqueue *)((void *)( \ |
167 | (uintptr_t)(waitq) - \ |
168 | __offsetof(struct ipc_mqueue, imq_wait_queue)) \ |
169 | )) \ |
170 | ) |
171 | |
172 | extern void imq_reserve_and_lock(ipc_mqueue_t mq, |
173 | uint64_t *reserved_prepost); |
174 | |
175 | extern void imq_release_and_unlock(ipc_mqueue_t mq, |
176 | uint64_t reserved_prepost); |
177 | |
178 | #define imq_full(mq) ((mq)->imq_msgcount >= (mq)->imq_qlimit) |
179 | #define imq_full_kernel(mq) ((mq)->imq_msgcount >= MACH_PORT_QLIMIT_KERNEL) |
180 | |
181 | extern int ipc_mqueue_full; |
182 | // extern int ipc_mqueue_rcv; |
183 | |
184 | #define IPC_MQUEUE_FULL CAST_EVENT64_T(&ipc_mqueue_full) |
185 | #define IPC_MQUEUE_RECEIVE NO_EVENT64 |
186 | |
187 | /* |
188 | * Exported interfaces |
189 | */ |
190 | |
191 | /* Initialize a newly-allocated message queue */ |
192 | extern void ipc_mqueue_init( |
193 | ipc_mqueue_t mqueue, |
194 | boolean_t is_set); |
195 | |
196 | /* de-initialize / cleanup an mqueue (specifically waitq resources) */ |
197 | extern void ipc_mqueue_deinit( |
198 | ipc_mqueue_t mqueue); |
199 | |
200 | /* destroy an mqueue */ |
201 | extern boolean_t ipc_mqueue_destroy_locked( |
202 | ipc_mqueue_t mqueue); |
203 | |
204 | /* Wake up receivers waiting in a message queue */ |
205 | extern void ipc_mqueue_changed( |
206 | ipc_mqueue_t mqueue); |
207 | |
208 | /* Add the specific mqueue as a member of the set */ |
209 | extern kern_return_t ipc_mqueue_add( |
210 | ipc_mqueue_t mqueue, |
211 | ipc_mqueue_t set_mqueue, |
212 | uint64_t *reserved_link, |
213 | uint64_t *reserved_prepost); |
214 | |
215 | /* Check to see if mqueue is member of set_mqueue */ |
216 | extern boolean_t ipc_mqueue_member( |
217 | ipc_mqueue_t mqueue, |
218 | ipc_mqueue_t set_mqueue); |
219 | |
220 | /* Remove an mqueue from a specific set */ |
221 | extern kern_return_t ipc_mqueue_remove( |
222 | ipc_mqueue_t mqueue, |
223 | ipc_mqueue_t set_mqueue); |
224 | |
225 | /* Remove an mqueue from all sets */ |
226 | extern void ipc_mqueue_remove_from_all( |
227 | ipc_mqueue_t mqueue); |
228 | |
229 | /* Remove all the members of the specifiied set */ |
230 | extern void ipc_mqueue_remove_all( |
231 | ipc_mqueue_t mqueue); |
232 | |
233 | /* Send a message to a port */ |
234 | extern mach_msg_return_t ipc_mqueue_send( |
235 | ipc_mqueue_t mqueue, |
236 | ipc_kmsg_t kmsg, |
237 | mach_msg_option_t option, |
238 | mach_msg_timeout_t timeout_val); |
239 | |
240 | /* check for queue send queue full of a port */ |
241 | extern mach_msg_return_t ipc_mqueue_preflight_send( |
242 | ipc_mqueue_t mqueue, |
243 | ipc_kmsg_t kmsg, |
244 | mach_msg_option_t option, |
245 | mach_msg_timeout_t timeout_val); |
246 | |
247 | /* Set a [send-possible] override on the mqueue */ |
248 | extern void ipc_mqueue_override_send( |
249 | ipc_mqueue_t mqueue, |
250 | mach_msg_priority_t override); |
251 | |
252 | /* Deliver message to message queue or waiting receiver */ |
253 | extern void ipc_mqueue_post( |
254 | ipc_mqueue_t mqueue, |
255 | ipc_kmsg_t kmsg, |
256 | mach_msg_option_t option); |
257 | |
258 | /* Receive a message from a message queue */ |
259 | extern void ipc_mqueue_receive( |
260 | ipc_mqueue_t mqueue, |
261 | mach_msg_option_t option, |
262 | mach_msg_size_t max_size, |
263 | mach_msg_timeout_t timeout_val, |
264 | int interruptible); |
265 | |
266 | /* Receive a message from a message queue using a specified thread */ |
267 | extern wait_result_t ipc_mqueue_receive_on_thread( |
268 | ipc_mqueue_t mqueue, |
269 | mach_msg_option_t option, |
270 | mach_msg_size_t max_size, |
271 | mach_msg_timeout_t rcv_timeout, |
272 | int interruptible, |
273 | thread_t thread); |
274 | |
275 | /* Continuation routine for message receive */ |
276 | extern void ipc_mqueue_receive_continue( |
277 | void *param, |
278 | wait_result_t wresult); |
279 | |
280 | /* Select a message from a queue and try to post it to ourself */ |
281 | extern void ipc_mqueue_select_on_thread( |
282 | ipc_mqueue_t port_mq, |
283 | ipc_mqueue_t set_mq, |
284 | mach_msg_option_t option, |
285 | mach_msg_size_t max_size, |
286 | thread_t thread); |
287 | |
288 | /* Peek into a messaqe queue to see if there are messages */ |
289 | extern unsigned ipc_mqueue_peek( |
290 | ipc_mqueue_t mqueue, |
291 | mach_port_seqno_t *msg_seqnop, |
292 | mach_msg_size_t *msg_sizep, |
293 | mach_msg_id_t *msg_idp, |
294 | mach_msg_max_trailer_t *msg_trailerp, |
295 | ipc_kmsg_t *kmsgp); |
296 | |
297 | /* Peek into a locked messaqe queue to see if there are messages */ |
298 | extern unsigned ipc_mqueue_peek_locked( |
299 | ipc_mqueue_t mqueue, |
300 | mach_port_seqno_t *msg_seqnop, |
301 | mach_msg_size_t *msg_sizep, |
302 | mach_msg_id_t *msg_idp, |
303 | mach_msg_max_trailer_t *msg_trailerp, |
304 | ipc_kmsg_t *kmsgp); |
305 | |
306 | /* Peek into a messaqe queue set to see if there are queues with messages */ |
307 | extern unsigned ipc_mqueue_set_peek( |
308 | ipc_mqueue_t mqueue); |
309 | |
310 | /* Release an mqueue/port reference that was granted by MACH_PEEK_MSG */ |
311 | extern void ipc_mqueue_release_peek_ref( |
312 | ipc_mqueue_t mqueue); |
313 | |
314 | /* Gather the names of member port for a given set */ |
315 | extern void ipc_mqueue_set_gather_member_names( |
316 | ipc_space_t space, |
317 | ipc_mqueue_t set_mq, |
318 | ipc_entry_num_t maxnames, |
319 | mach_port_name_t *names, |
320 | ipc_entry_num_t *actualp); |
321 | |
322 | /* Clear a message count reservation */ |
323 | extern void ipc_mqueue_release_msgcount( |
324 | ipc_mqueue_t port_mq, |
325 | ipc_mqueue_t set_mq); |
326 | |
327 | /* Change a queue limit */ |
328 | extern void ipc_mqueue_set_qlimit( |
329 | ipc_mqueue_t mqueue, |
330 | mach_port_msgcount_t qlimit); |
331 | |
332 | /* Change a queue's sequence number */ |
333 | extern void ipc_mqueue_set_seqno( |
334 | ipc_mqueue_t mqueue, |
335 | mach_port_seqno_t seqno); |
336 | |
337 | /* Convert a name in a space to a message queue */ |
338 | extern mach_msg_return_t ipc_mqueue_copyin( |
339 | ipc_space_t space, |
340 | mach_port_name_t name, |
341 | ipc_mqueue_t *mqueuep, |
342 | ipc_object_t *objectp); |
343 | |
344 | #endif /* _IPC_IPC_MQUEUE_H_ */ |
345 | |