1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<table class="head">
<tr>
<td class="head-ltitle">DTRACE_SCHED(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">DTRACE_SCHED(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">dtrace_sched</code> — <span class="Nd">a
DTrace provider for tracing CPU scheduling events</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Fn">sched:::change-pri</code>(<var class="Fa" style="white-space: nowrap;">struct
thread *</var>, <var class="Fa" style="white-space: nowrap;">struct proc
*</var>, <var class="Fa" style="white-space: nowrap;">uint8_t</var>);</p>
<p class="Pp"><code class="Fn">sched:::dequeue</code>(<var class="Fa" style="white-space: nowrap;">struct
thread *</var>, <var class="Fa" style="white-space: nowrap;">struct proc
*</var>, <var class="Fa" style="white-space: nowrap;">void *</var>);</p>
<p class="Pp"><code class="Fn">sched:::enqueue</code>(<var class="Fa" style="white-space: nowrap;">struct
thread *</var>, <var class="Fa" style="white-space: nowrap;">struct proc
*</var>, <var class="Fa" style="white-space: nowrap;">void *</var>,
<var class="Fa" style="white-space: nowrap;">int</var>);</p>
<p class="Pp"><code class="Fn">sched:::lend-pri</code>(<var class="Fa" style="white-space: nowrap;">struct
thread *</var>, <var class="Fa" style="white-space: nowrap;">struct proc
*</var>, <var class="Fa" style="white-space: nowrap;">uint8_t</var>,
<var class="Fa" style="white-space: nowrap;">struct thread *</var>);</p>
<p class="Pp"><code class="Fn">sched:::load-change</code>(<var class="Fa" style="white-space: nowrap;">int</var>,
<var class="Fa" style="white-space: nowrap;">int</var>);</p>
<p class="Pp"><code class="Fn">sched:::off-cpu</code>(<var class="Fa" style="white-space: nowrap;">struct
thread *</var>, <var class="Fa" style="white-space: nowrap;">struct proc
*</var>);</p>
<p class="Pp"><code class="Fn">sched:::on-cpu</code>();</p>
<p class="Pp"><code class="Fn">sched:::preempt</code>();</p>
<p class="Pp"><code class="Fn">sched:::remain-cpu</code>();</p>
<p class="Pp"><code class="Fn">sched:::surrender</code>(<var class="Fa" style="white-space: nowrap;">struct
thread *</var>, <var class="Fa" style="white-space: nowrap;">struct proc
*</var>);</p>
<p class="Pp"><code class="Fn">sched:::sleep</code>();</p>
<p class="Pp"><code class="Fn">sched:::tick</code>(<var class="Fa" style="white-space: nowrap;">struct
thread *</var>, <var class="Fa" style="white-space: nowrap;">struct proc
*</var>);</p>
<p class="Pp"><code class="Fn">sched:::wakeup</code>(<var class="Fa" style="white-space: nowrap;">struct
thread *</var>, <var class="Fa" style="white-space: nowrap;">struct proc
*</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The DTrace <code class="Nm">sched</code> provider allows the
tracing of events related to CPU scheduling in the 4BSD and ULE
schedulers.</p>
<p class="Pp" id="sched:::change-pri">The
<a class="permalink" href="#sched:::change-pri"><code class="Fn">sched:::change-pri</code></a>()
probe fires when a thread's active scheduling priority is about to be
updated. The first two arguments are the thread whose priority is about to
be changed, and the corresponding process. The third argument is the new
absolute priority for the thread, while the current value is given by
<code class="Dv">args[0]->td_priority</code>. The
<a class="permalink" href="#sched:::lend-pri"><code class="Fn" id="sched:::lend-pri">sched:::lend-pri</code></a>()
probe fires when the currently-running thread elevates the priority of
another thread via priority lending. The first two arguments are the thread
whose priority is about to be changed, and the corresponding process. The
third argument is the new absolute priority for the thread. The fourth
argument is the currently-running thread.</p>
<p class="Pp" id="sched:::dequeue">The
<a class="permalink" href="#sched:::dequeue"><code class="Fn">sched:::dequeue</code></a>()
probe fires immediately before a runnable thread is removed from a scheduler
run queue. This may occur when the thread is about to begin execution on a
CPU, or because the thread is being migrated to a different run queue. The
latter event may occur in several circumstances: the scheduler may be
attempting to rebalance load between multiple CPUs, the thread's scheduling
priority may have changed, or the thread's CPU affinity settings may have
changed. The first two arguments to
<code class="Fn">sched:::dequeue</code>() are the thread and corresponding
process. The third argument is currently always
<code class="Dv">NULL</code>. The
<a class="permalink" href="#sched:::enqueue"><code class="Fn" id="sched:::enqueue">sched:::enqueue</code></a>()
probe fires when a runnable thread is about to be added to a scheduler run
queue. Its first two arguments are the thread and corresponding process. The
third argument is currently always <code class="Dv">NULL</code>. The fourth
argument is a boolean value that is non-zero if the thread is enqueued at
the beginning of its run queue slot, and zero if the thread is instead
enqueued at the end.</p>
<p class="Pp" id="sched:::load-change">The
<a class="permalink" href="#sched:::load-change"><code class="Fn">sched:::load-change</code></a>()
probe fires after the load of a thread queue is adjusted. The first argument
is the cpuid for the CPU associated with the thread queue, and the second
argument is the adjusted load of the thread queue, i.e., the number of
elements in the queue.</p>
<p class="Pp" id="sched:::off-cpu">The
<a class="permalink" href="#sched:::off-cpu"><code class="Fn">sched:::off-cpu</code></a>()
probe is triggered by the scheduler suspending execution of the
currently-running thread, and the
<a class="permalink" href="#sched:::on-cpu"><code class="Fn" id="sched:::on-cpu">sched:::on-cpu</code></a>()
probe fires when the current thread has been selected to run on a CPU and is
about to begin or resume execution. The arguments to
<code class="Fn">sched:::off-cpu</code>() are the thread and corresponding
process selected to run following the currently-running thread. If these two
threads are the same, the <code class="Fn">sched:::remain-cpu</code>() probe
will fire instead.</p>
<p class="Pp" id="sched:::surrender">The
<a class="permalink" href="#sched:::surrender"><code class="Fn">sched:::surrender</code></a>()
probe fires when the scheduler is called upon to make a scheduling decision
by a thread running on a different CPU, via an interprocessor interrupt. The
arguments to this probe are the interrupted thread and its corresponding
process. This probe currently always fires in the context of the interrupted
thread.</p>
<p class="Pp" id="sched:::preempt">The
<a class="permalink" href="#sched:::preempt"><code class="Fn">sched:::preempt</code></a>()
probe will fire immediately before the currently-running thread is
preempted. When this occurs, the scheduler will select a new thread to run,
and one of the <code class="Fn">sched:::off-cpu</code>() or
<a class="permalink" href="#sched:::remain-cpu"><code class="Fn" id="sched:::remain-cpu">sched:::remain-cpu</code></a>()
probes will subsequently fire, depending on whether or not the scheduler
selects the preempted thread.</p>
<p class="Pp" id="sched:::sleep">The
<a class="permalink" href="#sched:::sleep"><code class="Fn">sched:::sleep</code></a>()
probe fires immediately before the currently-running thread is about to
suspend execution and begin waiting for a condition to be met. The
<a class="permalink" href="#sched:::wakeup"><code class="Fn" id="sched:::wakeup">sched:::wakeup</code></a>()
probe fires when a thread is set up to resume execution after having gone to
sleep. Its arguments are the thread being awoken, and the corresponding
process.</p>
<p class="Pp" id="sched:::tick">The
<a class="permalink" href="#sched:::tick"><code class="Fn">sched:::tick</code></a>()
fires before each scheduler clock tick. Its arguments are the
currently-running thread and its corresponding process.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="ARGUMENTS"><a class="permalink" href="#ARGUMENTS">ARGUMENTS</a></h1>
<p class="Pp">The <code class="Nm">sched</code> provider probes use the kernel
types <var class="Vt">struct proc</var> and <var class="Vt">struct
thread</var> to represent processes and threads, respectively. These
structures have many fields and are defined in
<span class="Pa">sys/proc.h</span>. In a probe body, the currently-running
thread can always be obtained with the <var class="Va">curthread</var>
global variable, which has type <var class="Vt">struct thread *</var>. For
example, when a running thread is about to sleep, the
<code class="Fn">sched:::sleep</code>() probe fires in the context of that
thread, which can be accessed using <var class="Va">curthread</var>. The
<var class="Va">curcpu</var> global variable contains the cpuid of the CPU
on which the currently-running thread is executing.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">The following script gives a breakdown of CPU utilization by
process name:</p>
<div class="Bd Pp Bd-indent Li">
<pre>sched:::on-cpu
{
self->ts = timestamp;
}
sched:::off-cpu
/self->ts != 0/
{
@[execname] = sum((timestamp - self->ts) / 1000);
self->ts = 0;
}</pre>
</div>
<p class="Pp">Here, DTrace stores a timestamp each time a thread is scheduled to
run, and computes the time elapsed in microseconds when it is descheduled.
The results are summed by process name.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="COMPATIBILITY"><a class="permalink" href="#COMPATIBILITY">COMPATIBILITY</a></h1>
<p class="Pp">This provider is not compatible with the
<code class="Nm">sched</code> provider found in Solaris. In particular, the
probe argument types are native <span class="Ux">FreeBSD</span> types, and
the <code class="Fn">sched:::cpucaps-sleep</code>(),
<code class="Fn">sched:::cpucaps-wakeup</code>(),
<code class="Fn">sched:::schedctl-nopreempt</code>(),
<code class="Fn">sched:::schedctl-preempt</code>(), and
<code class="Fn">sched:::schedctl-yield</code>() probes are not available in
<span class="Ux">FreeBSD</span>.</p>
<p class="Pp">The <code class="Fn">sched:::lend-pri</code>() and
<code class="Fn">sched:::load-change</code>() probes are specific to
<span class="Ux">FreeBSD</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">dtrace(1)</a>, <a class="Xr">sched_4bsd(4)</a>,
<a class="Xr">sched_ule(4)</a>, <a class="Xr">SDT(9)</a>,
<a class="Xr">sleepqueue(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">sched</code> provider first appeared in
<span class="Ux">FreeBSD</span> 8.4 and 9.1.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">This manual page was written by <span class="An">Mark
Johnston</span>
<<a class="Mt" href="mailto:markj@FreeBSD.org">markj@FreeBSD.org</a>>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">April 18, 2015</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
