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>.