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
84typedef 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) \
121MACRO_BEGIN \
122 assert(((imq)->imq_inheritor & 1) || SLIST_EMPTY(&(imq)->imq_klist)); \
123 ((imq)->imq_inheritor = (uintptr_t)(inheritor) | 1); \
124MACRO_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
172extern void imq_reserve_and_lock(ipc_mqueue_t mq,
173 uint64_t *reserved_prepost);
174
175extern 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
181extern 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 */
192extern void ipc_mqueue_init(
193 ipc_mqueue_t mqueue,
194 boolean_t is_set);
195
196/* de-initialize / cleanup an mqueue (specifically waitq resources) */
197extern void ipc_mqueue_deinit(
198 ipc_mqueue_t mqueue);
199
200/* destroy an mqueue */
201extern boolean_t ipc_mqueue_destroy_locked(
202 ipc_mqueue_t mqueue);
203
204/* Wake up receivers waiting in a message queue */
205extern void ipc_mqueue_changed(
206 ipc_mqueue_t mqueue);
207
208/* Add the specific mqueue as a member of the set */
209extern 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 */
216extern 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 */
221extern 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 */
226extern void ipc_mqueue_remove_from_all(
227 ipc_mqueue_t mqueue);
228
229/* Remove all the members of the specifiied set */
230extern void ipc_mqueue_remove_all(
231 ipc_mqueue_t mqueue);
232
233/* Send a message to a port */
234extern 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 */
241extern 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 */
248extern 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 */
253extern 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 */
259extern 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 */
267extern 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 */
276extern 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 */
281extern 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 */
289extern 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 */
298extern 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 */
307extern unsigned ipc_mqueue_set_peek(
308 ipc_mqueue_t mqueue);
309
310/* Release an mqueue/port reference that was granted by MACH_PEEK_MSG */
311extern void ipc_mqueue_release_peek_ref(
312 ipc_mqueue_t mqueue);
313
314/* Gather the names of member port for a given set */
315extern 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 */
323extern void ipc_mqueue_release_msgcount(
324 ipc_mqueue_t port_mq,
325 ipc_mqueue_t set_mq);
326
327/* Change a queue limit */
328extern void ipc_mqueue_set_qlimit(
329 ipc_mqueue_t mqueue,
330 mach_port_msgcount_t qlimit);
331
332/* Change a queue's sequence number */
333extern 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 */
338extern 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