Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DTRACE_SCHED(4)	       FreeBSD Kernel Interfaces Manual	       DTRACE_SCHED(4)

     dtrace_sched -- a DTrace provider for tracing CPU scheduling events

     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:::surrender(struct thread *,	struct proc *);


     sched:::tick(struct thread	*, struct proc *);

     sched:::wakeup(struct thread *, struct proc *);

     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 mi-
     grated 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	bool-
     ean 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

     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 exe-
     cution 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 inter-
     rupted 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 re-
     sume 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.

     The sched provider	probes use the kernel types struct proc	and struct
     thread to represent processes and threads,	respectively.  These struc-
     tures 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 cur-
     rently-running thread is executing.

     The following script gives	a breakdown of CPU utilization by process

		   self->ts = timestamp;

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

     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

     dtrace(1),	sched_4bsd(4), sched_ule(4), SDT(9), sleepqueue(9)

     The sched provider	first appeared in FreeBSD 8.4 and 9.1.

     This manual page was written by Mark Johnston <>.

FreeBSD	13.0			April 18, 2015			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help