Documentation/perfmon2-debugfs.txt

		The perfmon2 debug and statistics interface
                ------------------------------------------
		           Stephane Eranian
			  <eranian@gmail.com>

The perfmon2 interfaces exports a set of statistics which are used to tune and
debug the implementation. The data is composed of a set of very simple metrics
mostly aggregated counts and durations. They instruments key points in the
perfmon2 code, such as context switch and interrupt handling.

The data is accessible via the debug filesystem (debugfs). Thus you need to
have the filesystem support enabled in your kernel. Furthermore since, 2.6.25,
the perfmon2 statistics interface is an optional component. It needs to be
explicitely enabled in the kernel config file (CONFIG_PERFMON_DEBUG_FS).

To access the data, the debugs filesystem must be mounted. Supposing the mount
point is /debugfs, you would need to do:
	$ mount -t debugs none /debugfs

The data is located under the perfmon subdirectory and is organized per CPU.
For each CPU, the same set of metrics is available, one metric per file in
clear ASCII text.

The metrics are as follows:

	ctxswin_count (read-only):

		Number of PMU context switch in.

	ctxswin_ns (read-only):

		Number of nanoseconds spent in the PMU context switch in
		routine.  Dividing this number by the value of ctxswin_count,
		yields average cost of the PMU context switch in.

	ctxswout_count (read-only):

		Number of PMU context switch out.

	ctxswout_ns (read-only):

		Number of nanoseconds spent in the PMU context switch in
		routine. Dividing this number by the value of ctxswout_count,
		yields average cost of the PMU context switch out.

	fmt_handler_calls (read-only):

		Number of calls to the sampling format routine that handles
		PMU interrupts, i.e., typically the routine that records a
		sample.

	fmt_handler_ns (read-only):

		Number of nanoseconds spent in the routine that handle PMU
		interrupt in the sampling format. Dividing this number by
		the number of calls provided by fmt_handler_calls, yields
		average time spent in this routine.

	ovfl_intr_all_count (read-only):

		Number of PMU interrupts received by the kernel.


	ovfl_intr_nmi_count (read-only):

		Number of Non Maskeable Interrupts (NMI) received by the kernel
		for perfmon. This is relevant only on X86 hardware.

	ovfl_intr_ns (read-only):

		Number of nanoseconds spent in the perfmon2 PMU interrupt
		handler routine. Dividing this number of ovfl_intr_all_count
		yields the average time to handle one PMU interrupt.

	ovfl_intr_regular_count (read-only):

		Number of PMU interrupts which are actually processed by
		the perfmon interrupt handler. There may be spurious or replay
		interrupts.

	ovfl_intr_replay_count (read-only):

		Number of PMU interrupts which were replayed on context switch
		in or on event set switching. Interrupts get replayed when they
		were in flight at the time monitoring had to be stopped.

	perfmon/ovfl_intr_spurious_count (read-only):

		Number of PMU interrupts which were dropped because there was
		no active context (session).

	ovfl_notify_count (read-only):

		Number of user level notifications sent. Notifications are
		appended as messages to the context queue. Notifications may
		be sent on PMU interrupts.

	pfm_restart_count (read-only):

		Number of times pfm_restart() is called.

	reset_pmds_count (read-only):

		Number of times pfm_reset_pmds() is called.

	set_switch_count (read-only):

		Number of event set switches.

	set_switch_ns (read-only):

		Number of nanoseconds spent in the set switching routine.
		Dividing this number by set_switch_count yields the average
		cost of switching sets.

	handle_timeout_count (read-only):

		Number of times the pfm_handle_timeout() routine is called.
		It is used for timeout-based set switching.

	handle_work_count (read-only):

		Number of times pfm_handle_work() is called. The routine
		handles asynchronous perfmon2 work for per-thread contexts
		(sessions).