1/*
2 * Copyright (c) 2000-2006 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,1988,1987 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 */
62/*
63 */
64/*
65 * File: mach/port.h
66 *
67 * Definition of a Mach port
68 *
69 * Mach ports are the endpoints to Mach-implemented communications
70 * channels (usually uni-directional message queues, but other types
71 * also exist).
72 *
73 * Unique collections of these endpoints are maintained for each
74 * Mach task. Each Mach port in the task's collection is given a
75 * [task-local] name to identify it - and the the various "rights"
76 * held by the task for that specific endpoint.
77 *
78 * This header defines the types used to identify these Mach ports
79 * and the various rights associated with them. For more info see:
80 *
81 * <mach/mach_port.h> - manipulation of port rights in a given space
82 * <mach/message.h> - message queue [and port right passing] mechanism
83 *
84 */
85
86#ifndef _MACH_PORT_H_
87#define _MACH_PORT_H_
88
89#include <sys/cdefs.h>
90#include <stdint.h>
91#include <mach/boolean.h>
92#include <mach/machine/vm_types.h>
93
94/*
95 * mach_port_name_t - the local identity for a Mach port
96 *
97 * The name is Mach port namespace specific. It is used to
98 * identify the rights held for that port by the task whose
99 * namespace is implied [or specifically provided].
100 *
101 * Use of this type usually implies just a name - no rights.
102 * See mach_port_t for a type that implies a "named right."
103 *
104 */
105
106typedef natural_t mach_port_name_t;
107typedef mach_port_name_t *mach_port_name_array_t;
108
109#ifdef KERNEL
110
111/*
112 * mach_port_t - a named port right
113 *
114 * In the kernel, "rights" are represented [named] by pointers to
115 * the ipc port object in question. There is no port namespace for the
116 * rights to be collected.
117 *
118 * Actually, there is namespace for the kernel task. But most kernel
119 * code - including, but not limited to, Mach IPC code - lives in the
120 * limbo between the current user-level task and the "next" task. Very
121 * little of the kernel code runs in full kernel task context. So very
122 * little of it gets to use the kernel task's port name space.
123 *
124 * Because of this implementation approach, all in-kernel rights for
125 * a given port coalesce [have the same name/pointer]. The actual
126 * references are counted in the port itself. It is up to the kernel
127 * code in question to "just remember" how many [and what type of]
128 * rights it holds and handle them appropriately.
129 *
130 */
131
132#ifndef MACH_KERNEL_PRIVATE
133/*
134 * For kernel code that resides outside of Mach proper, we opaque the
135 * port structure definition.
136 */
137struct ipc_port ;
138
139#endif /* MACH_KERNEL_PRIVATE */
140
141typedef struct ipc_port *ipc_port_t;
142
143#define IPC_PORT_NULL ((ipc_port_t) 0UL)
144#define IPC_PORT_DEAD ((ipc_port_t)~0UL)
145#define IPC_PORT_VALID(port) \
146 ((port) != IPC_PORT_NULL && (port) != IPC_PORT_DEAD)
147
148typedef ipc_port_t mach_port_t;
149
150/*
151 * Since the 32-bit and 64-bit representations of ~0 are different,
152 * explicitly handle MACH_PORT_DEAD
153 */
154
155#define CAST_MACH_PORT_TO_NAME(x) ((mach_port_name_t)(uintptr_t)(x))
156#define CAST_MACH_NAME_TO_PORT(x) ((x) == MACH_PORT_DEAD ? (mach_port_t)IPC_PORT_DEAD : (mach_port_t)(uintptr_t)(x))
157
158#else /* KERNEL */
159
160/*
161 * mach_port_t - a named port right
162 *
163 * In user-space, "rights" are represented by the name of the
164 * right in the Mach port namespace. Even so, this type is
165 * presented as a unique one to more clearly denote the presence
166 * of a right coming along with the name.
167 *
168 * Often, various rights for a port held in a single name space
169 * will coalesce and are, therefore, be identified by a single name
170 * [this is the case for send and receive rights]. But not
171 * always [send-once rights currently get a unique name for
172 * each right].
173 *
174 */
175
176#include <sys/_types.h>
177#include <sys/_types/_mach_port_t.h>
178
179#endif /* KERNEL */
180
181typedef mach_port_t *mach_port_array_t;
182
183/*
184 * MACH_PORT_NULL is a legal value that can be carried in messages.
185 * It indicates the absence of any port or port rights. (A port
186 * argument keeps the message from being "simple", even if the
187 * value is MACH_PORT_NULL.) The value MACH_PORT_DEAD is also a legal
188 * value that can be carried in messages. It indicates
189 * that a port right was present, but it died.
190 */
191
192#define MACH_PORT_NULL 0 /* intentional loose typing */
193#define MACH_PORT_DEAD ((mach_port_name_t) ~0)
194#define MACH_PORT_VALID(name) \
195 (((name) != MACH_PORT_NULL) && \
196 ((name) != MACH_PORT_DEAD))
197
198
199/*
200 * For kernel-selected [assigned] port names, the name is
201 * comprised of two parts: a generation number and an index.
202 * This approach keeps the exact same name from being generated
203 * and reused too quickly [to catch right/reference counting bugs].
204 * The dividing line between the constituent parts is exposed so
205 * that efficient "mach_port_name_t to data structure pointer"
206 * conversion implementation can be made. But it is possible
207 * for user-level code to assign their own names to Mach ports.
208 * These are not required to participate in this algorithm. So
209 * care should be taken before "assuming" this model.
210 *
211 */
212
213#ifndef NO_PORT_GEN
214
215#define MACH_PORT_INDEX(name) ((name) >> 8)
216#define MACH_PORT_GEN(name) (((name) & 0xff) << 24)
217#define MACH_PORT_MAKE(index, gen) \
218 (((index) << 8) | (gen) >> 24)
219
220#else /* NO_PORT_GEN */
221
222#define MACH_PORT_INDEX(name) (name)
223#define MACH_PORT_GEN(name) (0)
224#define MACH_PORT_MAKE(index, gen) (index)
225
226#endif /* NO_PORT_GEN */
227
228
229/*
230 * These are the different rights a task may have for a port.
231 * The MACH_PORT_RIGHT_* definitions are used as arguments
232 * to mach_port_allocate, mach_port_get_refs, etc, to specify
233 * a particular right to act upon. The mach_port_names and
234 * mach_port_type calls return bitmasks using the MACH_PORT_TYPE_*
235 * definitions. This is because a single name may denote
236 * multiple rights.
237 */
238
239typedef natural_t mach_port_right_t;
240
241#define MACH_PORT_RIGHT_SEND ((mach_port_right_t) 0)
242#define MACH_PORT_RIGHT_RECEIVE ((mach_port_right_t) 1)
243#define MACH_PORT_RIGHT_SEND_ONCE ((mach_port_right_t) 2)
244#define MACH_PORT_RIGHT_PORT_SET ((mach_port_right_t) 3)
245#define MACH_PORT_RIGHT_DEAD_NAME ((mach_port_right_t) 4)
246#define MACH_PORT_RIGHT_LABELH ((mach_port_right_t) 5)
247#define MACH_PORT_RIGHT_NUMBER ((mach_port_right_t) 6)
248
249typedef natural_t mach_port_type_t;
250typedef mach_port_type_t *mach_port_type_array_t;
251
252#define MACH_PORT_TYPE(right) \
253 ((mach_port_type_t)(((mach_port_type_t) 1) \
254 << ((right) + ((mach_port_right_t) 16))))
255#define MACH_PORT_TYPE_NONE ((mach_port_type_t) 0L)
256#define MACH_PORT_TYPE_SEND MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND)
257#define MACH_PORT_TYPE_RECEIVE MACH_PORT_TYPE(MACH_PORT_RIGHT_RECEIVE)
258#define MACH_PORT_TYPE_SEND_ONCE MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND_ONCE)
259#define MACH_PORT_TYPE_PORT_SET MACH_PORT_TYPE(MACH_PORT_RIGHT_PORT_SET)
260#define MACH_PORT_TYPE_DEAD_NAME MACH_PORT_TYPE(MACH_PORT_RIGHT_DEAD_NAME)
261#define MACH_PORT_TYPE_LABELH MACH_PORT_TYPE(MACH_PORT_RIGHT_LABELH)
262
263/* Convenient combinations. */
264
265#define MACH_PORT_TYPE_SEND_RECEIVE \
266 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_RECEIVE)
267#define MACH_PORT_TYPE_SEND_RIGHTS \
268 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_SEND_ONCE)
269#define MACH_PORT_TYPE_PORT_RIGHTS \
270 (MACH_PORT_TYPE_SEND_RIGHTS|MACH_PORT_TYPE_RECEIVE)
271#define MACH_PORT_TYPE_PORT_OR_DEAD \
272 (MACH_PORT_TYPE_PORT_RIGHTS|MACH_PORT_TYPE_DEAD_NAME)
273#define MACH_PORT_TYPE_ALL_RIGHTS \
274 (MACH_PORT_TYPE_PORT_OR_DEAD|MACH_PORT_TYPE_PORT_SET)
275
276/* Dummy type bits that mach_port_type/mach_port_names can return. */
277
278#define MACH_PORT_TYPE_DNREQUEST 0x80000000
279#define MACH_PORT_TYPE_SPREQUEST 0x40000000
280#define MACH_PORT_TYPE_SPREQUEST_DELAYED 0x20000000
281
282/* User-references for capabilities. */
283
284typedef natural_t mach_port_urefs_t;
285typedef integer_t mach_port_delta_t; /* change in urefs */
286
287/* Attributes of ports. (See mach_port_get_receive_status.) */
288
289typedef natural_t mach_port_seqno_t; /* sequence number */
290typedef natural_t mach_port_mscount_t; /* make-send count */
291typedef natural_t mach_port_msgcount_t; /* number of msgs */
292typedef natural_t mach_port_rights_t; /* number of rights */
293
294/*
295 * Are there outstanding send rights for a given port?
296 */
297#define MACH_PORT_SRIGHTS_NONE 0 /* no srights */
298#define MACH_PORT_SRIGHTS_PRESENT 1 /* srights */
299typedef unsigned int mach_port_srights_t; /* status of send rights */
300
301typedef struct mach_port_status {
302 mach_port_rights_t mps_pset; /* count of containing port sets */
303 mach_port_seqno_t mps_seqno; /* sequence number */
304 mach_port_mscount_t mps_mscount; /* make-send count */
305 mach_port_msgcount_t mps_qlimit; /* queue limit */
306 mach_port_msgcount_t mps_msgcount; /* number in the queue */
307 mach_port_rights_t mps_sorights; /* how many send-once rights */
308 boolean_t mps_srights; /* do send rights exist? */
309 boolean_t mps_pdrequest; /* port-deleted requested? */
310 boolean_t mps_nsrequest; /* no-senders requested? */
311 natural_t mps_flags; /* port flags */
312} mach_port_status_t;
313
314/* System-wide values for setting queue limits on a port */
315#define MACH_PORT_QLIMIT_ZERO (0)
316#define MACH_PORT_QLIMIT_BASIC (5)
317#define MACH_PORT_QLIMIT_SMALL (16)
318#define MACH_PORT_QLIMIT_LARGE (1024)
319#define MACH_PORT_QLIMIT_KERNEL (65534)
320#define MACH_PORT_QLIMIT_MIN MACH_PORT_QLIMIT_ZERO
321#define MACH_PORT_QLIMIT_DEFAULT MACH_PORT_QLIMIT_BASIC
322#define MACH_PORT_QLIMIT_MAX MACH_PORT_QLIMIT_LARGE
323
324typedef struct mach_port_limits {
325 mach_port_msgcount_t mpl_qlimit; /* number of msgs */
326} mach_port_limits_t;
327
328/* Possible values for mps_flags (part of mach_port_status_t) */
329#define MACH_PORT_STATUS_FLAG_TEMPOWNER 0x01
330#define MACH_PORT_STATUS_FLAG_GUARDED 0x02
331#define MACH_PORT_STATUS_FLAG_STRICT_GUARD 0x04
332#define MACH_PORT_STATUS_FLAG_IMP_DONATION 0x08
333#define MACH_PORT_STATUS_FLAG_REVIVE 0x10
334#define MACH_PORT_STATUS_FLAG_TASKPTR 0x20
335
336typedef struct mach_port_info_ext {
337 mach_port_status_t mpie_status;
338 mach_port_msgcount_t mpie_boost_cnt;
339 uint32_t reserved[6];
340} mach_port_info_ext_t;
341
342typedef integer_t *mach_port_info_t; /* varying array of natural_t */
343
344/* Flavors for mach_port_get/set_attributes() */
345typedef int mach_port_flavor_t;
346#define MACH_PORT_LIMITS_INFO 1 /* uses mach_port_limits_t */
347#define MACH_PORT_RECEIVE_STATUS 2 /* uses mach_port_status_t */
348#define MACH_PORT_DNREQUESTS_SIZE 3 /* info is int */
349#define MACH_PORT_TEMPOWNER 4 /* indicates receive right will be reassigned to another task */
350#define MACH_PORT_IMPORTANCE_RECEIVER 5 /* indicates recieve right accepts priority donation */
351#define MACH_PORT_DENAP_RECEIVER 6 /* indicates receive right accepts de-nap donation */
352#define MACH_PORT_INFO_EXT 7 /* uses mach_port_info_ext_t */
353
354#define MACH_PORT_LIMITS_INFO_COUNT ((natural_t) \
355 (sizeof(mach_port_limits_t)/sizeof(natural_t)))
356#define MACH_PORT_RECEIVE_STATUS_COUNT ((natural_t) \
357 (sizeof(mach_port_status_t)/sizeof(natural_t)))
358#define MACH_PORT_DNREQUESTS_SIZE_COUNT 1
359#define MACH_PORT_INFO_EXT_COUNT ((natural_t) \
360 (sizeof(mach_port_info_ext_t)/sizeof(natural_t)))
361/*
362 * Structure used to pass information about port allocation requests.
363 * Must be padded to 64-bits total length.
364 */
365typedef struct mach_port_qos {
366 unsigned int name:1; /* name given */
367 unsigned int prealloc:1; /* prealloced message */
368 boolean_t pad1:30;
369 natural_t len;
370} mach_port_qos_t;
371
372/* Mach Port Guarding definitions */
373
374/*
375 * Flags for mach_port_options (used for
376 * invocation of mach_port_construct).
377 * Indicates attributes to be set for the newly
378 * allocated port.
379 */
380#define MPO_CONTEXT_AS_GUARD 0x01 /* Add guard to the port */
381#define MPO_QLIMIT 0x02 /* Set qlimit for the port msg queue */
382#define MPO_TEMPOWNER 0x04 /* Set the tempowner bit of the port */
383#define MPO_IMPORTANCE_RECEIVER 0x08 /* Mark the port as importance receiver */
384#define MPO_INSERT_SEND_RIGHT 0x10 /* Insert a send right for the port */
385#define MPO_STRICT 0x20 /* Apply strict guarding for port */
386#define MPO_DENAP_RECEIVER 0x40 /* Mark the port as App de-nap receiver */
387/*
388 * Structure to define optional attributes for a newly
389 * constructed port.
390 */
391typedef struct mach_port_options {
392 uint32_t flags; /* Flags defining attributes for port */
393 mach_port_limits_t mpl; /* Message queue limit for port */
394 uint64_t reserved[2]; /* Reserved */
395}mach_port_options_t;
396
397typedef mach_port_options_t *mach_port_options_ptr_t;
398
399/*
400 * EXC_GUARD represents a guard violation for both
401 * mach ports and file descriptors. GUARD_TYPE_ is used
402 * to differentiate among them.
403 */
404#define GUARD_TYPE_MACH_PORT 0x1
405
406/* Reasons for exception for a guarded mach port */
407enum mach_port_guard_exception_codes {
408 kGUARD_EXC_DESTROY = 1u << 0,
409 kGUARD_EXC_MOD_REFS = 1u << 1,
410 kGUARD_EXC_SET_CONTEXT = 1u << 2,
411 kGUARD_EXC_UNGUARDED = 1u << 3,
412 kGUARD_EXC_INCORRECT_GUARD = 1u << 4,
413 /* start of non-fatal guards */
414 kGUARD_EXC_INVALID_RIGHT = 1u << 8,
415 kGUARD_EXC_INVALID_NAME = 1u << 9,
416 kGUARD_EXC_INVALID_VALUE = 1u << 10,
417 kGUARD_EXC_INVALID_ARGUMENT = 1u << 11,
418 kGUARD_EXC_RIGHT_EXISTS = 1u << 12,
419 kGUARD_EXC_KERN_NO_SPACE = 1u << 13,
420 kGUARD_EXC_KERN_FAILURE = 1u << 14,
421 kGUARD_EXC_KERN_RESOURCE = 1u << 15,
422 kGUARD_EXC_SEND_INVALID_REPLY = 1u << 16,
423 kGUARD_EXC_SEND_INVALID_VOUCHER = 1u << 16,
424 kGUARD_EXC_SEND_INVALID_RIGHT = 1u << 17,
425 kGUARD_EXC_RCV_INVALID_NAME = 1u << 18,
426 kGUARD_EXC_RCV_INVALID_NOTIFY = 1u << 19
427};
428
429#if !__DARWIN_UNIX03 && !defined(_NO_PORT_T_FROM_MACH)
430/*
431 * Mach 3.0 renamed everything to have mach_ in front of it.
432 * These types and macros are provided for backward compatibility
433 * but are deprecated.
434 */
435typedef mach_port_t port_t;
436typedef mach_port_name_t port_name_t;
437typedef mach_port_name_t *port_name_array_t;
438
439#define PORT_NULL ((port_t) 0)
440#define PORT_DEAD ((port_t) ~0)
441#define PORT_VALID(name) \
442 ((port_t)(name) != PORT_NULL && (port_t)(name) != PORT_DEAD)
443
444#endif /* !__DARWIN_UNIX03 && !_NO_PORT_T_FROM_MACH */
445
446#endif /* _MACH_PORT_H_ */
447