Re: Documentation about sysfs/procfs entries

Scott Lovenberg <scott.lovenberg@xxxxxxxxx> · Tue, 12 Feb 2008 03:50:26 -0500

Peter Teoh wrote:

  On Feb 12, 2008 2:17 PM, Scott Lovenberg <scott.lovenberg@xxxxxxxxx> wrote:

    On Feb 12, 2008 12:23 AM, Peter Teoh <htmldeveloper@xxxxxxxxx> wrote:

      I  was looking for documentation on the kstack_depth_to_print under

    /proc/sys/kernel, and I found it in Documentation/sysctl.txt (written by
Rik).

      How about /proc/sys/net?   or all other directories under /sys or /proc

    fs?

      Wouldn't it be useful to have a centralized store located in Documentation

    - properly structured,  just a one-liner or two - on the reasons and
explanations for each of these /proc or /sys parameters?   And something to
look for further details?

      Something of the following:

|-- netfilter
|   |-- nf_conntrack_buckets:your explanation here
|   |-- nf_conntrack_checksum:your explanation here...
|   |-- nf_conntrack_count
|   |-- nf_conntrack_expect_max
|   |-- nf_conntrack_generic_timeout
|   |-- nf_conntrack_icmp_timeout
|   |-- nf_conntrack_log_invalid
|   |-- nf_conntrack_max
|   |-- nf_conntrack_tcp_be_liberal
|   |-- nf_conntrack_tcp_loose
|   |-- nf_conntrack_tcp_max_retrans
|   |-- nf_conntrack_tcp_timeout_close
|   |-- nf_conntrack_tcp_timeout_close_wait
|   |-- nf_conntrack_tcp_timeout_established
|   |-- nf_conntrack_tcp_timeout_fin_wait
|   |-- nf_conntrack_tcp_timeout_last_ack
|   |-- nf_conntrack_tcp_timeout_max_retrans
|   |-- nf_conntrack_tcp_timeout_syn_recv
|   |-- nf_conntrack_tcp_timeout_syn_sent
|   |-- nf_conntrack_tcp_timeout_time_wait
|   |-- nf_conntrack_udp_timeout
|   `-- nf_conntrack_udp_timeout_stream
|-- nf_conntrack_max
|-- token-ring
|   `-- rif_timeout
`-- unix
    `-- max_dgram_qlen

Alternatively, we can write a script to extract out the partial

    explanations/details from existing source code, based on some coding
convention/style structure, and further hand-modification from there.
(given the dynamic nature of the kernel code, this may be preferred?)

    I was looking for exactly this about 2 weeks ago; I needed to look up the
knobs for net and disk elevators, and had to jump all over the place.  I
assumed that such a thing should exist, but I didn't find it.  I know I
would personally benefit from this, and I'm sure many others would, too.

My suggestion is that since the parameters are:

a.   divide the symbols into two group:   well-documented vs
undocumented (prefixed by "__" eg, __xxxx).   this supposedly for
sysadmin vs kernel developer.

b.   for each of the official documented /sys control, provide a
one-line description when passed via /sys/help (eg, echo
kstack_depth_to_print > /sys/help) and the helpstring will go to the
console.

On the other hand, this may potentially blow up the vmlinux image size.

First off, let me say that I really like this idea in theory, but I
have a few concerns as far as an implementation is concerned.

I'm not sure if that'll be FHS compliant, but then again, I'm not sure
if anyone is FSH compliant (depending on whom you ask!) anymore (just
checked, last FHS spec. is from 2004 and doesn't contain /sys/ as its
2.6 Linux centric... borrowed from Plan9, IIRC?) 

Also, /sys/ is primarily an interface to hardware and drivers, would
this be an appropriate place for documentation lookup?  I don't know...
it would be in the root of sysfs and if viewed as a(n) lookup/indexing
feature, perhaps that falls in line with the current design.

Finally, is this better handled as a text file in linux/Documentation
and interfaced with a simple grep from userland, keeping with the *nix
philosophy of doing one thing well?

begin:vcard
fn:Scott Lovenberg
n:Lovenberg;Scott
email;internet:scott.lovenberg@xxxxxxxxx
title:Student
tel;cell:570-856-2999
x-mozilla-html:TRUE
url:http://www.scottlovenberg.com
version:2.1
end:vcard