osfmk/man/etap_trace_event.html

   1 <h2>etap_trace_event</h2>
   2 <hr>
   3 <p>
   4 <strong>System Trap</strong> -
   5 manipulate event probes and lock event tracing.
   6 <h3>SYNOPSIS</h3>
   7 <pre>
   8 <strong>#include&ltmach/etap.h&gt</strong>
   9
  10 <strong>kern_return_t   etap_trace_event</strong>
  11                 <strong>(etap_data_t</strong>                               <var>mode</var>,
  12                  <strong>mode</strong>                                      <var>type</var>,
  13                  <strong>boolean_t</strong>                               <var>enable</var>,
  14                  <strong>enable</strong>                                   <var>nargs</var>,
  15                  <strong>mode</strong>                                      <var>mode</var><strong>);</strong>
  16 </pre>
  17 <h3>PARAMETERS</h3>
  18 <dl>
  19 <p>
  20 <dt> <var>mode</var>
  21 <dd>
  22 indicates the desired trace flavor or reset option and may be one,
  23 or more, of the following:
  24 <ul>
  25 <p>
  26   <li>
  27 ETAP_CUMULATIVE: cumulative lock event trace mode.
  28      <p>
  29 <li>
  30 ETAP_MONITORED: monitored event trace mode (for probes or locks)
  31 <p>
  32 <li>
  33 ETAP_RESET: reset mode, clears all trace status and cumulative buffer entries
  34 </ul>
  35 <p>
  36 <dt> <var>type</var>
  37 <dd>
  38 used when measuring lock event contention or durations
  39 and may be one, or more, of the following:
  40 <ul>
  41 <p>
  42   <li>
  43 ETAP_CONTENT
  44 <p>
  45   <li>
  46 ETAP_DURATION
  47 </ul>
  48 <p>
  49 <dt> <var>enable</var>
  50 <dd>
  51 a boolean value  indicattin whether the event trace operation is
  52 to be enabled (TRUE) or disabled (FALSE).
  53 <p>
  54 <dt> <var>nargs</var>
  55 <dd>
  56 specifies how many arguments are passed in the args array.
  57 <p>
  58 <dt> <var>args</var>
  59 <dd>
  60 an array, each element of which is a character string
  61 representing a specific subsystem or event type. These values must
  62 correspond to the ones the kernel uses to represent the same
  63 subsystems and event types. The maximum length of a character string
  64 is EVENT_NAME_LENGTH (defined in <strong>mach/etap.h</strong>).
  65 </dl>
  66 <h3>DESCRIPTION</h3>
  67 <p>
  68 The <strong>etap_trace_event</strong> system call is used to enable
  69 and disable kernel event probes (of a specified type) and all modes of lock event
  70 tracing. The call also supports a reset option, where the cumulative
  71 buffer data and all event type tracing is reset to zero. When the
  72 reset option is used, a new interval width can also be defined, using
  73 the <var>nargs</var> parameter.
  74 <p>
  75 To reset the ETAP instrumentation,
  76 the system call would utilize the mode parameter, passing the value of
  77 ETAP_RESET (All other parameters may equal NULL). If, at the time of
  78 reset, the <var>nargs</var> parameter is assigned a value, then the
  79 cumulative buffer interval width will be adjusted to be the size of
  80 that value.  For example, the following system call would reset the
  81 ETAP instrumentation and adjust the cumulative buffer's interval width
  82 to 100ms:
  83 <pre>
  84          etap_trace_event(ETAP_RESET, 0, 0, 100, 0);
  85
  86 </pre>
  87 <h3>RETURN VALUES</h3>
  88 <dl>
  89   <dt> <strong>KERN_SUCCESS</strong>
  90        <dd>
  91             The call was performed successfully.
  92 <p>
  93   <dt> <strong>KERN_NO_SPACE</strong>
  94        <dd>
  95             A shortage of kernel resources prevented the operation from completing;
  96             the kernel has cleaned up all residual state (the error indicates a "clean"
  97             failure).
  98 <p>
  99   <dt> <strong>KERN_FAILURE</strong>
 100        <dd>
 101             ETAP is not configured in the kernel.
 102 </dl>
 103 <h3>RELATED INFORMATION</h3>
 104 <p>
 105 Functions:
 106 <a href="etap_probe.html"><strong>etap_probe</strong></a>,
 107 <a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>,
 108 <a href="etap_get_info.html"><strong>etap_get_info</strong></a>.