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 */ 54 typedef mach_port_t mach_voucher_t; 55 #define MACH_VOUCHER_NULL ((mach_voucher_t) 0) 56 57 typedef mach_port_name_t mach_voucher_name_t; 58 #define MACH_VOUCHER_NAME_NULL ((mach_voucher_name_t) 0) 59 60 typedef 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) 68 typedef mach_voucher_t ipc_voucher_t; 69 #else 70 #if !defined(MACH_KERNEL_PRIVATE) 71 struct ipc_voucher; 72 #endif 73 typedef 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 */ 82 typedef 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 */ 92 typedef uint32_t mach_voucher_attr_key_t; 93 typedef 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 #define MACH_VOUCHER_ATTR_KEY_PTHPRIORITY ((mach_voucher_attr_key_t)4) 103 104 #define MACH_VOUCHER_ATTR_KEY_USER_DATA ((mach_voucher_attr_key_t)7) 105 #define MACH_VOUCHER_ATTR_KEY_BITS MACH_VOUCHER_ATTR_KEY_USER_DATA /* deprecated */ 106 #define MACH_VOUCHER_ATTR_KEY_TEST ((mach_voucher_attr_key_t)8) 107 108 #define MACH_VOUCHER_ATTR_KEY_NUM_WELL_KNOWN MACH_VOUCHER_ATTR_KEY_TEST 109 110 /* 111 * mach_voucher_attr_content_t 112 * 113 * Data passed to a resource manager for modifying an attribute 114 * value or returned from the resource manager in response to a 115 * request to externalize the current value for that attribute. 116 */ 117 typedef uint8_t *mach_voucher_attr_content_t; 118 typedef uint32_t mach_voucher_attr_content_size_t; 119 120 /* 121 * mach_voucher_attr_command_t - The private verbs implemented by each voucher 122 * attribute manager via mach_voucher_attr_command(). 123 */ 124 typedef uint32_t mach_voucher_attr_command_t; 125 126 /* 127 * mach_voucher_attr_recipe_command_t 128 * 129 * The verbs used to create/morph a voucher attribute value. 130 * We define some system-wide commands here - related to creation, and transport of 131 * vouchers and attributes. Additional commands can be defined by, and supported by, 132 * individual attribute resource managers. 133 */ 134 typedef uint32_t mach_voucher_attr_recipe_command_t; 135 typedef mach_voucher_attr_recipe_command_t *mach_voucher_attr_recipe_command_array_t; 136 137 #define MACH_VOUCHER_ATTR_NOOP ((mach_voucher_attr_recipe_command_t)0) 138 #define MACH_VOUCHER_ATTR_COPY ((mach_voucher_attr_recipe_command_t)1) 139 #define MACH_VOUCHER_ATTR_REMOVE ((mach_voucher_attr_recipe_command_t)2) 140 #define MACH_VOUCHER_ATTR_SET_VALUE_HANDLE ((mach_voucher_attr_recipe_command_t)3) 141 #define MACH_VOUCHER_ATTR_AUTO_REDEEM ((mach_voucher_attr_recipe_command_t)4) 142 #define MACH_VOUCHER_ATTR_SEND_PREPROCESS ((mach_voucher_attr_recipe_command_t)5) 143 144 /* redeem is on its way out? */ 145 #define MACH_VOUCHER_ATTR_REDEEM ((mach_voucher_attr_recipe_command_t)10) 146 147 /* recipe command(s) for importance attribute manager */ 148 #define MACH_VOUCHER_ATTR_IMPORTANCE_SELF ((mach_voucher_attr_recipe_command_t)200) 149 150 /* recipe command(s) for bit-store attribute manager */ 151 #define MACH_VOUCHER_ATTR_USER_DATA_STORE ((mach_voucher_attr_recipe_command_t)211) 152 #define MACH_VOUCHER_ATTR_BITS_STORE MACH_VOUCHER_ATTR_USER_DATA_STORE /* deprecated */ 153 154 /* recipe command(s) for test attribute manager */ 155 #define MACH_VOUCHER_ATTR_TEST_STORE MACH_VOUCHER_ATTR_USER_DATA_STORE 156 157 /* 158 * mach_voucher_attr_recipe_t 159 * 160 * An element in a recipe list to create a voucher. 161 */ 162 #pragma pack(push, 1) 163 164 typedef struct mach_voucher_attr_recipe_data { 165 mach_voucher_attr_key_t key; 166 mach_voucher_attr_recipe_command_t command; 167 mach_voucher_name_t previous_voucher; 168 mach_voucher_attr_content_size_t content_size; 169 uint8_t content[]; 170 } mach_voucher_attr_recipe_data_t; 171 typedef mach_voucher_attr_recipe_data_t *mach_voucher_attr_recipe_t; 172 typedef mach_msg_type_number_t mach_voucher_attr_recipe_size_t; 173 174 /* Make the above palatable to MIG */ 175 typedef uint8_t *mach_voucher_attr_raw_recipe_t; 176 typedef mach_voucher_attr_raw_recipe_t mach_voucher_attr_raw_recipe_array_t; 177 typedef mach_msg_type_number_t mach_voucher_attr_raw_recipe_size_t; 178 typedef mach_msg_type_number_t mach_voucher_attr_raw_recipe_array_size_t; 179 180 #define MACH_VOUCHER_ATTR_MAX_RAW_RECIPE_ARRAY_SIZE 5120 181 #define MACH_VOUCHER_TRAP_STACK_LIMIT 256 182 183 #pragma pack(pop) 184 185 /* 186 * VOUCHER ATTRIBUTE MANAGER Writer types 187 */ 188 189 /* 190 * mach_voucher_attr_manager_t 191 * 192 * A handle through which the mach voucher mechanism communicates with the voucher 193 * attribute manager for a given attribute key. 194 */ 195 typedef mach_port_t mach_voucher_attr_manager_t; 196 #define MACH_VOUCHER_ATTR_MANAGER_NULL ((mach_voucher_attr_manager_t) 0) 197 198 /* 199 * mach_voucher_attr_control_t 200 * 201 * A handle provided to the voucher attribute manager for a given attribute key 202 * through which it makes inquiries or control operations of the mach voucher mechanism. 203 */ 204 typedef mach_port_t mach_voucher_attr_control_t; 205 #define MACH_VOUCHER_ATTR_CONTROL_NULL ((mach_voucher_attr_control_t) 0) 206 207 /* 208 * These types are different in-kernel vs user-space. They are ports in user-space, 209 * pointers to opaque structs in most of the kernel, and pointers to known struct 210 * types in the Mach portion of the kernel. 211 */ 212 #if !defined(KERNEL) 213 typedef mach_port_t ipc_voucher_attr_manager_t; 214 typedef mach_port_t ipc_voucher_attr_control_t; 215 #else 216 #if !defined(MACH_KERNEL_PRIVATE) 217 struct ipc_voucher_attr_manager; 218 struct ipc_voucher_attr_control; 219 #endif 220 typedef const struct ipc_voucher_attr_manager *ipc_voucher_attr_manager_t; 221 typedef struct ipc_voucher_attr_control *ipc_voucher_attr_control_t; 222 #endif 223 #define IPC_VOUCHER_ATTR_MANAGER_NULL ((ipc_voucher_attr_manager_t) 0) 224 #define IPC_VOUCHER_ATTR_CONTROL_NULL ((ipc_voucher_attr_control_t) 0) 225 226 /* 227 * mach_voucher_attr_value_handle_t 228 * 229 * The private handle that the voucher attribute manager provides to 230 * the mach voucher mechanism to represent a given attr content/value. 231 */ 232 typedef uint64_t mach_voucher_attr_value_handle_t __kernel_ptr_semantics; 233 typedef mach_voucher_attr_value_handle_t *mach_voucher_attr_value_handle_array_t; 234 235 typedef mach_msg_type_number_t mach_voucher_attr_value_handle_array_size_t; 236 #define MACH_VOUCHER_ATTR_VALUE_MAX_NESTED ((mach_voucher_attr_value_handle_array_size_t)4) 237 238 typedef uint32_t mach_voucher_attr_value_reference_t; 239 typedef uint32_t mach_voucher_attr_value_flags_t; 240 #define MACH_VOUCHER_ATTR_VALUE_FLAGS_NONE ((mach_voucher_attr_value_flags_t)0) 241 #define MACH_VOUCHER_ATTR_VALUE_FLAGS_PERSIST ((mach_voucher_attr_value_flags_t)1) 242 243 /* USE - TBD */ 244 typedef uint32_t mach_voucher_attr_control_flags_t; 245 #define MACH_VOUCHER_ATTR_CONTROL_FLAGS_NONE ((mach_voucher_attr_control_flags_t)0) 246 247 /* 248 * Commands and types for the IPC Importance Attribute Manager 249 * 250 * These are the valid mach_voucher_attr_command() options with the 251 * MACH_VOUCHER_ATTR_KEY_IMPORTANCE key. 252 */ 253 #define MACH_VOUCHER_IMPORTANCE_ATTR_ADD_EXTERNAL 1 /* Add some number of external refs (not supported) */ 254 #define MACH_VOUCHER_IMPORTANCE_ATTR_DROP_EXTERNAL 2 /* Drop some number of external refs */ 255 typedef uint32_t mach_voucher_attr_importance_refs; 256 257 /* 258 * Activity id Generation defines 259 */ 260 #define MACH_ACTIVITY_ID_COUNT_MAX 16 261 262 #endif /* _MACH_VOUCHER_TYPES_H_ */ 263