share/man/man4/dtrace_sched.4

   1 .\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  12 .\"
  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
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd April 18, 2015
  28 .Dt DTRACE_SCHED 4
  29 .Os
  30 .Sh NAME
  31 .Nm dtrace_sched
  32 .Nd a DTrace provider for tracing CPU scheduling events
  33 .Sh SYNOPSIS
  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 *"
  40 .Fn sched:::on-cpu
  41 .Fn sched:::preempt
  42 .Fn sched:::remain-cpu
  43 .Fn sched:::surrender "struct thread *" "struct proc *"
  44 .Fn sched:::sleep
  45 .Fn sched:::tick "struct thread *" "struct proc *"
  46 .Fn sched:::wakeup "struct thread *" "struct proc *"
  47 .Sh DESCRIPTION
  48 The DTrace
  49 .Nm sched
  50 provider allows the tracing of events related to CPU scheduling in the 4BSD and
  51 ULE schedulers.
  52 .Pp
  53 The
  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 .
  61 The
  62 .Fn sched:::lend-pri
  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.
  69 .Pp
  70 The
  71 .Fn sched:::dequeue
  72 probe fires immediately before a runnable thread is removed from a scheduler
  73 run queue.
  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
  79 changed.
  80 The first two arguments to
  81 .Fn sched:::dequeue
  82 are the thread and corresponding process.
  83 The third argument is currently always
  84 .Dv NULL .
  85 The
  86 .Fn sched:::enqueue
  87 probe fires when a runnable thread is about to be added to a scheduler run
  88 queue.
  89 Its first two arguments are the thread and corresponding process.
  90 The third argument is currently always
  91 .Dv NULL .
  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.
  95 .Pp
  96 The
  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.
 102 .Pp
 103 The
 104 .Fn sched:::off-cpu
 105 probe is triggered by the scheduler suspending execution of the
 106 currently-running thread, and the
 107 .Fn sched:::on-cpu
 108 probe fires when the current thread has been selected to run on a CPU and is
 109 about to begin or resume execution.
 110 The arguments to
 111 .Fn sched:::off-cpu
 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.
 117 .Pp
 118 The
 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
 123 process.
 124 This probe currently always fires in the context of the interrupted thread.
 125 .Pp
 126 The
 127 .Fn sched:::preempt
 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
 130 .Fn sched:::off-cpu
 131 or
 132 .Fn sched:::remain-cpu
 133 probes will subsequently fire, depending on whether or not the scheduler selects
 134 the preempted thread.
 135 .Pp
 136 The
 137 .Fn sched:::sleep
 138 probe fires immediately before the currently-running thread is about to suspend
 139 execution and begin waiting for a condition to be met.
 140 The
 141 .Fn sched:::wakeup
 142 probe fires when a thread is set up to resume execution after having gone to
 143 sleep.
 144 Its arguments are the thread being awoken, and the corresponding process.
 145 .Pp
 146 The
 147 .Fn sched:::tick
 148 fires before each scheduler clock tick.
 149 Its arguments are the currently-running thread and its corresponding process.
 150 .Sh ARGUMENTS
 151 The
 152 .Nm sched
 153 provider probes use the kernel types
 154 .Vt "struct proc"
 155 and
 156 .Vt "struct thread"
 157 to represent processes and threads, respectively.
 158 These structures have many fields and are defined in
 159 .Pa sys/proc.h .
 160 In a probe body, the currently-running thread can always be obtained with the
 161 .Va curthread
 162 global variable, which has type
 163 .Vt "struct thread *" .
 164 For example, when a running thread is about to sleep, the
 165 .Fn sched:::sleep
 166 probe fires in the context of that thread, which can be accessed using
 167 .Va curthread .
 168 The
 169 .Va curcpu
 170 global variable contains the cpuid of the CPU on which the currently-running
 171 thread is executing.
 172 .Sh EXAMPLES
 173 The following script gives a breakdown of CPU utilization by process name:
 174 .Bd -literal -offset indent
 175 sched:::on-cpu
 176 {
 177         self->ts = timestamp;
 178 }
 179
 180 sched:::off-cpu
 181 /self->ts != 0/
 182 {
 183         @[execname] = sum((timestamp - self->ts) / 1000);
 184         self->ts = 0;
 185 }
 186 .Ed
 187 .Pp
 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.
 191 .Sh COMPATIBILITY
 192 This provider is not compatible with the
 193 .Nm sched
 194 provider found in Solaris.
 195 In particular, the probe argument types are native
 196 .Fx
 197 types, and the
 198 .Fn sched:::cpucaps-sleep ,
 199 .Fn sched:::cpucaps-wakeup ,
 200 .Fn sched:::schedctl-nopreempt ,
 201 .Fn sched:::schedctl-preempt ,
 202 and
 203 .Fn sched:::schedctl-yield
 204 probes are not available in
 205 .Fx .
 206 .Pp
 207 The
 208 .Fn sched:::lend-pri
 209 and
 210 .Fn sched:::load-change
 211 probes are specific to
 212 .Fx .
 213 .Sh SEE ALSO
 214 .Xr dtrace 1 ,
 215 .Xr sched_4bsd 4 ,
 216 .Xr sched_ule 4 ,
 217 .Xr SDT 9 ,
 218 .Xr sleepqueue 9
 219 .Sh HISTORY
 220 The
 221 .Nm sched
 222 provider first appeared in
 223 .Fx
 224 8.4 and 9.1.
 225 .Sh AUTHORS
 226 This manual page was written by
 227 .An Mark Johnston Aq Mt markj@FreeBSD.org .