-<h2>etap_trace_event</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> -
\rmanipulate event probes and lock event tracing.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/etap.h></strong>
\r\r<strong>kern_return_t etap_trace_event</strong>
\r <strong>(etap_data_t</strong> <var>mode</var>,
\r <strong>mode</strong> <var>type</var>,
\r <strong>boolean_t</strong> <var>enable</var>,
\r <strong>enable</strong> <var>nargs</var>,
\r <strong>mode</strong> <var>mode</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\rindicates the desired trace flavor or reset option and may be one,
\ror more, of the following:
\r<ul>
\r<p>
\r <li>
\rETAP_CUMULATIVE: cumulative lock event trace mode.
\r <p>
\r<li>
\rETAP_MONITORED: monitored event trace mode (for probes or locks)
\r<p>
\r<li>
\rETAP_RESET: reset mode, clears all trace status and cumulative buffer entries
\r</ul>
\r<p>
\r<dt> <var>type</var>
\r<dd>
\rused when measuring lock event contention or durations
\rand may be one, or more, of the following:
\r<ul>
\r<p>
\r <li>
\rETAP_CONTENT
\r<p>
\r <li>
\rETAP_DURATION
\r</ul>
\r<p>
\r<dt> <var>enable</var>
\r<dd>
\ra boolean value indicattin whether the event trace operation is
\rto be enabled (TRUE) or disabled (FALSE).
\r<p>
\r<dt> <var>nargs</var>
\r<dd>
\rspecifies how many arguments are passed in the args array.
\r<p>
\r<dt> <var>args</var>
\r<dd>
\ran array, each element of which is a character string
\rrepresenting a specific subsystem or event type. These values must
\rcorrespond to the ones the kernel uses to represent the same
\rsubsystems and event types. The maximum length of a character string
\ris EVENT_NAME_LENGTH (defined in <strong>mach/etap.h</strong>).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>etap_trace_event</strong> system call is used to enable
\rand disable kernel event probes (of a specified type) and all modes of lock event
\rtracing. The call also supports a reset option, where the cumulative
\rbuffer data and all event type tracing is reset to zero. When the
\rreset option is used, a new interval width can also be defined, using
\rthe <var>nargs</var> parameter.
\r<p>
\rTo reset the ETAP instrumentation,
\rthe system call would utilize the mode parameter, passing the value of
\rETAP_RESET (All other parameters may equal NULL). If, at the time of
\rreset, the <var>nargs</var> parameter is assigned a value, then the
\rcumulative buffer interval width will be adjusted to be the size of
\rthat value. For example, the following system call would reset the
\rETAP instrumentation and adjust the cumulative buffer's interval width
\rto 100ms:
\r<pre>
\r etap_trace_event(ETAP_RESET, 0, 0, 100, 0);
\r\r</pre>
\r<h3>RETURN VALUES</h3>
\r<dl>
\r <dt> <strong>KERN_SUCCESS</strong>
\r <dd>
\r The call was performed successfully.
\r<p>
\r <dt> <strong>KERN_NO_SPACE</strong>
\r <dd>
\r A shortage of kernel resources prevented the operation from completing;
\r the kernel has cleaned up all residual state (the error indicates a "clean"
\r failure).
\r<p>
\r <dt> <strong>KERN_FAILURE</strong>
\r <dd>
\r ETAP is not configured in the kernel.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="etap_probe.html"><strong>etap_probe</strong></a>,
\r<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>,
\r<a href="etap_get_info.html"><strong>etap_get_info</strong></a>.
\r\ No newline at end of file
+<h2>etap_trace_event</h2>
+<hr>
+<p>
+<strong>System Trap</strong> -
+manipulate event probes and lock event tracing.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/etap.h></strong>
+
+<strong>kern_return_t etap_trace_event</strong>
+ <strong>(etap_data_t</strong> <var>mode</var>,
+ <strong>mode</strong> <var>type</var>,
+ <strong>boolean_t</strong> <var>enable</var>,
+ <strong>enable</strong> <var>nargs</var>,
+ <strong>mode</strong> <var>mode</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>mode</var>
+<dd>
+indicates the desired trace flavor or reset option and may be one,
+or more, of the following:
+<ul>
+<p>
+ <li>
+ETAP_CUMULATIVE: cumulative lock event trace mode.
+ <p>
+<li>
+ETAP_MONITORED: monitored event trace mode (for probes or locks)
+<p>
+<li>
+ETAP_RESET: reset mode, clears all trace status and cumulative buffer entries
+</ul>
+<p>
+<dt> <var>type</var>
+<dd>
+used when measuring lock event contention or durations
+and may be one, or more, of the following:
+<ul>
+<p>
+ <li>
+ETAP_CONTENT
+<p>
+ <li>
+ETAP_DURATION
+</ul>
+<p>
+<dt> <var>enable</var>
+<dd>
+a boolean value indicattin whether the event trace operation is
+to be enabled (TRUE) or disabled (FALSE).
+<p>
+<dt> <var>nargs</var>
+<dd>
+specifies how many arguments are passed in the args array.
+<p>
+<dt> <var>args</var>
+<dd>
+an array, each element of which is a character string
+representing a specific subsystem or event type. These values must
+correspond to the ones the kernel uses to represent the same
+subsystems and event types. The maximum length of a character string
+is EVENT_NAME_LENGTH (defined in <strong>mach/etap.h</strong>).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>etap_trace_event</strong> system call is used to enable
+and disable kernel event probes (of a specified type) and all modes of lock event
+tracing. The call also supports a reset option, where the cumulative
+buffer data and all event type tracing is reset to zero. When the
+reset option is used, a new interval width can also be defined, using
+the <var>nargs</var> parameter.
+<p>
+To reset the ETAP instrumentation,
+the system call would utilize the mode parameter, passing the value of
+ETAP_RESET (All other parameters may equal NULL). If, at the time of
+reset, the <var>nargs</var> parameter is assigned a value, then the
+cumulative buffer interval width will be adjusted to be the size of
+that value. For example, the following system call would reset the
+ETAP instrumentation and adjust the cumulative buffer's interval width
+to 100ms:
+<pre>
+ etap_trace_event(ETAP_RESET, 0, 0, 100, 0);
+
+</pre>
+<h3>RETURN VALUES</h3>
+<dl>
+ <dt> <strong>KERN_SUCCESS</strong>
+ <dd>
+ The call was performed successfully.
+<p>
+ <dt> <strong>KERN_NO_SPACE</strong>
+ <dd>
+ A shortage of kernel resources prevented the operation from completing;
+ the kernel has cleaned up all residual state (the error indicates a "clean"
+ failure).
+<p>
+ <dt> <strong>KERN_FAILURE</strong>
+ <dd>
+ ETAP is not configured in the kernel.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="etap_probe.html"><strong>etap_probe</strong></a>,
+<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>,
+<a href="etap_get_info.html"><strong>etap_get_info</strong></a>.
projects / apple / xnu.git / blobdiff