Date: Thu, 18 Feb 1999 15:18:38 -0800 (PST) From: Matthew Dillon <dillon@apollo.backplane.com> To: Peter Jeremy <peter.jeremy@auss2.alcatel.com.au> Cc: hackers@FreeBSD.ORG Subject: Re: Documenting sysctl knobs Message-ID: <199902182318.PAA27201@apollo.backplane.com> References: <99Feb19.084745est.40350@border.alcanet.com.au>
next in thread | previous in thread | raw e-mail | index | archive | help
We could do a javadoc like thingy where we document the item in
a comment in the source code and then run a program to generate
the documentation by scanning the the source.
-Matt
Matthew Dillon
<dillon@backplane.com>
:
:Just to re-open this particular festering sore...
:
:I don't want to pick on Matt Dillon in particular, but a recent commit
:of his (dillon 1999/02/18 11:57:33 PST) states:
:
:> Add two swap tuneables to sysctl:
:>
:> vm.swap_async_max: 4
:> vm.swap_cluster_max: 16
:>
:> Recommended values are a cluster size of 8 or 16 pages. async_max is
:> about right for 1-4 swap devices. Reduce to 2 if swap is eating too much
:> bandwidth, or even 1 if swap is both eating too much bandwidth and sitting
:> on a slow network (10BaseT).
:>
:> The defaults work well across a broad range of configurations and should
:> normally be left alone.
:
:IMHO, this is the sort of documentation that is needed for all the
:tunable sysctl identifiers. The problem is that (IMHO again), CVS
:logs aren't the correct place for it - the information needs to be
:available to a sysadmin who doesn't have the CVS archive on-line (and
:may not even want to RTSL [*]). Adding several hundred bytes of text
:per identifier to the in-memory kernel image is also not the right
:place. man8/sysctl.8 may be a reasonable place, but it doesn't get
:updated (and the logistics involved in having lots of different
:people all trying to update a single file virtually guarantee that
:updates would be lost).
:
:Physically, the information needs to be in the source code near the
:sysctl OID definition - so it gets updated. It also needs to be
:accessible from either man or sysctl(8) - so the sysadmin doesn't need
:to rummage thru the source code.
:
:I can immediately think of two solutions:
:1) Include the documentation as a parameter to the SYSCTL_OID macro
: (and it's various derivatives). This parameter gets inserted (as
: text) into an ELF section that's not loaded. sysctl(8) can locate
: the description by reading it out of the kernel image on disk.
: (The section could also be stripped out to reduce disk space if
: necessary).
:2) Mark the documentation is some way (possibly, but not necessarily
: via the SYSCTL_OID macro) so that it can be easily extracted from
: the source by an awk or perl script and turned into a man page
: (or several) - ie there'd be a single automatically generated
: sysctl.oid(7) man page that documented all sysctl identifiers,
: or several man pages, each documenting a group of identifiers.
:
:[*] As a `production OS', it should not be necessary for the sysadmin
: to be intimately familiar with the source code.
:
:Peter
:
:
:To Unsubscribe: send mail to majordomo@FreeBSD.org
:with "unsubscribe freebsd-hackers" in the body of the message
:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-hackers" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199902182318.PAA27201>