1/*
2 * Copyright (c) 2013 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#ifndef _MACH_VOUCHER_TYPES_H_
30#define _MACH_VOUCHER_TYPES_H_
31
32#include <mach/std_types.h>
33#include <mach/port.h>
34#include <mach/message.h>
35
36/*
37 * Mach Voucher - an immutable collection of attribute value handles.
38 *
39 * The mach voucher is such that it can be passed between processes
40 * as a Mach port send right (by convention in the mach_msg_header_t’s
41 * msgh_voucher field).
42 *
43 * You may construct a new mach voucher by passing a construction
44 * recipe to host_create_mach_voucher(). The construction recipe supports
45 * generic commands for copying, removing, and redeeming attribute value
46 * handles from previous vouchers, or running attribute-mananger-specific
47 * commands within the recipe.
48 *
49 * Once the set of attribute value handles is constructed and returned,
50 * that set will not change for the life of the voucher (just because the
51 * attribute value handle itself doesn't change, the value the handle refers
52 * to is free to change at will).
53 */
54typedef mach_port_t mach_voucher_t;
55#define MACH_VOUCHER_NULL ((mach_voucher_t) 0)
56
57typedef mach_port_name_t mach_voucher_name_t;
58#define MACH_VOUCHER_NAME_NULL ((mach_voucher_name_t) 0)
59
60typedef mach_voucher_name_t *mach_voucher_name_array_t;
61#define MACH_VOUCHER_NAME_ARRAY_NULL ((mach_voucher_name_array_t) 0)
62
63/*
64 * This type changes appearance between user-space and kernel. It is
65 * a port at user-space and a reference to an ipc_voucher structure in-kernel.
66 */
67#if !defined(KERNEL)
68typedef mach_voucher_t ipc_voucher_t;
69#else
70#if !defined(MACH_KERNEL_PRIVATE)
71struct ipc_voucher;
72#endif
73typedef struct ipc_voucher *ipc_voucher_t;
74#endif
75#define IPC_VOUCHER_NULL ((ipc_voucher_t) 0)
76
77/*
78 * mach_voucher_selector_t - A means of specifying which thread/task value to extract -
79 * the current voucher set at this level, or a voucher representing
80 * the full [layered] effective value for the task/thread.
81 */
82typedef uint32_t mach_voucher_selector_t;
83#define MACH_VOUCHER_SELECTOR_CURRENT ((mach_voucher_selector_t)0)
84#define MACH_VOUCHER_SELECTOR_EFFECTIVE ((mach_voucher_selector_t)1)
85
86
87/*
88 * mach_voucher_attr_key_t - The key used to identify a particular managed resource or
89 * to select the specific resource manager’s data associated
90 * with a given voucher.
91 */
92typedef uint32_t mach_voucher_attr_key_t;
93typedef mach_voucher_attr_key_t *mach_voucher_attr_key_array_t;
94
95#define MACH_VOUCHER_ATTR_KEY_ALL ((mach_voucher_attr_key_t)~0)
96#define MACH_VOUCHER_ATTR_KEY_NONE ((mach_voucher_attr_key_t)0)
97
98/* other well-known-keys will be added here */
99#define MACH_VOUCHER_ATTR_KEY_ATM ((mach_voucher_attr_key_t)1)
100#define MACH_VOUCHER_ATTR_KEY_IMPORTANCE ((mach_voucher_attr_key_t)2)
101#define MACH_VOUCHER_ATTR_KEY_BANK ((mach_voucher_attr_key_t)3)
102
103/* following keys have been removed from embedded platforms */
104#define MACH_VOUCHER_ATTR_KEY_PTHPRIORITY ((mach_voucher_attr_key_t)4)
105#define MACH_VOUCHER_ATTR_KEY_USER_DATA ((mach_voucher_attr_key_t)7)
106#define MACH_VOUCHER_ATTR_KEY_BITS MACH_VOUCHER_ATTR_KEY_USER_DATA
107#define MACH_VOUCHER_ATTR_KEY_TEST ((mach_voucher_attr_key_t)8)
108
109/* not used, for compatibility only */
110#define MACH_VOUCHER_ATTR_KEY_NUM_WELL_KNOWN MACH_VOUCHER_ATTR_KEY_TEST
111
112/*
113 * mach_voucher_attr_content_t
114 *
115 * Data passed to a resource manager for modifying an attribute
116 * value or returned from the resource manager in response to a
117 * request to externalize the current value for that attribute.
118 */
119typedef uint8_t *mach_voucher_attr_content_t;
120typedef uint32_t mach_voucher_attr_content_size_t;
121
122/*
123 * mach_voucher_attr_command_t - The private verbs implemented by each voucher
124 * attribute manager via mach_voucher_attr_command().
125 */
126typedef uint32_t mach_voucher_attr_command_t;
127
128/*
129 * mach_voucher_attr_recipe_command_t
130 *
131 * The verbs used to create/morph a voucher attribute value.
132 * We define some system-wide commands here - related to creation, and transport of
133 * vouchers and attributes. Additional commands can be defined by, and supported by,
134 * individual attribute resource managers.
135 */
136typedef uint32_t mach_voucher_attr_recipe_command_t;
137typedef mach_voucher_attr_recipe_command_t *mach_voucher_attr_recipe_command_array_t;
138
139#define MACH_VOUCHER_ATTR_NOOP ((mach_voucher_attr_recipe_command_t)0)
140#define MACH_VOUCHER_ATTR_COPY ((mach_voucher_attr_recipe_command_t)1)
141#define MACH_VOUCHER_ATTR_REMOVE ((mach_voucher_attr_recipe_command_t)2)
142#define MACH_VOUCHER_ATTR_SET_VALUE_HANDLE ((mach_voucher_attr_recipe_command_t)3)
143#define MACH_VOUCHER_ATTR_AUTO_REDEEM ((mach_voucher_attr_recipe_command_t)4)
144#define MACH_VOUCHER_ATTR_SEND_PREPROCESS ((mach_voucher_attr_recipe_command_t)5)
145
146/* redeem is on its way out? */
147#define MACH_VOUCHER_ATTR_REDEEM ((mach_voucher_attr_recipe_command_t)10)
148
149/* recipe command(s) for importance attribute manager */
150#define MACH_VOUCHER_ATTR_IMPORTANCE_SELF ((mach_voucher_attr_recipe_command_t)200)
151
152/* recipe command(s) for bit-store attribute manager */
153#define MACH_VOUCHER_ATTR_USER_DATA_STORE ((mach_voucher_attr_recipe_command_t)211)
154#define MACH_VOUCHER_ATTR_BITS_STORE MACH_VOUCHER_ATTR_USER_DATA_STORE /* deprecated */
155
156/* recipe command(s) for test attribute manager */
157#define MACH_VOUCHER_ATTR_TEST_STORE MACH_VOUCHER_ATTR_USER_DATA_STORE
158
159/*
160 * mach_voucher_attr_recipe_t
161 *
162 * An element in a recipe list to create a voucher.
163 */
164#pragma pack(push, 1)
165
166typedef struct mach_voucher_attr_recipe_data {
167 mach_voucher_attr_key_t key;
168 mach_voucher_attr_recipe_command_t command;
169 mach_voucher_name_t previous_voucher;
170 mach_voucher_attr_content_size_t content_size;
171 uint8_t content[];
172} mach_voucher_attr_recipe_data_t;
173typedef mach_voucher_attr_recipe_data_t *mach_voucher_attr_recipe_t;
174typedef mach_msg_type_number_t mach_voucher_attr_recipe_size_t;
175
176/* Make the above palatable to MIG */
177typedef uint8_t *mach_voucher_attr_raw_recipe_t;
178typedef mach_voucher_attr_raw_recipe_t mach_voucher_attr_raw_recipe_array_t;
179typedef mach_msg_type_number_t mach_voucher_attr_raw_recipe_size_t;
180typedef mach_msg_type_number_t mach_voucher_attr_raw_recipe_array_size_t;
181
182#define MACH_VOUCHER_ATTR_MAX_RAW_RECIPE_ARRAY_SIZE 5120
183#define MACH_VOUCHER_TRAP_STACK_LIMIT 256
184
185#pragma pack(pop)
186
187/*
188 * VOUCHER ATTRIBUTE MANAGER Writer types
189 */
190
191/*
192 * mach_voucher_attr_manager_t
193 *
194 * A handle through which the mach voucher mechanism communicates with the voucher
195 * attribute manager for a given attribute key.
196 */
197typedef mach_port_t mach_voucher_attr_manager_t;
198#define MACH_VOUCHER_ATTR_MANAGER_NULL ((mach_voucher_attr_manager_t) 0)
199
200/*
201 * mach_voucher_attr_control_t
202 *
203 * A handle provided to the voucher attribute manager for a given attribute key
204 * through which it makes inquiries or control operations of the mach voucher mechanism.
205 */
206typedef mach_port_t mach_voucher_attr_control_t;
207#define MACH_VOUCHER_ATTR_CONTROL_NULL ((mach_voucher_attr_control_t) 0)
208
209/*
210 * These types are different in-kernel vs user-space. They are ports in user-space,
211 * pointers to opaque structs in most of the kernel, and pointers to known struct
212 * types in the Mach portion of the kernel.
213 */
214#if !defined(KERNEL)
215typedef mach_port_t ipc_voucher_attr_manager_t;
216typedef mach_port_t ipc_voucher_attr_control_t;
217#else
218#if !defined(MACH_KERNEL_PRIVATE)
219struct ipc_voucher_attr_manager;
220struct ipc_voucher_attr_control;
221#endif
222typedef const struct ipc_voucher_attr_manager *ipc_voucher_attr_manager_t;
223typedef struct ipc_voucher_attr_control *ipc_voucher_attr_control_t;
224#endif
225#define IPC_VOUCHER_ATTR_MANAGER_NULL ((ipc_voucher_attr_manager_t) 0)
226#define IPC_VOUCHER_ATTR_CONTROL_NULL ((ipc_voucher_attr_control_t) 0)
227
228/*
229 * mach_voucher_attr_value_handle_t
230 *
231 * The private handle that the voucher attribute manager provides to
232 * the mach voucher mechanism to represent a given attr content/value.
233 */
234typedef uint64_t mach_voucher_attr_value_handle_t __kernel_ptr_semantics;
235typedef mach_voucher_attr_value_handle_t *mach_voucher_attr_value_handle_array_t;
236
237typedef mach_msg_type_number_t mach_voucher_attr_value_handle_array_size_t;
238#define MACH_VOUCHER_ATTR_VALUE_MAX_NESTED ((mach_voucher_attr_value_handle_array_size_t)4)
239
240typedef uint32_t mach_voucher_attr_value_reference_t;
241typedef uint32_t mach_voucher_attr_value_flags_t;
242#define MACH_VOUCHER_ATTR_VALUE_FLAGS_NONE ((mach_voucher_attr_value_flags_t)0)
243#define MACH_VOUCHER_ATTR_VALUE_FLAGS_PERSIST ((mach_voucher_attr_value_flags_t)1)
244
245/* USE - TBD */
246typedef uint32_t mach_voucher_attr_control_flags_t;
247#define MACH_VOUCHER_ATTR_CONTROL_FLAGS_NONE ((mach_voucher_attr_control_flags_t)0)
248
249/*
250 * Commands and types for the IPC Importance Attribute Manager
251 *
252 * These are the valid mach_voucher_attr_command() options with the
253 * MACH_VOUCHER_ATTR_KEY_IMPORTANCE key.
254 */
255#define MACH_VOUCHER_IMPORTANCE_ATTR_ADD_EXTERNAL 1 /* Add some number of external refs (not supported) */
256#define MACH_VOUCHER_IMPORTANCE_ATTR_DROP_EXTERNAL 2 /* Drop some number of external refs */
257typedef uint32_t mach_voucher_attr_importance_refs;
258
259/*
260 * Activity id Generation defines
261 */
262#define MACH_ACTIVITY_ID_COUNT_MAX 16
263
264#endif /* _MACH_VOUCHER_TYPES_H_ */
265