Re: [PATCH] ABI Documentation for /proc/timer_list, v2
Hi Randy, Thanks for taking the time to review this. I get the impression, though, that the corresponding patch that creates the 0.5 version of /proc/timer_list is not going to be accepted. Perhaps I should strip down this ABI patch to document just the existing 0.4 /proc/timer_list. Regards, Joe -- 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
Re: [PATCH] ABI Documentation for /proc/timer_list, v2
Joe Korty wrote: > 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.0 + > +++ 2.6.28-rc6/Documentation/ABI/stable/procfs-timer_list 2008-12-01 > 13:07:15.0 -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. Are we supposed to be able to see lines beginning with '#' in this text file, or only in /proc/timer_list ? > + > +The contents of per-CPU hrtimer data fields not > +associated with a particular cpu clock (ie, shared by Please use "CPU" consistenly (instead of "cpu"). > +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 '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:
[PATCH] ABI Documentation for /proc/timer_list, v2
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.0 + +++ 2.6.28-rc6/Documentation/ABI/stable/procfs-timer_list 2008-12-01 13:07:15.0 -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 time
