os/voucher_activity_private.h

   1 /*
   2  * Copyright (c) 2013-2015 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_ACTIVITY_PRIVATE__
  22 #define __OS_VOUCHER_ACTIVITY_PRIVATE__
  23
  24 #if OS_VOUCHER_ACTIVITY_SPI
  25 #if __has_include(<mach/mach_time.h>)
  26 #include <mach/mach_time.h>
  27 #include <firehose/tracepoint_private.h>
  28 #endif
  29 #ifndef __linux__
  30 #include <os/base.h>
  31 #endif
  32 #include <os/object.h>
  33 #include "voucher_private.h"
  34
  35 #define OS_VOUCHER_ACTIVITY_SPI_VERSION 20160329
  36
  37 #if OS_VOUCHER_WEAK_IMPORT
  38 #define OS_VOUCHER_EXPORT OS_EXPORT OS_WEAK_IMPORT
  39 #else
  40 #define OS_VOUCHER_EXPORT OS_EXPORT
  41 #endif
  42
  43 #define __VOUCHER_ACTIVITY_IGNORE_DEPRECATION_PUSH \
  44         _Pragma("clang diagnostic push") \
  45         _Pragma("clang diagnostic ignored \"-Wdeprecated-declarations\"")
  46 #define __VOUCHER_ACTIVITY_IGNORE_DEPRECATION_POP \
  47         _Pragma("clang diagnostic pop")
  48
  49 __BEGIN_DECLS
  50
  51 /*!
  52  * @const VOUCHER_CURRENT
  53  * Shorthand for the currently adopted voucher
  54  *
  55  * This value can only be used as an argument to functions, and is never
  56  * actually returned. It looks enough like a tagged pointer object that ARC
  57  * won't crash if this is assigned to a temporary variable.
  58  */
  59 #define VOUCHER_CURRENT         ((OS_OBJECT_BRIDGE voucher_t)(void *)~2ul)
  60
  61 /*!
  62  * @function voucher_get_activity_id
  63  *
  64  * @abstract
  65  * Returns the activity_id associated with the specified voucher at the time
  66  * of the call.
  67  *
  68  * @discussion
  69  * When the passed voucher is VOUCHER_CURRENT this returns the current
  70  * activity ID.
  71  *
  72  * @param voucher
  73  * The specified voucher.
  74  *
  75  * @param parent_id
  76  * An out parameter to return the parent ID of the returned activity ID.
  77  *
  78  * @result
  79  * The current activity identifier, if any. When 0 is returned, parent_id will
  80  * also always be 0.
  81  */
  82 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
  83 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
  84 OS_VOUCHER_EXPORT OS_NOTHROW
  85 firehose_activity_id_t
  86 voucher_get_activity_id(voucher_t voucher, firehose_activity_id_t *parent_id);
  87
  88 /*!
  89  * @function voucher_get_activity_id_and_creator
  90  *
  91  * @abstract
  92  * Returns the activity_id associated with the specified voucher at the time
  93  * of the call.
  94  *
  95  * @discussion
  96  * When the passed voucher is VOUCHER_CURRENT this returns the current
  97  * activity ID.
  98  *
  99  * @param voucher
 100  * The specified voucher.
 101  *
 102  * @param creator_pid
 103  * The unique pid of the process that created the returned activity ID if any.
 104  *
 105  * @param parent_id
 106  * An out parameter to return the parent ID of the returned activity ID.
 107  *
 108  * @result
 109  * The current activity identifier, if any. When 0 is returned, parent_id will
 110  * also always be 0.
 111  */
 112 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 113 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 114 OS_VOUCHER_EXPORT OS_NOTHROW
 115 firehose_activity_id_t
 116 voucher_get_activity_id_and_creator(voucher_t voucher, uint64_t *creator_pid,
 117                 firehose_activity_id_t *parent_id);
 118
 119 /*!
 120  * @function voucher_activity_create
 121  *
 122  * @abstract
 123  * Creates a voucher object with a new activity identifier.
 124  *
 125  * @discussion
 126  * As part of voucher transport, activities are automatically propagated by the
 127  * system to other threads and processes (across IPC).
 128  *
 129  * When a voucher with an activity identifier is applied to a thread, work
 130  * on that thread is done on behalf of this activity.
 131  *
 132  * @param trace_id
 133  * Tracepoint identifier returned by voucher_activity_trace_id(), intended for
 134  * identification of the automatic tracepoint generated as part of creating the
 135  * new activity.
 136  *
 137  * @param base
 138  * The base voucher used to create the activity. If the base voucher has an
 139  * activity identifier, then the created activity will be parented to that one.
 140  * If the passed in base has no activity identifier, the activity identifier
 141  * will be a top-level one, on behalf of the process that created the base
 142  * voucher.
 143  *
 144  * If base is VOUCHER_NONE, the activity is a top-level one, on behalf of the
 145  * current process.
 146  *
 147  * If base is VOUCHER_CURRENT, then the activity is naturally based on the
 148  * one currently applied to the current thread (the one voucher_copy() would
 149  * return).
 150  *
 151  * @param flags
 152  * See voucher_activity_flag_t documentation for effect.
 153  *
 154  * @param location
 155  * Location identifier for the automatic tracepoint generated as part of
 156  * creating the new activity.
 157  *
 158  * @result
 159  * A new voucher with an activity identifier.
 160  */
 161 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 162 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 163 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 164 voucher_t
 165 voucher_activity_create(firehose_tracepoint_id_t trace_id,
 166                 voucher_t base, firehose_activity_flags_t flags, uint64_t location);
 167
 168 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 169 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 170 OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
 171 voucher_t
 172 voucher_activity_create_with_location(firehose_tracepoint_id_t *trace_id,
 173                 voucher_t base, firehose_activity_flags_t flags, uint64_t location);
 174
 175 /*!
 176  * @group Voucher Activity Trace SPI
 177  * SPI intended for libtrace only
 178  */
 179
 180 /*!
 181  * @function voucher_activity_flush
 182  *
 183  * @abstract
 184  * Force flushing the specified stream.
 185  *
 186  * @discussion
 187  * This maks all the buffers currently being written to as full, so that
 188  * their current content is pushed in a timely fashion.
 189  *
 190  * When this call returns, the actual flush may or may not yet have happened.
 191  *
 192  * @param stream
 193  * The stream to flush.
 194  */
 195 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 196 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 197 OS_VOUCHER_EXPORT OS_NOTHROW
 198 void
 199 voucher_activity_flush(firehose_stream_t stream);
 200
 201 /*!
 202  * @function voucher_activity_trace
 203  *
 204  * @abstract
 205  * Add a tracepoint to the specified stream.
 206  *
 207  * @param stream
 208  * The stream to trace this entry into.
 209  *
 210  * @param trace_id
 211  * Tracepoint identifier returned by voucher_activity_trace_id()
 212  *
 213  * @param timestamp
 214  * The mach_approximate_time()/mach_absolute_time() value for this tracepoint.
 215  *
 216  * @param pubdata
 217  * Pointer to packed buffer of tracepoint data.
 218  *
 219  * @param publen
 220  * Length of data at 'pubdata'.
 221  */
 222 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 223 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 224 OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL4
 225 firehose_tracepoint_id_t
 226 voucher_activity_trace(firehose_stream_t stream,
 227                 firehose_tracepoint_id_t trace_id, uint64_t timestamp,
 228                 const void *pubdata, size_t publen);
 229
 230 /*!
 231  * @function voucher_activity_trace_with_private_strings
 232  *
 233  * @abstract
 234  * Add a tracepoint to the specified stream, with private data.
 235  *
 236  * @param stream
 237  * The stream to trace this entry into.
 238  *
 239  * @param trace_id
 240  * Tracepoint identifier returned by voucher_activity_trace_id()
 241  *
 242  * @param timestamp
 243  * The mach_approximate_time()/mach_absolute_time() value for this tracepoint.
 244  *
 245  * @param pubdata
 246  * Pointer to packed buffer of tracepoint data.
 247  *
 248  * @param publen
 249  * Length of data at 'pubdata'.
 250  *
 251  * @param privdata
 252  * Pointer to packed buffer of private tracepoint data.
 253  *
 254  * @param privlen
 255  * Length of data at 'privdata'.
 256  */
 257 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 258 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 259 OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL4 OS_NONNULL6
 260 firehose_tracepoint_id_t
 261 voucher_activity_trace_with_private_strings(firehose_stream_t stream,
 262                 firehose_tracepoint_id_t trace_id, uint64_t timestamp,
 263                 const void *pubdata, size_t publen,
 264                 const void *privdata, size_t privlen);
 265
 266 typedef struct voucher_activity_hooks_s {
 267 #define VOUCHER_ACTIVITY_HOOKS_VERSION     3
 268         long vah_version;
 269         // version 1
 270         mach_port_t (*vah_get_logd_port)(void);
 271         // version 2
 272         dispatch_mach_handler_function_t vah_debug_channel_handler;
 273         // version 3
 274         kern_return_t (*vah_get_reconnect_info)(mach_vm_address_t *, mach_vm_size_t *);
 275 } *voucher_activity_hooks_t;
 276
 277 /*!
 278  * @function voucher_activity_initialize_4libtrace
 279  *
 280  * @abstract
 281  * Configure upcall hooks for libtrace.
 282  *
 283  * @param hooks
 284  * A pointer to a voucher_activity_hooks_s structure.
 285  */
 286 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 287 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 288 OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL_ALL
 289 void
 290 voucher_activity_initialize_4libtrace(voucher_activity_hooks_t hooks);
 291
 292 /*!
 293  * @function voucher_activity_get_metadata_buffer
 294  *
 295  * @abstract
 296  * Return address and length of buffer in the process trace memory area
 297  * reserved for libtrace metadata.
 298  *
 299  * @param length
 300  * Pointer to size_t variable, filled with length of metadata buffer.
 301  *
 302  * @result
 303  * Address of metadata buffer.
 304  */
 305 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 306 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL_ALL
 307 void*
 308 voucher_activity_get_metadata_buffer(size_t *length);
 309
 310 /*!
 311  * @function voucher_get_activity_id_4dyld
 312  *
 313  * @abstract
 314  * Return the current voucher activity ID. Available for the dyld client stub
 315  * only.
 316  */
 317 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
 318 __TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
 319 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW
 320 firehose_activity_id_t
 321 voucher_get_activity_id_4dyld(void);
 322
 323 __END_DECLS
 324
 325 #endif // OS_VOUCHER_ACTIVITY_SPI
 326
 327 #endif // __OS_VOUCHER_ACTIVITY_PRIVATE__