1/*
2 * Copyright (c) 2000-2004 Apple Computer, 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 * NOTICE: This file was modified by McAfee Research in 2004 to introduce
58 * support for mandatory and extensible security protections. This notice
59 * is included in support of clause 2.2 (b) of the Apple Public License,
60 * Version 2.0.
61 * Copyright (c) 2005 SPARTA, Inc.
62 */
63/*
64 */
65/*
66 * File: ipc/ipc_kmsg.h
67 * Author: Rich Draves
68 * Date: 1989
69 *
70 * Definitions for kernel messages.
71 */
72
73#ifndef _IPC_IPC_KMSG_H_
74#define _IPC_IPC_KMSG_H_
75
76#include <mach/vm_types.h>
77#include <mach/message.h>
78#include <kern/kern_types.h>
79#include <kern/assert.h>
80#include <kern/macro_help.h>
81#include <ipc/ipc_types.h>
82#include <ipc/ipc_object.h>
83#include <sys/kdebug.h>
84
85/*
86 * This structure is only the header for a kmsg buffer;
87 * the actual buffer is normally larger. The rest of the buffer
88 * holds the body of the message.
89 *
90 * In a kmsg, the port fields hold pointers to ports instead
91 * of port names. These pointers hold references.
92 *
93 * The ikm_header.msgh_remote_port field is the destination
94 * of the message.
95 *
96 * sync_qos and special_port_qos stores the qos for prealloced
97 * port, this fields could be deleted once we remove ip_prealloc.
98 */
99
100struct ipc_kmsg {
101 mach_msg_size_t ikm_size;
102 struct ipc_kmsg *ikm_next; /* next message on port/discard queue */
103 struct ipc_kmsg *ikm_prev; /* prev message on port/discard queue */
104 mach_msg_header_t *ikm_header;
105 ipc_port_t ikm_prealloc; /* port we were preallocated from */
106 ipc_port_t ikm_voucher; /* voucher port carried */
107 mach_msg_priority_t ikm_qos; /* qos of this kmsg */
108 mach_msg_priority_t ikm_qos_override; /* qos override on this kmsg */
109 struct ipc_importance_elem *ikm_importance; /* inherited from */
110 queue_chain_t ikm_inheritance; /* inherited from link */
111 struct turnstile *ikm_turnstile; /* send turnstile for ikm_prealloc port */
112#if MACH_FLIPC
113 struct mach_node *ikm_node; /* Originating node - needed for ack */
114#endif
115};
116
117#if defined(__i386__) || defined(__arm__)
118#define IKM_SUPPORT_LEGACY 1
119#else
120#define IKM_SUPPORT_LEGACY 0
121#endif
122
123#define IKM_OVERHEAD (sizeof(struct ipc_kmsg))
124
125#define ikm_plus_overhead(size) ((mach_msg_size_t)((size) + IKM_OVERHEAD))
126#define ikm_less_overhead(size) ((mach_msg_size_t)((size) - IKM_OVERHEAD))
127
128/*
129 * XXX For debugging.
130 */
131#define IKM_BOGUS ((ipc_kmsg_t) 0xffffff10)
132
133/*
134 * The size of the kernel message buffers that will be cached.
135 * IKM_SAVED_KMSG_SIZE includes overhead; IKM_SAVED_MSG_SIZE doesn't.
136 */
137extern zone_t ipc_kmsg_zone;
138#define IKM_SAVED_KMSG_SIZE 256
139#define IKM_SAVED_MSG_SIZE ikm_less_overhead(IKM_SAVED_KMSG_SIZE)
140
141#define ikm_prealloc_inuse_port(kmsg) \
142 ((kmsg)->ikm_prealloc)
143
144#define ikm_prealloc_inuse(kmsg) \
145 ((kmsg)->ikm_prealloc != IP_NULL)
146
147#define ikm_prealloc_set_inuse(kmsg, port) \
148MACRO_BEGIN \
149 assert((port) != IP_NULL); \
150 (kmsg)->ikm_prealloc = (port); \
151 ip_reference(port); \
152MACRO_END
153
154#define ikm_prealloc_clear_inuse(kmsg, port) \
155MACRO_BEGIN \
156 (kmsg)->ikm_prealloc = IP_NULL; \
157MACRO_END
158
159#if MACH_FLIPC
160#define ikm_flipc_init(kmsg) (kmsg)->ikm_node = MACH_NODE_NULL
161#else
162#define ikm_flipc_init(kmsg)
163#endif
164
165#define ikm_init(kmsg, size) \
166MACRO_BEGIN \
167 (kmsg)->ikm_size = (size); \
168 (kmsg)->ikm_prealloc = IP_NULL; \
169 (kmsg)->ikm_voucher = IP_NULL; \
170 (kmsg)->ikm_importance = IIE_NULL; \
171 ikm_qos_init(kmsg); \
172 ikm_flipc_init(kmsg); \
173 assert((kmsg)->ikm_prev = (kmsg)->ikm_next = IKM_BOGUS); \
174MACRO_END
175
176#define ikm_qos_init(kmsg) \
177MACRO_BEGIN \
178 (kmsg)->ikm_qos = MACH_MSG_PRIORITY_UNSPECIFIED; \
179 (kmsg)->ikm_qos_override = MACH_MSG_PRIORITY_UNSPECIFIED; \
180MACRO_END
181
182#define ikm_check_init(kmsg, size) \
183MACRO_BEGIN \
184 assert((kmsg)->ikm_size == (size)); \
185 assert((kmsg)->ikm_prev == IKM_BOGUS); \
186 assert((kmsg)->ikm_next == IKM_BOGUS); \
187MACRO_END
188
189#define ikm_set_header(kmsg, mtsize) \
190MACRO_BEGIN \
191 (kmsg)->ikm_header = (mach_msg_header_t *) \
192 ((vm_offset_t)((kmsg) + 1) + (kmsg)->ikm_size - (mtsize)); \
193MACRO_END
194
195struct ipc_kmsg_queue {
196 struct ipc_kmsg *ikmq_base;
197};
198
199typedef struct ipc_kmsg_queue *ipc_kmsg_queue_t;
200
201#define IKMQ_NULL ((ipc_kmsg_queue_t) 0)
202
203
204/*
205 * Exported interfaces
206 */
207
208#define ipc_kmsg_queue_init(queue) \
209MACRO_BEGIN \
210 (queue)->ikmq_base = IKM_NULL; \
211MACRO_END
212
213#define ipc_kmsg_queue_empty(queue) ((queue)->ikmq_base == IKM_NULL)
214
215/* Enqueue a kmsg */
216extern void ipc_kmsg_enqueue(
217 ipc_kmsg_queue_t queue,
218 ipc_kmsg_t kmsg);
219
220extern boolean_t ipc_kmsg_enqueue_qos(
221 ipc_kmsg_queue_t queue,
222 ipc_kmsg_t kmsg);
223
224extern boolean_t ipc_kmsg_override_qos(
225 ipc_kmsg_queue_t queue,
226 ipc_kmsg_t kmsg,
227 mach_msg_priority_t override);
228
229/* Dequeue and return a kmsg */
230extern ipc_kmsg_t ipc_kmsg_dequeue(
231 ipc_kmsg_queue_t queue);
232
233/* Pull a kmsg out of a queue */
234extern void ipc_kmsg_rmqueue(
235 ipc_kmsg_queue_t queue,
236 ipc_kmsg_t kmsg);
237
238/* Pull the (given) first kmsg out of a queue */
239extern void ipc_kmsg_rmqueue_first(
240 ipc_kmsg_queue_t queue,
241 ipc_kmsg_t kmsg);
242
243#define ipc_kmsg_queue_first(queue) ((queue)->ikmq_base)
244
245/* Return the kmsg following the given kmsg */
246extern ipc_kmsg_t ipc_kmsg_queue_next(
247 ipc_kmsg_queue_t queue,
248 ipc_kmsg_t kmsg);
249
250/* Allocate a kernel message */
251extern ipc_kmsg_t ipc_kmsg_alloc(
252 mach_msg_size_t size);
253
254/* Free a kernel message buffer */
255extern void ipc_kmsg_free(
256 ipc_kmsg_t kmsg);
257
258/* Destroy kernel message */
259extern void ipc_kmsg_destroy(
260 ipc_kmsg_t kmsg);
261
262/* Enqueue kernel message for deferred destruction */
263extern boolean_t ipc_kmsg_delayed_destroy(
264 ipc_kmsg_t kmsg);
265
266/* Process all the delayed message destroys */
267extern void ipc_kmsg_reap_delayed(void);
268
269/* Preallocate a kernel message buffer */
270extern ipc_kmsg_t ipc_kmsg_prealloc(
271 mach_msg_size_t size);
272
273/* bind a preallocated message buffer to a port */
274extern void ipc_kmsg_set_prealloc(
275 ipc_kmsg_t kmsg,
276 ipc_port_t port);
277
278/* Clear preallocated message buffer binding */
279extern void ipc_kmsg_clear_prealloc(
280 ipc_kmsg_t kmsg,
281 ipc_port_t port);
282
283/* Allocate a kernel message buffer and copy a user message to the buffer */
284extern mach_msg_return_t ipc_kmsg_get(
285 mach_vm_address_t msg_addr,
286 mach_msg_size_t size,
287 ipc_kmsg_t *kmsgp);
288
289/* Allocate a kernel message buffer and copy a kernel message to the buffer */
290extern mach_msg_return_t ipc_kmsg_get_from_kernel(
291 mach_msg_header_t *msg,
292 mach_msg_size_t size,
293 ipc_kmsg_t *kmsgp);
294
295/* Send a message to a port */
296extern mach_msg_return_t ipc_kmsg_send(
297 ipc_kmsg_t kmsg,
298 mach_msg_option_t option,
299 mach_msg_timeout_t timeout_val);
300
301/* Copy a kernel message buffer to a user message */
302extern mach_msg_return_t ipc_kmsg_put(
303 ipc_kmsg_t kmsg,
304 mach_msg_option_t option,
305 mach_vm_address_t rcv_addr,
306 mach_msg_size_t rcv_size,
307 mach_msg_size_t trailer_size,
308 mach_msg_size_t *size);
309
310/* Copy a kernel message buffer to a kernel message */
311extern void ipc_kmsg_put_to_kernel(
312 mach_msg_header_t *msg,
313 ipc_kmsg_t kmsg,
314 mach_msg_size_t size);
315
316/* Copyin port rights in the header of a message */
317extern mach_msg_return_t ipc_kmsg_copyin_header(
318 ipc_kmsg_t kmsg,
319 ipc_space_t space,
320 mach_msg_priority_t override,
321 mach_msg_option_t *optionp);
322
323/* Copyin port rights and out-of-line memory from a user message */
324extern mach_msg_return_t ipc_kmsg_copyin(
325 ipc_kmsg_t kmsg,
326 ipc_space_t space,
327 vm_map_t map,
328 mach_msg_priority_t override,
329 mach_msg_option_t *optionp);
330
331/* Copyin port rights and out-of-line memory from a kernel message */
332extern mach_msg_return_t ipc_kmsg_copyin_from_kernel(
333 ipc_kmsg_t kmsg);
334
335#if IKM_SUPPORT_LEGACY
336extern mach_msg_return_t ipc_kmsg_copyin_from_kernel_legacy(
337 ipc_kmsg_t kmsg);
338#endif
339
340/* Copyout port rights in the header of a message */
341extern mach_msg_return_t ipc_kmsg_copyout_header(
342 ipc_kmsg_t kmsg,
343 ipc_space_t space,
344 mach_msg_option_t option);
345
346/* Copyout a port right returning a name */
347extern mach_msg_return_t ipc_kmsg_copyout_object(
348 ipc_space_t space,
349 ipc_object_t object,
350 mach_msg_type_name_t msgt_name,
351 mach_port_name_t *namep);
352
353/* Copyout the header and body to a user message */
354extern mach_msg_return_t ipc_kmsg_copyout(
355 ipc_kmsg_t kmsg,
356 ipc_space_t space,
357 vm_map_t map,
358 mach_msg_body_t *slist,
359 mach_msg_option_t option);
360
361/* Copyout port rights and out-of-line memory from the body of a message */
362extern mach_msg_return_t ipc_kmsg_copyout_body(
363 ipc_kmsg_t kmsg,
364 ipc_space_t space,
365 vm_map_t map,
366 mach_msg_body_t *slist);
367
368/* Copyout port rights and out-of-line memory to a user message,
369 not reversing the ports in the header */
370extern mach_msg_return_t ipc_kmsg_copyout_pseudo(
371 ipc_kmsg_t kmsg,
372 ipc_space_t space,
373 vm_map_t map,
374 mach_msg_body_t *slist);
375
376/* Compute size of message as copied out to the specified space/map */
377extern mach_msg_size_t ipc_kmsg_copyout_size(
378 ipc_kmsg_t kmsg,
379 vm_map_t map);
380
381/* Copyout the destination port in the message */
382extern void ipc_kmsg_copyout_dest(
383 ipc_kmsg_t kmsg,
384 ipc_space_t space);
385
386/* kernel's version of ipc_kmsg_copyout_dest */
387extern void ipc_kmsg_copyout_to_kernel(
388 ipc_kmsg_t kmsg,
389 ipc_space_t space);
390
391#if IKM_SUPPORT_LEGACY
392extern void ipc_kmsg_copyout_to_kernel_legacy(
393 ipc_kmsg_t kmsg,
394 ipc_space_t space);
395#endif
396
397extern mach_msg_trailer_size_t
398ipc_kmsg_add_trailer(ipc_kmsg_t kmsg, ipc_space_t space,
399 mach_msg_option_t option, thread_t thread,
400 mach_port_seqno_t seqno, boolean_t minimal_trailer,
401 mach_vm_offset_t context);
402
403#if (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD)
404extern void ipc_kmsg_trace_send(ipc_kmsg_t kmsg,
405 mach_msg_option_t option);
406#else
407#define ipc_kmsg_trace_send(a,b) do { } while (0)
408#endif
409
410#endif /* _IPC_IPC_KMSG_H_ */
411
412