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