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