private/voucher_activity_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_ACTIVITY_PRIVATE__
  22 #define __OS_VOUCHER_ACTIVITY_PRIVATE__
  23
  24 #include <os/base.h>
  25 #include <os/object.h>
  26 #if !defined(__DISPATCH_BUILDING_DISPATCH__)
  27 #include <os/voucher_private.h>
  28 #endif
  29
  30 #define OS_VOUCHER_ACTIVITY_SPI_VERSION 20140708
  31
  32 #if OS_VOUCHER_WEAK_IMPORT
  33 #define OS_VOUCHER_EXPORT OS_EXPORT OS_WEAK_IMPORT
  34 #else
  35 #define OS_VOUCHER_EXPORT OS_EXPORT
  36 #endif
  37
  38 __BEGIN_DECLS
  39
  40 #if OS_VOUCHER_ACTIVITY_SPI
  41
  42 /*!
  43  * @group Voucher Activity SPI
  44  * SPI intended for libtrace only
  45  */
  46
  47 /*!
  48  * @typedef voucher_activity_id_t
  49  *
  50  * @abstract
  51  * Opaque activity identifier.
  52  *
  53  * @discussion
  54  * Scalar value type, not reference counted.
  55  */
  56 typedef uint64_t voucher_activity_id_t;
  57
  58 /*!
  59  * @enum voucher_activity_tracepoint_type_t
  60  *
  61  * @abstract
  62  * Types of tracepoints.
  63  */
  64 OS_ENUM(voucher_activity_tracepoint_type, uint8_t,
  65         voucher_activity_tracepoint_type_release = (1u << 0),
  66         voucher_activity_tracepoint_type_debug = (1u << 1),
  67         voucher_activity_tracepoint_type_error = (1u << 6) | (1u << 0),
  68         voucher_activity_tracepoint_type_fault = (1u << 7) | (1u << 6) | (1u << 0),
  69 );
  70
  71 /*!
  72  * @enum voucher_activity_flag_t
  73  *
  74  * @abstract
  75  * Flags to pass to voucher_activity_start/voucher_activity_start_with_location
  76  */
  77 OS_ENUM(voucher_activity_flag, unsigned long,
  78         voucher_activity_flag_default = 0,
  79         voucher_activity_flag_force = 0x1,
  80 );
  81
  82 /*!
  83  * @typedef voucher_activity_trace_id_t
  84  *
  85  * @abstract
  86  * Opaque tracepoint identifier.
  87  */
  88 typedef uint64_t voucher_activity_trace_id_t;
  89 static const uint8_t _voucher_activity_trace_id_type_shift = 40;
  90 static const uint8_t _voucher_activity_trace_id_code_namespace_shift = 32;
  91
  92 /*!
  93  * @function voucher_activity_trace_id
  94  *
  95  * @abstract
  96  * Return tracepoint identifier for specified arguments.
  97  *
  98  * @param type
  99  * Tracepoint type from voucher_activity_tracepoint_type_t.
 100  *
 101  * @param code_namespace
 102  * Namespace of 'code' argument.
 103  *
 104  * @param code
 105  * Tracepoint code.
 106  *
 107  * @result
 108  * Tracepoint identifier.
 109  */
 110 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 111 OS_INLINE OS_ALWAYS_INLINE
 112 voucher_activity_trace_id_t
 113 voucher_activity_trace_id(uint8_t type, uint8_t code_namespace, uint32_t code)
 114 {
 115         return ((voucher_activity_trace_id_t)type <<
 116                         _voucher_activity_trace_id_type_shift) |
 117                         ((voucher_activity_trace_id_t)code_namespace <<
 118                         _voucher_activity_trace_id_code_namespace_shift) |
 119                         (voucher_activity_trace_id_t)code;
 120 }
 121
 122 /*!
 123  * @function voucher_activity_start
 124  *
 125  * @abstract
 126  * Creates a new activity identifier and marks the current thread as
 127  * participating in the activity.
 128  *
 129  * @discussion
 130  * As part of voucher transport, activities are automatically propagated by the
 131  * system to other threads and processes (across IPC).
 132  *
 133  * Activities persist as long as any threads in any process are marked as
 134  * participating. There may be many calls to voucher_activity_end()
 135  * corresponding to one call to voucher_activity_start().
 136  *
 137  * @param trace_id
 138  * Tracepoint identifier returned by voucher_activity_trace_id(), intended for
 139  * identification of the automatic tracepoint generated as part of creating the
 140  * new activity.
 141  *
 142  * @param flags
 143  * Pass voucher_activity_flag_force to indicate that existing activities
 144  * on the current thread should not be inherited and that a new toplevel
 145  * activity should be created.
 146  *
 147  * @result
 148  * A new activity identifier.
 149  */
 150 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 151 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW
 152 voucher_activity_id_t
 153 voucher_activity_start(voucher_activity_trace_id_t trace_id,
 154                 voucher_activity_flag_t flags);
 155
 156 /*!
 157  * @function voucher_activity_start_with_location
 158  *
 159  * @abstract
 160  * Creates a new activity identifier and marks the current thread as
 161  * participating in the activity.
 162  *
 163  * @discussion
 164  * As part of voucher transport, activities are automatically propagated by the
 165  * system to other threads and processes (across IPC).
 166  *
 167  * Activities persist as long as any threads in any process are marked as
 168  * participating. There may be many calls to voucher_activity_end()
 169  * corresponding to one call to voucher_activity_start_with_location().
 170  *
 171  * @param trace_id
 172  * Tracepoint identifier returned by voucher_activity_trace_id(), intended for
 173  * identification of the automatic tracepoint generated as part of creating the
 174  * new activity.
 175  *
 176  * @param location
 177  * Location identifier for the automatic tracepoint generated as part of
 178  * creating the new activity.
 179  *
 180  * @param flags
 181  * Pass voucher_activity_flag_force to indicate that existing activities
 182  * on the current thread should not be inherited and that a new toplevel
 183  * activity should be created.
 184  *
 185  * @result
 186  * A new activity identifier.
 187  */
 188 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 189 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW
 190 voucher_activity_id_t
 191 voucher_activity_start_with_location(voucher_activity_trace_id_t trace_id,
 192                 uint64_t location, voucher_activity_flag_t flags);
 193
 194 /*!
 195  * @function voucher_activity_end
 196  *
 197  * @abstract
 198  * Unmarks the current thread if it is marked as particpating in the activity
 199  * with the specified identifier.
 200  *
 201  * @discussion
 202  * Activities persist as long as any threads in any process are marked as
 203  * participating. There may be many calls to voucher_activity_end()
 204  * corresponding to one call to voucher_activity_start() or
 205  * voucher_activity_start_with_location().
 206  */
 207 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 208 OS_VOUCHER_EXPORT OS_NOTHROW
 209 void
 210 voucher_activity_end(voucher_activity_id_t activity_id);
 211
 212 /*!
 213  * @function voucher_get_activities
 214  *
 215  * @abstract
 216  * Returns the list of activity identifiers that the current thread is marked
 217  * with.
 218  *
 219  * @param entries
 220  * Pointer to an array of activity identifiers to be filled in.
 221  *
 222  * @param count
 223  * Pointer to the requested number of activity identifiers.
 224  * On output will be filled with the number of activities that are available.
 225  *
 226  * @result
 227  * Number of activity identifiers written to 'entries'
 228  */
 229 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 230 OS_VOUCHER_EXPORT OS_NOTHROW
 231 unsigned int
 232 voucher_get_activities(voucher_activity_id_t *entries, unsigned int *count);
 233
 234 /*!
 235  * @group Voucher Activity Trace SPI
 236  * SPI intended for libtrace only
 237  */
 238
 239 /*!
 240  * @function voucher_activity_get_namespace
 241  *
 242  * @abstract
 243  * Returns the namespace of the current activity.
 244  *
 245  * @result
 246  * The namespace of the current activity (if any).
 247  */
 248 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 249 OS_VOUCHER_EXPORT OS_NOTHROW
 250 uint8_t
 251 voucher_activity_get_namespace(void);
 252
 253 /*!
 254  * @function voucher_activity_trace
 255  *
 256  * @abstract
 257  * Add a tracepoint to trace buffer of the current activity.
 258  *
 259  * @param trace_id
 260  * Tracepoint identifier returned by voucher_activity_trace_id()
 261  *
 262  * @param location
 263  * Tracepoint location.
 264  *
 265  * @param buffer
 266  * Pointer to packed buffer of tracepoint data.
 267  *
 268  * @param length
 269  * Length of data at 'buffer'.
 270  *
 271  * @result
 272  * Timestamp recorded in tracepoint or 0 if no tracepoint was recorded.
 273  */
 274 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 275 OS_VOUCHER_EXPORT OS_NOTHROW
 276 uint64_t
 277 voucher_activity_trace(voucher_activity_trace_id_t trace_id, uint64_t location,
 278                 void *buffer, size_t length);
 279
 280 /*!
 281  * @function voucher_activity_trace_args
 282  *
 283  * @abstract
 284  * Add a tracepoint to trace buffer of the current activity, recording
 285  * specified arguments passed in registers.
 286  *
 287  * @param trace_id
 288  * Tracepoint identifier returned by voucher_activity_trace_id()
 289  *
 290  * @param location
 291  * Tracepoint location.
 292  *
 293  * @param arg1
 294  * Argument to be recorded in tracepoint data.
 295  *
 296  * @param arg2
 297  * Argument to be recorded in tracepoint data.
 298  *
 299  * @param arg3
 300  * Argument to be recorded in tracepoint data.
 301  *
 302  * @param arg4
 303  * Argument to be recorded in tracepoint data.
 304  *
 305  * @result
 306  * Timestamp recorded in tracepoint or 0 if no tracepoint was recorded.
 307  */
 308 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 309 OS_VOUCHER_EXPORT OS_NOTHROW
 310 uint64_t
 311 voucher_activity_trace_args(voucher_activity_trace_id_t trace_id,
 312                 uint64_t location, uintptr_t arg1, uintptr_t arg2, uintptr_t arg3,
 313                 uintptr_t arg4);
 314
 315 /*!
 316  * @group Voucher Activity Mode SPI
 317  * SPI intended for libtrace only
 318  */
 319
 320 /*!
 321  * @enum voucher_activity_mode_t
 322  *
 323  * @abstract
 324  * Voucher activity mode.
 325  *
 326  * @discussion
 327  * Configure at process start by setting the OS_ACTIVITY_MODE environment
 328  * variable.
 329  */
 330 OS_ENUM(voucher_activity_mode, unsigned long,
 331         voucher_activity_mode_disable = 0,
 332         voucher_activity_mode_release = (1u << 0),
 333         voucher_activity_mode_debug = (1u << 1),
 334         voucher_activity_mode_stream = (1u << 2),
 335 );
 336
 337 /*!
 338  * @function voucher_activity_get_mode
 339  *
 340  * @abstract
 341  * Return current mode of voucher activity subsystem.
 342  *
 343  * @result
 344  * Value from voucher_activity_mode_t enum.
 345  */
 346 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 347 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW
 348 voucher_activity_mode_t
 349 voucher_activity_get_mode(void);
 350
 351 /*!
 352  * @function voucher_activity_set_mode_4libtrace(void)
 353  *
 354  * @abstract
 355  * Set the current mode of voucher activity subsystem.
 356  *
 357  * @param mode
 358  * The new mode.
 359  *
 360  * Note that the new mode will take effect soon, but not immediately.
 361  */
 362 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 363 OS_VOUCHER_EXPORT OS_NOTHROW
 364 void
 365 voucher_activity_set_mode_4libtrace(voucher_activity_mode_t mode);
 366
 367 /*!
 368  * @group Voucher Activity Metadata SPI
 369  * SPI intended for libtrace only
 370  */
 371
 372 /*!
 373  * @function voucher_activity_get_metadata_buffer
 374  *
 375  * @abstract
 376  * Return address and length of buffer in the process trace memory area
 377  * reserved for libtrace metadata.
 378  *
 379  * @param length
 380  * Pointer to size_t variable, filled with length of metadata buffer.
 381  *
 382  * @result
 383  * Address of metadata buffer.
 384  */
 385 __OSX_AVAILABLE_STARTING(__MAC_10_10,__IPHONE_8_0)
 386 OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL_ALL
 387 void*
 388 voucher_activity_get_metadata_buffer(size_t *length);
 389
 390 #endif // OS_VOUCHER_ACTIVITY_SPI
 391
 392 #if OS_VOUCHER_ACTIVITY_BUFFER_SPI
 393
 394 /*!
 395  * @group Voucher Activity Tracepoint SPI
 396  * SPI intended for diagnosticd only
 397  */
 398
 399 OS_ENUM(_voucher_activity_tracepoint_flag, uint16_t,
 400         _voucher_activity_trace_flag_buffer_empty = 0,
 401         _voucher_activity_trace_flag_tracepoint = (1u << 0),
 402         _voucher_activity_trace_flag_tracepoint_args = (1u << 1),
 403         _voucher_activity_trace_flag_wide_first = (1u << 6),
 404         _voucher_activity_trace_flag_wide_second = (1u << 6) | (1u << 7),
 405         _voucher_activity_trace_flag_start = (1u << 8),
 406         _voucher_activity_trace_flag_end = (1u << 8) | (1u << 9),
 407         _voucher_activity_trace_flag_libdispatch = (1u << 13),
 408         _voucher_activity_trace_flag_activity = (1u << 14),
 409         _voucher_activity_trace_flag_buffer_header = (1u << 15),
 410 );
 411
 412 // for tracepoints with _voucher_activity_trace_flag_libdispatch
 413 OS_ENUM(_voucher_activity_tracepoint_namespace, uint8_t,
 414         _voucher_activity_tracepoint_namespace_ipc = 0x1
 415 );
 416 OS_ENUM(_voucher_activity_tracepoint_code, uint32_t,
 417         _voucher_activity_tracepoint_namespace_ipc_send = 0x1,
 418         _voucher_activity_tracepoint_namespace_ipc_receive = 0x2,
 419 );
 420
 421 typedef struct _voucher_activity_tracepoint_s {
 422         uint16_t vat_flags;             // voucher_activity_tracepoint_flag_t
 423         uint8_t  vat_type;              // voucher_activity_tracepoint_type_t
 424         uint8_t  vat_namespace; // namespace for tracepoint code
 425         uint32_t vat_code;              // tracepoint code
 426         uint64_t vat_thread;    // pthread_t
 427         uint64_t vat_timestamp; // absolute time
 428         uint64_t vat_location;  // tracepoint PC
 429         uint64_t vat_data[4];   // trace data
 430 } *_voucher_activity_tracepoint_t;
 431
 432 /*!
 433  * @group Voucher Activity Buffer Internals
 434  * SPI intended for diagnosticd only
 435  * Layout of structs is subject to change without notice
 436  */
 437
 438 #include <sys/queue.h>
 439 #include <atm/atm_types.h>
 440 #include <os/lock_private.h>
 441
 442 static const atm_subaid32_t _voucher_default_activity_subid =
 443                 ATM_SUBAID32_MAX-1;
 444
 445 static const size_t _voucher_activity_buffer_size = 4096;
 446 static const size_t _voucher_activity_tracepoints_per_buffer =
 447                 _voucher_activity_buffer_size /
 448                 sizeof(struct _voucher_activity_tracepoint_s);
 449 typedef uint8_t _voucher_activity_buffer_t[_voucher_activity_buffer_size];
 450
 451 struct _voucher_activity_self_metadata_s {
 452         struct _voucher_activity_metadata_opaque_s *vasm_baseaddr;
 453 };
 454 typedef struct _voucher_activity_metadata_opaque_s {
 455         _voucher_activity_buffer_t vam_kernel_metadata;
 456         _voucher_activity_buffer_t vam_client_metadata;
 457         union {
 458                 struct _voucher_activity_self_metadata_s vam_self_metadata;
 459                 _voucher_activity_buffer_t vam_self_metadata_opaque;
 460         };
 461 } *_voucher_activity_metadata_opaque_t;
 462
 463 typedef os_lock_handoff_s _voucher_activity_lock_s;
 464
 465 typedef struct _voucher_atm_s {
 466         int32_t volatile vatm_refcnt;
 467         mach_voucher_t vatm_kvoucher;
 468         atm_aid_t vatm_id;
 469         atm_mailbox_offset_t vatm_mailbox_offset;
 470         TAILQ_ENTRY(_voucher_atm_s) vatm_list;
 471 #if __LP64__
 472         uintptr_t vatm_pad[3];
 473         // cacheline
 474 #endif
 475         _voucher_activity_lock_s vatm_activities_lock;
 476         TAILQ_HEAD(_voucher_atm_activities_s, _voucher_activity_s) vatm_activities;
 477         TAILQ_HEAD(, _voucher_activity_s) vatm_used_activities;
 478 } *_voucher_atm_t;
 479
 480 // must match layout of _voucher_activity_tracepoint_s
 481 typedef struct _voucher_activity_buffer_header_s {
 482         uint16_t vabh_flags;    // _voucher_activity_trace_flag_buffer_header
 483         uint8_t  vabh_unused[6];
 484         uint64_t vabh_thread;
 485         uint64_t vabh_timestamp;
 486         uint32_t volatile vabh_next_tracepoint_idx;
 487         uint32_t vabh_sequence_no;
 488         voucher_activity_id_t vabh_activity_id;
 489         uint64_t vabh_reserved;
 490         TAILQ_ENTRY(_voucher_activity_buffer_header_s) vabh_list;
 491 } *_voucher_activity_buffer_header_t;
 492
 493 // must match layout of _voucher_activity_buffer_header_s
 494 typedef struct _voucher_activity_s {
 495         // first tracepoint entry
 496         // must match layout of _voucher_activity_tracepoint_s
 497         uint16_t va_flags;              // _voucher_activity_trace_flag_buffer_header |
 498                                                         // _voucher_activity_trace_flag_activity |
 499                                                         // _voucher_activity_trace_flag_start |
 500                                                         // _voucher_activity_trace_flag_wide_first
 501         uint8_t  va_type;
 502         uint8_t  va_namespace;
 503         uint32_t va_code;
 504         uint64_t va_thread;
 505         uint64_t va_timestamp;
 506         uint32_t volatile vabh_next_tracepoint_idx;
 507         uint32_t volatile va_max_sequence_no;
 508         voucher_activity_id_t va_id;
 509         int32_t volatile va_use_count;
 510         uint32_t va_buffer_limit;
 511         TAILQ_HEAD(_voucher_activity_buffer_list_s,
 512                         _voucher_activity_buffer_header_s) va_buffers;
 513 #if !__LP64__
 514         uint64_t va_pad;
 515 #endif
 516
 517         // second tracepoint entry
 518         // must match layout of _voucher_activity_tracepoint_s
 519         uint16_t va_flags2;
 520         uint8_t va_unused2[2];
 521         int32_t volatile va_refcnt;
 522         uint64_t va_location;
 523         _voucher_activity_buffer_header_t volatile va_current_buffer;
 524         _voucher_atm_t va_atm;
 525         _voucher_activity_lock_s va_buffers_lock;
 526         uintptr_t va_pad2[2];
 527
 528 #if __LP64__
 529         // third tracepoint entry
 530         // must match layout of _voucher_activity_tracepoint_s
 531         uint16_t va_flags3;
 532         uint8_t va_unused3[6];
 533         uintptr_t va_pad3;
 534 #endif
 535         TAILQ_ENTRY(_voucher_activity_s) va_list;
 536         TAILQ_ENTRY(_voucher_activity_s) va_atm_list;
 537         TAILQ_ENTRY(_voucher_activity_s) va_atm_used_list;
 538 } *_voucher_activity_t;
 539
 540 #endif // OS_VOUCHER_ACTIVITY_BUFFER_SPI
 541
 542 __END_DECLS
 543
 544 #endif // __OS_VOUCHER_ACTIVITY_PRIVATE__