Peter Teoh wrote:
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.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 /procfs?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 partialexplanations/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. 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