osfmk/mach/mach_voucher_types.h

   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  */
  53 typedef mach_port_t             mach_voucher_t;
  54 #define MACH_VOUCHER_NULL       ((mach_voucher_t) 0)
  55
  56 typedef mach_port_name_t        mach_voucher_name_t;
  57 #define MACH_VOUCHER_NAME_NULL  ((mach_voucher_name_t) 0)
  58
  59 typedef 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)
  67 typedef mach_voucher_t          ipc_voucher_t;
  68 #else
  69 #if !defined(MACH_KERNEL_PRIVATE)
  70 struct ipc_voucher              ;
  71 #endif
  72 typedef 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  */
  81 typedef 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  */
  91 typedef uint32_t mach_voucher_attr_key_t;
  92 typedef 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  */
 115 typedef uint8_t *mach_voucher_attr_content_t;
 116 typedef 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  */
 122 typedef 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  */
 132 typedef uint32_t mach_voucher_attr_recipe_command_t;
 133 typedef 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
 160 typedef 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;
 167 typedef mach_voucher_attr_recipe_data_t *mach_voucher_attr_recipe_t;
 168 typedef mach_msg_type_number_t mach_voucher_attr_recipe_size_t;
 169
 170 /* Make the above palatable to MIG */
 171 typedef uint8_t *mach_voucher_attr_raw_recipe_t;
 172 typedef mach_voucher_attr_raw_recipe_t mach_voucher_attr_raw_recipe_array_t;
 173 typedef mach_msg_type_number_t mach_voucher_attr_raw_recipe_size_t;
 174 typedef 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  */
 188 typedef 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  */
 197 typedef 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)
 206 typedef mach_port_t             ipc_voucher_attr_manager_t;
 207 typedef mach_port_t             ipc_voucher_attr_control_t;
 208 #else
 209 #if !defined(MACH_KERNEL_PRIVATE)
 210 struct ipc_voucher_attr_manager ;
 211 struct ipc_voucher_attr_control ;
 212 #endif
 213 typedef struct ipc_voucher_attr_manager *ipc_voucher_attr_manager_t;
 214 typedef 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  */
 225 typedef uint64_t mach_voucher_attr_value_handle_t;
 226 typedef mach_voucher_attr_value_handle_t *mach_voucher_attr_value_handle_array_t;
 227
 228 typedef 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
 231 typedef uint32_t mach_voucher_attr_value_reference_t;
 232
 233 /* USE - TBD */
 234 typedef 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 */
 245 typedef uint32_t mach_voucher_attr_importance_refs;
 246
 247 #endif  /* _MACH_VOUCHER_TYPES_H_ */