DTRACE_SCHED(4) FreeBSD Kernel Interfaces Manual DTRACE_SCHED(4)
NAME
dtrace_sched - a DTrace provider for tracing CPU scheduling events
SYNOPSIS
sched:::change-pri(struct thread *, struct proc *, uint8_t);
sched:::dequeue(struct thread *, struct proc *, void *);
sched:::enqueue(struct thread *, struct proc *, void *, int);
sched:::lend-pri(struct thread *, struct proc *, uint8_t,
struct thread *);
sched:::load-change(int, int);
sched:::off-cpu(struct thread *, struct proc *);
sched:::on-cpu();
sched:::preempt();
sched:::remain-cpu();
sched:::surrender(struct thread *, struct proc *);
sched:::sleep();
sched:::tick(struct thread *, struct proc *);
sched:::wakeup(struct thread *, struct proc *);
DESCRIPTION
The DTrace sched provider allows the tracing of events related to CPU
scheduling in the 4BSD and ULE schedulers.
The sched:::change-pri() 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 args[0]->td_priority. The sched:::lend-pri()
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.
The sched:::dequeue() 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 sched:::dequeue() are the thread and corresponding process. The third
argument is currently always NULL. The sched:::enqueue() 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 NULL. 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.
The sched:::load-change() 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.
The sched:::off-cpu() probe is triggered by the scheduler suspending
execution of the currently-running thread, and the sched:::on-cpu() 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 sched:::off-cpu()
are the thread and corresponding process selected to run following the
currently-running thread. If these two threads are the same, the
sched:::remain-cpu() probe will fire instead.
The sched:::surrender() 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.
The sched:::preempt() 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 sched:::off-cpu() or
sched:::remain-cpu() probes will subsequently fire, depending on whether
or not the scheduler selects the preempted thread.
The sched:::sleep() probe fires immediately before the currently-running
thread is about to suspend execution and begin waiting for a condition to
be met. The sched:::wakeup() 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.
The sched:::tick() fires before each scheduler clock tick. Its arguments
are the currently-running thread and its corresponding process.
ARGUMENTS
The sched provider probes use the kernel types struct proc and struct
thread to represent processes and threads, respectively. These
structures have many fields and are defined in sys/proc.h. In a probe
body, the currently-running thread can always be obtained with the
curthread global variable, which has type struct thread *. For example,
when a running thread is about to sleep, the sched:::sleep() probe fires
in the context of that thread, which can be accessed using curthread.
The curcpu global variable contains the cpuid of the CPU on which the
currently-running thread is executing.
EXAMPLES
The following script gives a breakdown of CPU utilization by process
name:
sched:::on-cpu
{
self->ts = timestamp;
}
sched:::off-cpu
/self->ts != 0/
{
@[execname] = sum((timestamp - self->ts) / 1000);
self->ts = 0;
}
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.
COMPATIBILITY
This provider is not compatible with the sched provider found in Solaris.
In particular, the probe argument types are native FreeBSD types, and the
sched:::cpucaps-sleep(), sched:::cpucaps-wakeup(),
sched:::schedctl-nopreempt(), sched:::schedctl-preempt(), and
sched:::schedctl-yield() probes are not available in FreeBSD.
The sched:::lend-pri() and sched:::load-change() probes are specific to
FreeBSD.
SEE ALSO
dtrace(1), sched_4bsd(4), sched_ule(4), SDT(9), sleepqueue(9)
HISTORY
The sched provider first appeared in FreeBSD 8.4 and 9.1.
AUTHORS
This manual page was written by Mark Johnston <markj@FreeBSD.org>.
FreeBSD 13.1-RELEASE-p6 April 18, 2015 FreeBSD 13.1-RELEASE-p6
man2web Home...