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