os/voucher_private.h

   1 /*
   2  * Copyright (c) 2013-2014 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_APACHE_LICENSE_HEADER_START@
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * @APPLE_APACHE_LICENSE_HEADER_END@
  19  */
  20
  21 #ifndef __OS_VOUCHER_PRIVATE__
  22 #define __OS_VOUCHER_PRIVATE__
  23
  24 #ifndef __linux__
  25 #include <os/base.h>
  26 #endif
  27 #if __has_include(<mach/mach.h>)
  28 #include <os/object.h>
  29 #include <mach/mach.h>
  30 #endif
  31 #if __has_include(<bank/bank_types.h>)
  32 #include <bank/bank_types.h>
  33 #endif
  34 #if __has_include(<sys/persona.h>)
  35 #include <sys/persona.h>
  36 #endif
  37
  38 #ifndef __DISPATCH_BUILDING_DISPATCH__
  39 #include <dispatch/dispatch.h>
  40 #endif /* !__DISPATCH_BUILDING_DISPATCH__ */
  41
  42 #define OS_VOUCHER_SPI_VERSION 20150630
  43
  44 #if OS_VOUCHER_WEAK_IMPORT
  45 #define OS_VOUCHER_EXPORT OS_EXPORT OS_WEAK_IMPORT
  46 #else
  47 #define OS_VOUCHER_EXPORT OS_EXPORT
  48 #endif
  49
  50 DISPATCH_ASSUME_NONNULL_BEGIN
  51
  52 __BEGIN_DECLS
  53
  54 /*!
  55  * @group Voucher Transport SPI
  56  * SPI intended for clients that need to transport vouchers.
  57  */
  58
  59 /*!
  60  * @typedef voucher_t
  61  *
  62  * @abstract
  63  * Vouchers are immutable sets of key/value attributes that can be adopted on a
  64  * thread in the current process or sent to another process.
  65  *
  66  * @discussion
  67  * Voucher objects are os_objects (c.f. <os/object.h>). They are memory-managed
  68  * with the os_retain()/os_release() functions or -[retain]/-[release] methods.
  69  */
  70 OS_OBJECT_DECL_CLASS(voucher);
  71
  72 /*!
  73  * @const VOUCHER_NULL
  74  * Represents the empty base voucher with no attributes.
  75  */
  76 #define VOUCHER_NULL            ((voucher_t)0)
  77 /*!
  78  * @const VOUCHER_INVALID
  79  * Represents an invalid voucher
  80  */
  81 #define VOUCHER_INVALID         ((voucher_t)-1)
  82
  83 /*!
  84  * @function voucher_adopt
  85  *
  86  * @abstract
  87  * Adopt the specified voucher on the current thread and return the voucher
  88  * that had been adopted previously.
  89  *
  90  * @discussion
  91  * Adopted vouchers are automatically carried forward by the system to other
  92  * threads and processes (across IPC).
  93  *
  94  * Consumes a reference to the specified voucher.
  95  * Returns a reference to the previous voucher.
  96  *
  97  * @param voucher
  98  * The voucher object to adopt on the current thread.
  99  *
 100  * @result
 101  * The previously adopted voucher object.
 102  */
 103 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 104 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT_NEEDS_RELEASE
 105 OS_NOTHROW
 106 voucher_t _Nullable
 107 voucher_adopt(voucher_t _Nullable voucher OS_OBJECT_CONSUMED);
 108
 109 /*!
 110  * @function voucher_copy
 111  *
 112  * @abstract
 113  * Returns a reference to the voucher that had been adopted previously on the
 114  * current thread (or carried forward by the system).
 115  *
 116  * @result
 117  * The currently adopted voucher object.
 118  */
 119 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 120 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 121 voucher_t _Nullable
 122 voucher_copy(void);
 123
 124 /*!
 125  * @function voucher_copy_without_importance
 126  *
 127  * @abstract
 128  * Returns a reference to a voucher object with all the properties of the
 129  * voucher that had been adopted previously on the current thread, but
 130  * without the importance properties that are frequently attached to vouchers
 131  * carried with IPC requests. Importance properties may elevate the scheduling
 132  * of threads that adopt or retain the voucher while they service the request.
 133  * See xpc_transaction_begin(3) for further details on importance.
 134  *
 135  * @result
 136  * A copy of the currently adopted voucher object, with importance removed.
 137  */
 138 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 139 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 140 voucher_t _Nullable
 141 voucher_copy_without_importance(void);
 142
 143 /*!
 144  * @function voucher_replace_default_voucher
 145  *
 146  * @abstract
 147  * Replace process attributes of default voucher (used for IPC by this process
 148  * when no voucher is adopted on the sending thread) with the process attributes
 149  * of the voucher adopted on the current thread.
 150  *
 151  * @discussion
 152  * This allows a daemon to indicate from the context of an incoming IPC request
 153  * that all future outgoing IPC from the process should be marked as acting
 154  * "on behalf of" the sending process of the current IPC request (as long as the
 155  * thread sending that outgoing IPC is not itself in the direct context of an
 156  * IPC request, i.e. no voucher is adopted).
 157  *
 158  * If no voucher is adopted on the current thread or the current voucher does
 159  * not contain any process attributes, the default voucher is reset to the
 160  * default process attributes for the current process.
 161  *
 162  * CAUTION: Do NOT use this SPI without contacting the Darwin Runtime team.
 163  */
 164 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 165 OS_VOUCHER_EXPORT OS_NOTHROW
 166 void
 167 voucher_replace_default_voucher(void);
 168
 169 /*!
 170  * @function voucher_decrement_importance_count4CF
 171  *
 172  * @abstract
 173  * Decrement external importance count of the mach voucher in the specified
 174  * voucher object.
 175  *
 176  * @discussion
 177  * This is only intended for use by CoreFoundation to explicitly manage the
 178  * App Nap state of an application following reception of a de-nap IPC message.
 179  *
 180  * CAUTION: Do NOT use this SPI without contacting the Darwin Runtime team.
 181  */
 182 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 183 OS_VOUCHER_EXPORT OS_NOTHROW
 184 void
 185 voucher_decrement_importance_count4CF(voucher_t _Nullable voucher);
 186
 187 /*!
 188  * @group Voucher dispatch block SPI
 189  */
 190
 191 /*!
 192  * @typedef dispatch_block_flags_t
 193  * SPI Flags to pass to the dispatch_block_create* functions.
 194  *
 195  * @const DISPATCH_BLOCK_NO_VOUCHER
 196  * Flag indicating that a dispatch block object should not be assigned a voucher
 197  * object. If invoked directly, the block object will be executed with the
 198  * voucher adopted on the calling thread. If the block object is submitted to a
 199  * queue, this replaces the default behavior of associating the submitted block
 200  * instance with the voucher adopted at the time of submission.
 201  * This flag is ignored if a specific voucher object is assigned with the
 202  * dispatch_block_create_with_voucher* functions, and is equivalent to passing
 203  * the NULL voucher to these functions.
 204  */
 205 #define DISPATCH_BLOCK_NO_VOUCHER (0x40)
 206
 207 /*!
 208  * @function dispatch_block_create_with_voucher
 209  *
 210  * @abstract
 211  * Create a new dispatch block object on the heap from an existing block and
 212  * the given flags, and assign it the specified voucher object.
 213  *
 214  * @discussion
 215  * The provided block is Block_copy'ed to the heap, it and the specified voucher
 216  * object are retained by the newly created dispatch block object.
 217  *
 218  * The returned dispatch block object is intended to be submitted to a dispatch
 219  * queue with dispatch_async() and related functions, but may also be invoked
 220  * directly. Both operations can be performed an arbitrary number of times but
 221  * only the first completed execution of a dispatch block object can be waited
 222  * on with dispatch_block_wait() or observed with dispatch_block_notify().
 223  *
 224  * The returned dispatch block will be executed with the specified voucher
 225  * adopted for the duration of the block body. If the NULL voucher is passed,
 226  * the block will be executed with the voucher adopted on the calling thread, or
 227  * with no voucher if the DISPATCH_BLOCK_DETACHED flag was also provided.
 228  *
 229  * If the returned dispatch block object is submitted to a dispatch queue, the
 230  * submitted block instance will be associated with the QOS class current at the
 231  * time of submission, unless one of the following flags assigned a specific QOS
 232  * class (or no QOS class) at the time of block creation:
 233  *  - DISPATCH_BLOCK_ASSIGN_CURRENT
 234  *  - DISPATCH_BLOCK_NO_QOS_CLASS
 235  *  - DISPATCH_BLOCK_DETACHED
 236  * The QOS class the block object will be executed with also depends on the QOS
 237  * class assigned to the queue and which of the following flags was specified or
 238  * defaulted to:
 239  *  - DISPATCH_BLOCK_INHERIT_QOS_CLASS (default for asynchronous execution)
 240  *  - DISPATCH_BLOCK_ENFORCE_QOS_CLASS (default for synchronous execution)
 241  * See description of dispatch_block_flags_t for details.
 242  *
 243  * If the returned dispatch block object is submitted directly to a serial queue
 244  * and is configured to execute with a specific QOS class, the system will make
 245  * a best effort to apply the necessary QOS overrides to ensure that blocks
 246  * submitted earlier to the serial queue are executed at that same QOS class or
 247  * higher.
 248  *
 249  * @param flags
 250  * Configuration flags for the block object.
 251  * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t
 252  * results in NULL being returned.
 253  *
 254  * @param voucher
 255  * A voucher object or NULL. Passing NULL is equivalent to specifying the
 256  * DISPATCH_BLOCK_NO_VOUCHER flag.
 257  *
 258  * @param block
 259  * The block to create the dispatch block object from.
 260  *
 261  * @result
 262  * The newly created dispatch block object, or NULL.
 263  * When not building with Objective-C ARC, must be released with a -[release]
 264  * message or the Block_release() function.
 265  */
 266 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 267 DISPATCH_EXPORT DISPATCH_NONNULL3 DISPATCH_RETURNS_RETAINED_BLOCK
 268 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 269 dispatch_block_t
 270 dispatch_block_create_with_voucher(dispatch_block_flags_t flags,
 271                 voucher_t _Nullable voucher, dispatch_block_t block);
 272
 273 /*!
 274  * @function dispatch_block_create_with_voucher_and_qos_class
 275  *
 276  * @abstract
 277  * Create a new dispatch block object on the heap from an existing block and
 278  * the given flags, and assign it the specified voucher object, QOS class and
 279  * relative priority.
 280  *
 281  * @discussion
 282  * The provided block is Block_copy'ed to the heap, it and the specified voucher
 283  * object are retained by the newly created dispatch block object.
 284  *
 285  * The returned dispatch block object is intended to be submitted to a dispatch
 286  * queue with dispatch_async() and related functions, but may also be invoked
 287  * directly. Both operations can be performed an arbitrary number of times but
 288  * only the first completed execution of a dispatch block object can be waited
 289  * on with dispatch_block_wait() or observed with dispatch_block_notify().
 290  *
 291  * The returned dispatch block will be executed with the specified voucher
 292  * adopted for the duration of the block body. If the NULL voucher is passed,
 293  * the block will be executed with the voucher adopted on the calling thread, or
 294  * with no voucher if the DISPATCH_BLOCK_DETACHED flag was also provided.
 295  *
 296  * If invoked directly, the returned dispatch block object will be executed with
 297  * the assigned QOS class as long as that does not result in a lower QOS class
 298  * than what is current on the calling thread.
 299  *
 300  * If the returned dispatch block object is submitted to a dispatch queue, the
 301  * QOS class it will be executed with depends on the QOS class assigned to the
 302  * block, the QOS class assigned to the queue and which of the following flags
 303  * was specified or defaulted to:
 304  *  - DISPATCH_BLOCK_INHERIT_QOS_CLASS: default for asynchronous execution
 305  *  - DISPATCH_BLOCK_ENFORCE_QOS_CLASS: default for synchronous execution
 306  * See description of dispatch_block_flags_t for details.
 307  *
 308  * If the returned dispatch block object is submitted directly to a serial queue
 309  * and is configured to execute with a specific QOS class, the system will make
 310  * a best effort to apply the necessary QOS overrides to ensure that blocks
 311  * submitted earlier to the serial queue are executed at that same QOS class or
 312  * higher.
 313  *
 314  * @param flags
 315  * Configuration flags for the block object.
 316  * Passing a value that is not a bitwise OR of flags from dispatch_block_flags_t
 317  * results in NULL being returned.
 318  *
 319  * @param voucher
 320  * A voucher object or NULL. Passing NULL is equivalent to specifying the
 321  * DISPATCH_BLOCK_NO_VOUCHER flag.
 322  *
 323  * @param qos_class
 324  * A QOS class value:
 325  *  - QOS_CLASS_USER_INTERACTIVE
 326  *  - QOS_CLASS_USER_INITIATED
 327  *  - QOS_CLASS_DEFAULT
 328  *  - QOS_CLASS_UTILITY
 329  *  - QOS_CLASS_BACKGROUND
 330  *  - QOS_CLASS_UNSPECIFIED
 331  * Passing QOS_CLASS_UNSPECIFIED is equivalent to specifying the
 332  * DISPATCH_BLOCK_NO_QOS_CLASS flag. Passing any other value results in NULL
 333  * being returned.
 334  *
 335  * @param relative_priority
 336  * A relative priority within the QOS class. This value is a negative
 337  * offset from the maximum supported scheduler priority for the given class.
 338  * Passing a value greater than zero or less than QOS_MIN_RELATIVE_PRIORITY
 339  * results in NULL being returned.
 340  *
 341  * @param block
 342  * The block to create the dispatch block object from.
 343  *
 344  * @result
 345  * The newly created dispatch block object, or NULL.
 346  * When not building with Objective-C ARC, must be released with a -[release]
 347  * message or the Block_release() function.
 348  */
 349 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0)
 350 DISPATCH_EXPORT DISPATCH_NONNULL5 DISPATCH_RETURNS_RETAINED_BLOCK
 351 DISPATCH_WARN_RESULT DISPATCH_NOTHROW
 352 dispatch_block_t
 353 dispatch_block_create_with_voucher_and_qos_class(dispatch_block_flags_t flags,
 354                 voucher_t _Nullable voucher, dispatch_qos_class_t qos_class,
 355                 int relative_priority, dispatch_block_t block);
 356
 357 /*!
 358  * @group Voucher dispatch queue SPI
 359  */
 360
 361 /*!
 362  * @function dispatch_queue_create_with_accounting_override_voucher
 363  *
 364  * @abstract
 365  * Creates a new dispatch queue with an accounting override voucher created
 366  * from the specified voucher.
 367  *
 368  * @discussion
 369  * See dispatch_queue_create() headerdoc for generic details on queue creation.
 370  *
 371  * The resource accounting attributes of the specified voucher are extracted
 372  * and used to create an accounting override voucher for the new queue.
 373  *
 374  * Every block executed on the returned queue will initially have this override
 375  * voucher adopted, any voucher automatically associated with or explicitly
 376  * assigned to the block will NOT be used and released immediately before block
 377  * execution starts.
 378  *
 379  * The accounting override voucher will be automatically propagated to any
 380  * asynchronous work generated from the queue following standard voucher
 381  * propagation rules.
 382  *
 383  * NOTE: this SPI should only be used in special circumstances when a subsystem
 384  * has complete control over all workitems submitted to a queue (e.g. no client
 385  * block is ever submitted to the queue) and if and only if such queues have a
 386  * one-to-one mapping with resource accounting identities.
 387  *
 388  * CAUTION: use of this SPI represents a potential voucher propagation hole. It
 389  * is the responsibility of the caller to ensure that any callbacks into client
 390  * code from the queue have the correct client voucher applied (rather than the
 391  * automatically propagated accounting override voucher), e.g. by use of the
 392  * dispatch_block_create() API to capture client state at the time the callback
 393  * is registered.
 394  *
 395  * @param label
 396  * A string label to attach to the queue.
 397  * This parameter is optional and may be NULL.
 398  *
 399  * @param attr
 400  * DISPATCH_QUEUE_SERIAL, DISPATCH_QUEUE_CONCURRENT, or the result of a call to
 401  * the function dispatch_queue_attr_make_with_qos_class().
 402  *
 403  * @param voucher
 404  * A voucher whose resource accounting attributes are used to create the
 405  * accounting override voucher attached to the queue.
 406  *
 407  * @result
 408  * The newly created dispatch queue.
 409  */
 410 __OSX_AVAILABLE_STARTING(__MAC_10_11,__IPHONE_9_0)
 411 DISPATCH_EXPORT DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT
 412 DISPATCH_NOTHROW
 413 dispatch_queue_t
 414 dispatch_queue_create_with_accounting_override_voucher(
 415                 const char *_Nullable label,
 416                 dispatch_queue_attr_t _Nullable attr,
 417                 voucher_t _Nullable voucher);
 418
 419 #if __has_include(<mach/mach.h>)
 420 /*!
 421  * @group Voucher Mach SPI
 422  * SPI intended for clients that need to interact with mach messages or mach
 423  * voucher ports directly.
 424  */
 425
 426 /*!
 427  * @function voucher_create_with_mach_msg
 428  *
 429  * @abstract
 430  * Creates a new voucher object from a mach message carrying a mach voucher port
 431  *
 432  * @discussion
 433  * Ownership of the mach voucher port in the message is transfered to the new
 434  * voucher object and the message header mach voucher field is cleared.
 435  *
 436  * @param msg
 437  * The mach message to query.
 438  *
 439  * @result
 440  * The newly created voucher object or NULL if the message was not carrying a
 441  * mach voucher.
 442  */
 443 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 444 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 445 voucher_t _Nullable
 446 voucher_create_with_mach_msg(mach_msg_header_t *msg);
 447
 448 /*!
 449  * @group Voucher Persona SPI
 450  * SPI intended for clients that need to interact with personas.
 451  */
 452
 453 struct proc_persona_info;
 454
 455 /*!
 456  * @function voucher_get_current_persona
 457  *
 458  * @abstract
 459  * Retrieve the persona identifier of the 'originator' process for the current
 460  * voucher.
 461  *
 462  * @discussion
 463  * Retrieve the persona identifier of the ’originator’ process possibly stored
 464  * in the PERSONA_TOKEN attribute of the currently adopted voucher.
 465  *
 466  * If the thread has not adopted a voucher, or the current voucher does not
 467  * contain a PERSONA_TOKEN attribute, this function returns the persona
 468  * identifier of the current process.
 469  *
 470  * If the process is not running under a persona, then this returns
 471  * PERSONA_ID_NONE.
 472  *
 473  * @result
 474  * The persona identifier of the 'originator' process for the current voucher,
 475  * or the persona identifier of the current process
 476  * or PERSONA_ID_NONE
 477  */
 478 __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_9_2)
 479 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW
 480 uid_t
 481 voucher_get_current_persona(void);
 482
 483 /*!
 484  * @function voucher_get_current_persona_originator_info
 485  *
 486  * @abstract
 487  * Retrieve the ’originator’ process persona info for the currently adopted
 488  * voucher.
 489  *
 490  * @discussion
 491  * If there is no currently adopted voucher, or no PERSONA_TOKEN attribute
 492  * in that voucher, this function fails.
 493  *
 494  * @param persona_info
 495  * The proc_persona_info structure to fill in case of success
 496  *
 497  * @result
 498  * 0 on success: currently adopted voucher has a PERSONA_TOKEN
 499  * -1 on failure: persona_info is untouched/uninitialized
 500  */
 501 __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_9_2)
 502 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL1
 503 int
 504 voucher_get_current_persona_originator_info(
 505         struct proc_persona_info *persona_info);
 506
 507 /*!
 508  * @function voucher_get_current_persona_proximate_info
 509  *
 510  * @abstract
 511  * Retrieve the ’proximate’ process persona info for the currently adopted
 512  * voucher.
 513  *
 514  * @discussion
 515  * If there is no currently adopted voucher, or no PERSONA_TOKEN attribute
 516  * in that voucher, this function fails.
 517  *
 518  * @param persona_info
 519  * The proc_persona_info structure to fill in case of success
 520  *
 521  * @result
 522  * 0 on success: currently adopted voucher has a PERSONA_TOKEN
 523  * -1 on failure: persona_info is untouched/uninitialized
 524  */
 525 __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_9_2)
 526 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL1
 527 int
 528 voucher_get_current_persona_proximate_info(
 529         struct proc_persona_info *persona_info);
 530
 531 #endif // __has_include(<mach/mach.h>)
 532
 533 __END_DECLS
 534
 535 DISPATCH_ASSUME_NONNULL_END
 536
 537 #endif // __OS_VOUCHER_PRIVATE__
 538
 539 #if OS_VOUCHER_ACTIVITY_SPI
 540 #include "voucher_activity_private.h"
 541 #endif