[PATCH] ABI Documentation for /proc/timer_list, v2

[Joe Korty <joe.korty-oXJCJecloQs@public.gmane.org>]

Document /proc/timer_list ABI, version 2.

This partially documents /timer_list, including the
proposed 'Version 0.5' extensions that add a jiffie timer
display.

v2 exists to address some of the concerns Michael Kerrisk
brought up.  What was left out: I did not document old
versions of /timer_list, I did not document the meaning
of the x.y version numbering system (which only Ingo
can answer anyway), and I did not document fields of
secondary importance that already had adequate 'DocBook'
documentation in the kernel sources.

Signed-off-by: Joe Korty <joe.korty-oXJCJecloQs@public.gmane.org>

Index: 2.6.28-rc6/Documentation/ABI/stable/procfs-timer_list
===================================================================
--- /dev/null	1970-01-01 00:00:00.000000000 +0000
+++ 2.6.28-rc6/Documentation/ABI/stable/procfs-timer_list	2008-12-01 13:07:15.000000000 -0500
@@ -0,0 +1,129 @@
+What:		/proc/timer_list
+Date:		November 2008
+Contact:	Ingo Molnar <mingo-X9Un+BFzKDI@public.gmane.org>
+		Thomas Gleixner <tglx-hfZtesqFncYOwBW4kG4KsQ@public.gmane.org>
+		Joe Korty <joe.korty-oXJCJecloQs@public.gmane.org>
+Revision-Rate:	Moderate
+At-Revision:	0.5
+Description:
+		/proc/timer_list displays most everything about every kind
+		of timer, and some things about time too.
+
+		The contents of this file should be expected to change,
+		as the data displayed corresponds directly to various
+		kernel-internal data structures.  For this reason, the first
+		line contains the file revision.  It is the responsibility
+		of this file's maintainers to bump the revision each time a
+		kernel is released having incompatible changes in this file.
+
+		This document covers only the version of /proc/timer_list
+		located in the kernel sources to which it is attached.
+		Documentation for previous (and later) versions of
+		/proc/timer_list is to be found (if they exist) in the
+		kernel sources of those earlier (or later) kernels.
+
+		Section Overview
+		----------------
+		The file contains several somewhat independent sections.
+
+		The first section contains a few lines of global info:
+		   1 - Timer List Version: File revision.
+		   2 - HRTIMER_MAX_CLOCK_BASES: number of clock types that
+		       support high resolution timers.
+		   3 - now at x nsecs: number of nsecs since boot.
+
+		The second section is organized per-CPU.  Each CPU subsection
+		in turn contains several sub-subsections which are, in order
+		of appearance:
+
+		   The contents of the data structures associated with each
+		   clock on this CPU:
+		    1 - clock ID: 0 == CLOCK_REALTIME, 1 == CLOCK_MONOTONIC
+		    2 - base: kernel address of this clock's
+		        hrtimer_clock_base structure.
+		    3 - resolution: resolution of this clock.
+		    4 - get_time: name of kernel function used to fetch
+		        time from this clock.
+		    5 - offset: difference, in nsecs, between this clock
+		        and the reference clock for this clock.
+		   Under each of these clocks is, in turn, a display of all
+		   the active high resolution timers queued to that clock.
+		   These are the lines beginning with '#' and are described
+		   in detail later in this document.
+
+		   The contents of per-CPU hrtimer data fields not
+		   associated with a particular cpu clock (ie, shared by
+		   both clocks or not associated with any clock).  These
+		   are: expires_next, hres_active, nr_event, nohz_mode, all
+		   things idle_*, tick_stopped, last_jiffies, next_jiffies.
+		   The above are field names from 'struct tick_sched' and
+		   'struct hrtimer_cpu_base', documentation for these may
+		   be found in the kernel DocBook.
+
+		   A display of low resolution (ie, jiffie) timer wheel
+		   data.  These are prefixed by the lines:
+		    1 - base: kernel virtual address of the timer wheel
+		        data structure (struct tvec_base) for this cpu.
+		    2 - running timer: kernel virtual address of the
+		        expired timer being processed, NULL if none.
+		    3 - timer_jiffies: what this wheel considers to
+		        be the current time, will be == jiffies or
+			will lag it by a tick or two if it has not
+			caught up with the current time.
+		   Also under this section is a display, one per line, of
+		   each active jiffie timer queued to this CPU.  These are
+		   the lines under an 'active jiffie timers' section that
+		   begin with a number.
+
+		The third and final section describes each 'tick device'
+		known to the kernel.  A tick device is a piece of hardware
+		capable of generating periodic and/or one-shot interrupts
+		under software control, and thus is capable of generating
+		the interrupts needed to expire the various active timers
+		at their given expiration times.  Examples of tick devices:
+		hpet, pit, lapic.  All but the first two lines display
+		fields corresponding to structure elements from 'struct
+		clock_event_device', documentation for which can be found
+		in the kernel Docbook. The first two lines are:
+		  1 - mode: 0 == periodic timer, 1 == one-shot timer
+		  2 - is 'Per CPU device' or is 'Broadcast device'
+
+		Hires Timer Layout
+		------------------
+		High-resolution timers are displayed on lines that begin
+		with a '#' and always appear under one of the many sections
+		labeled 'active timers'.  There is an 'active timers'
+		section for every CPU and every clock.
+
+		The fields of a hrtimer, spread out over two lines, are:
+
+		line 1 fields:
+		  1 - unique hrtimer index (#0, #1, #2, etc)
+		  2 - kernel address of the hrtimer data structure
+		      in question
+		  3 - function to be called when timer expires
+		  4 - timer state (eg, S:01), avail states, OR-able:
+		      0 - inactive
+		      1 - enqueued
+		      2 - callback
+		      4 - pending
+		      8 - migrate
+		  5 - function which created the timer
+		  6 - process name & pid which created the timer
+
+		line 2 fields:
+		  1 - absolute expiration time, range format (start - end)
+		  2 - relative expiration time, range format (start - end)
+
+		Lowres Timer Layout
+		-------------------
+		Low-resolution timers are displayed one-per-line under
+		sections labeled 'active jiffie timers'.  There is one such
+		section per CPU.  A lowres timer has the following fields:
+
+		  1 - number of jiffies remaining until timer expires
+		  2 - function to be called on expiration
+		  3 - data value to be given to the above function on
+		      expiration
+		  4 - function which created this timer
+		  5 - name & pid of the process that created this timer
--
To unsubscribe from this list: send the line "unsubscribe linux-api" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html