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 <[EMAIL PROTECTED]>

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 <[EMAIL PROTECTED]>
+               Thomas Gleixner <[EMAIL PROTECTED]>
+               Joe Korty <[EMAIL PROTECTED]>
+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 [EMAIL PROTECTED]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to