Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 10 Dec 1997 09:56:17 +1030
From:      Mike Smith <mike@smith.net.au>
To:        Eivind Eklund <eivind@yes.no>
Cc:        Mike Smith <mike@smith.net.au>, Eivind Eklund <perhaps@yes.no>, dyson@FreeBSD.ORG, current@FreeBSD.ORG
Subject:   Re: VM system info 
Message-ID:  <199712092326.JAA00418@word.smith.net.au>
In-Reply-To: Your message of "Tue, 09 Dec 1997 15:11:53 BST." <19971209151153.42427@follo.net> 

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? 

A given built kernel will contain some subset of all the possible 
sysctl nodes.  For a non-kernel-specific resource to be useful, it 
should contain (as far as possible) the union of all these sets, ie. a 
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.

I would probably prefer your original suggestion whereby a null macro 
or specially-formatted comment placed the documentation close to the 
code where the dynamically-created nodes were generated.

> > 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?)

Yes. 8)

> 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.

Sounds good.

> 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)).

How about something more generalised, that lets us document other 
kernel items than just sysctl nodes?  Perhaps looking at the tools 
available for automatically generating code-related documentation would 
be enlightening?

> 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.

Yup.

> (B) Documentation is exported to userland, by scanning kernel sources
> and generating text files as a part of 'make world'.

Yup.

> (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).

If you are doing (B), this is not terribly useful; the output from (B) 
should be available via a standard API to userland programs.

> (D) Documentation is exported to userland by a kernel interface.

See (C).

mike




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199712092326.JAA00418>