From owner-freebsd-hackers Thu Feb 18 15:20:53 1999 Delivered-To: freebsd-hackers@freebsd.org Received: from apollo.backplane.com (apollo.backplane.com [209.157.86.2]) by hub.freebsd.org (Postfix) with ESMTP id D56FE119C2 for ; Thu, 18 Feb 1999 15:19:46 -0800 (PST) (envelope-from dillon@apollo.backplane.com) Received: (from dillon@localhost) by apollo.backplane.com (8.9.3/8.9.1) id PAA27201; Thu, 18 Feb 1999 15:18:38 -0800 (PST) (envelope-from dillon) Date: Thu, 18 Feb 1999 15:18:38 -0800 (PST) From: Matthew Dillon Message-Id: <199902182318.PAA27201@apollo.backplane.com> To: Peter Jeremy Cc: hackers@FreeBSD.ORG Subject: Re: Documenting sysctl knobs References: <99Feb19.084745est.40350@border.alcanet.com.au> Sender: owner-freebsd-hackers@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG 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 : :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