Date: Tue, 9 Dec 1997 15:11:53 +0100 From: Eivind Eklund <eivind@yes.no> To: Mike Smith <mike@smith.net.au> Cc: Eivind Eklund <perhaps@yes.no>, dyson@FreeBSD.ORG, current@FreeBSD.ORG Subject: Re: VM system info Message-ID: <19971209151153.42427@follo.net> In-Reply-To: <199712090058.LAA06720@word.smith.net.au>; from Mike Smith on Tue, Dec 09, 1997 at 11:28:50AM %2B1030 References: <19971209013941.17444@follo.net> <199712090058.LAA06720@word.smith.net.au>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Dec 09, 1997 at 11:28:50AM +1030, Mike Smith wrote:
> > I'd opt for it to be compiled as part of 'make world' instead, but
> > there are certainly some good points to doing it at the kernel build
> > time.
>
> If it was possible to automatically generate a supserset listing at
> 'world' time, that would be good.
I once more don't follow you - which superset? I was thinking of
something like a perl script that goes through the kernel source and
finds SYSCTL() macros and grab documentation from them, with support
for some form of support for adding documentation for non-static
SYSCTLs - possibly just by having a static file that describe them.
This file would be concatenated with the doc extracted from the kernel
source to create the documentation installed.
> If I thought that there was an easy way to arrange pageable kernel
> data, I would be leaping and screaming about putting the above data in
> the kernel RBN.
RBN? (Right B* Now?)
> As it is, any alternative scheme that will serve as a stopgap for
> now and actually achieve the desired goal without requiring massive
> trampling of the kernel and major changes to the interface appeals.
> Hacking some gratuitous macro changes in as a quickie-fix just
> doesn't cut it.
Let's try to orient this towards solutions instead of bashing each
others solutions. My main priorities are as follows:
(1) Documentation becomes available to user(s)
(2) Documentation stays correct and complete (covering the relevant
variables).
(3) Keeping (1) and (2) add minimal workload to the developers; as far
as possible we do work up front and cut the later costs (as
otherwise we'll either block later development or let the
documentation slip)
(4) System should not be a stopgap - parts of the implementation of
the scheme might change later, but the scaffolding itself should
be good enough to be used as far down the road as we can see.
(5) Any significant kernel bloat caused by this should be possible to
disable.
As far as I can see, the best solution to this is to change the
sysctl-macros to add documentation, but I'm open to other solutions
(as long as they at least satisfy (1), (2) and (3)).
But before proposing other solutions, let me just outline the way I
see this progress:
(A) This will give us a standardized form of documentation in the
kernel source. Nothing new will be exported to userland, no new
interface will be defined, no new files created - the docs are just
added as a required part of the kernel, so they can be looked up by
people that have the kernel sources.
(B) Documentation is exported to userland, by scanning kernel sources
and generating text files as a part of 'make world'.
(C) Parts of the kernel is made swappable; documentation is consigned
to such a part. I don't know if this can be done by a C macro; if it
can't, it will probably be necessary to scan the kernel and construct
a new file for the documentation strings. If this is prohibitively
expensive, we could add a make target to do it, and provide a default
version in the CVS repository (which could be updated from time to
time by running 'make sysctldocs' and committing).
(D) Documentation is exported to userland by a kernel interface.
I'm not certain that this is the best solution, as parts of it suck
(esp. (C)) - but I've not seen any other suggestion that seems likely
to satisfy requirement (1), (2) and (3) :-(
But - to see if we can find a better solution - what are your
priorities?
Eivind.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19971209151153.42427>