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 | |
106 | typedef natural_t mach_port_name_t; |
107 | typedef 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 | */ |
137 | struct ipc_port ; |
138 | |
139 | #endif /* MACH_KERNEL_PRIVATE */ |
140 | |
141 | typedef 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 | |
148 | typedef 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 | |
181 | typedef 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 | |
239 | typedef 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 | |
249 | typedef natural_t mach_port_type_t; |
250 | typedef 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 | |
284 | typedef natural_t mach_port_urefs_t; |
285 | typedef integer_t mach_port_delta_t; /* change in urefs */ |
286 | |
287 | /* Attributes of ports. (See mach_port_get_receive_status.) */ |
288 | |
289 | typedef natural_t mach_port_seqno_t; /* sequence number */ |
290 | typedef natural_t mach_port_mscount_t; /* make-send count */ |
291 | typedef natural_t mach_port_msgcount_t; /* number of msgs */ |
292 | typedef 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 */ |
299 | typedef unsigned int mach_port_srights_t; /* status of send rights */ |
300 | |
301 | typedef 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 | |
324 | typedef 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 | |
336 | typedef 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 | |
342 | typedef integer_t *mach_port_info_t; /* varying array of natural_t */ |
343 | |
344 | /* Flavors for mach_port_get/set_attributes() */ |
345 | typedef 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 | */ |
365 | typedef 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 | */ |
391 | typedef 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 | |
397 | typedef 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 */ |
407 | enum 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 | */ |
435 | typedef mach_port_t port_t; |
436 | typedef mach_port_name_t port_name_t; |
437 | typedef 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 | |