1 .\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd a DTrace provider for tracing CPU scheduling events
34 .Fn sched:::change-pri "struct thread *" "struct proc *" "uint8_t"
35 .Fn sched:::dequeue "struct thread *" "struct proc *" "void *"
36 .Fn sched:::enqueue "struct thread *" "struct proc *" "void *" "int"
37 .Fn sched:::lend-pri "struct thread *" "struct proc *" "uint8_t" "struct thread *"
38 .Fn sched:::load-change "int" "int"
39 .Fn sched:::off-cpu "struct thread *" "struct proc *"
42 .Fn sched:::remain-cpu
43 .Fn sched:::surrender "struct thread *" "struct proc *"
45 .Fn sched:::tick "struct thread *" "struct proc *"
46 .Fn sched:::wakeup "struct thread *" "struct proc *"
50 provider allows the tracing of events related to CPU scheduling in the 4BSD and
54 .Fn sched:::change-pri
55 probe fires when a thread's active scheduling priority is about to be updated.
56 The first two arguments are the thread whose priority is about to be changed,
57 and the corresponding process.
58 The third argument is the new absolute priority for the thread, while the
59 current value is given by
60 .Dv args[0]->td_priority .
63 probe fires when the currently-running thread elevates the priority of another
64 thread via priority lending.
65 The first two arguments are the thread whose priority is about to be changed,
66 and the corresponding process.
67 The third argument is the new absolute priority for the thread.
68 The fourth argument is the currently-running thread.
72 probe fires immediately before a runnable thread is removed from a scheduler
74 This may occur when the thread is about to begin execution on a CPU, or because
75 the thread is being migrated to a different run queue.
76 The latter event may occur in several circumstances: the scheduler may be
77 attempting to rebalance load between multiple CPUs, the thread's scheduling
78 priority may have changed, or the thread's CPU affinity settings may have
80 The first two arguments to
82 are the thread and corresponding process.
83 The third argument is currently always
87 probe fires when a runnable thread is about to be added to a scheduler run
89 Its first two arguments are the thread and corresponding process.
90 The third argument is currently always
92 The fourth argument is a boolean value that is non-zero if the thread is
93 enqueued at the beginning of its run queue slot, and zero if the thread is
94 instead enqueued at the end.
97 .Fn sched:::load-change
98 probe fires after the load of a thread queue is adjusted.
99 The first argument is the cpuid for the CPU associated with the thread queue,
100 and the second argument is the adjusted load of the thread queue, i.e., the
101 number of elements in the queue.
105 probe is triggered by the scheduler suspending execution of the
106 currently-running thread, and the
108 probe fires when the current thread has been selected to run on a CPU and is
109 about to begin or resume execution.
112 are the thread and corresponding process selected to run following the
113 currently-running thread.
114 If these two threads are the same, the
115 .Fn sched:::remain-cpu
116 probe will fire instead.
119 .Fn sched:::surrender
120 probe fires when the scheduler is called upon to make a scheduling decision by
121 a thread running on a different CPU, via an interprocessor interrupt.
122 The arguments to this probe are the interrupted thread and its corresponding
124 This probe currently always fires in the context of the interrupted thread.
128 probe will fire immediately before the currently-running thread is preempted.
129 When this occurs, the scheduler will select a new thread to run, and one of the
132 .Fn sched:::remain-cpu
133 probes will subsequently fire, depending on whether or not the scheduler selects
134 the preempted thread.
138 probe fires immediately before the currently-running thread is about to suspend
139 execution and begin waiting for a condition to be met.
142 probe fires when a thread is set up to resume execution after having gone to
144 Its arguments are the thread being awoken, and the corresponding process.
148 fires before each scheduler clock tick.
149 Its arguments are the currently-running thread and its corresponding process.
153 provider probes use the kernel types
157 to represent processes and threads, respectively.
158 These structures have many fields and are defined in
160 In a probe body, the currently-running thread can always be obtained with the
162 global variable, which has type
163 .Vt "struct thread *" .
164 For example, when a running thread is about to sleep, the
166 probe fires in the context of that thread, which can be accessed using
170 global variable contains the cpuid of the CPU on which the currently-running
173 The following script gives a breakdown of CPU utilization by process name:
174 .Bd -literal -offset indent
177 self->ts = timestamp;
183 @[execname] = sum((timestamp - self->ts) / 1000);
188 Here, DTrace stores a timestamp each time a thread is scheduled to run, and
189 computes the time elapsed in microseconds when it is descheduled.
190 The results are summed by process name.
192 This provider is not compatible with the
194 provider found in Solaris.
195 In particular, the probe argument types are native
198 .Fn sched:::cpucaps-sleep ,
199 .Fn sched:::cpucaps-wakeup ,
200 .Fn sched:::schedctl-nopreempt ,
201 .Fn sched:::schedctl-preempt ,
203 .Fn sched:::schedctl-yield
204 probes are not available in
210 .Fn sched:::load-change
211 probes are specific to
222 provider first appeared in
226 This manual page was written by
227 .An Mark Johnston Aq Mt markj@FreeBSD.org .