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