|John S. Dyson||Dec 6, 1997 5:30 am|
|Joao Carlos Mendes Luis||Dec 7, 1997 10:24 am|
|John S. Dyson||Dec 7, 1997 10:29 am|
|Eivind Eklund||Dec 7, 1997 4:43 pm|
|Wolfram Schneider||Dec 7, 1997 5:37 pm|
|John S. Dyson||Dec 7, 1997 5:51 pm|
|Mike Smith||Dec 7, 1997 11:05 pm|
|Eivind Eklund||Dec 8, 1997 12:36 am|
|Johan Granlund||Dec 8, 1997 11:05 am|
|Andrew Reilly||Dec 8, 1997 1:27 pm|
|Mike Smith||Dec 8, 1997 4:04 pm|
|Eivind Eklund||Dec 8, 1997 4:39 pm|
|Mike Smith||Dec 8, 1997 4:58 pm|
|Terry Lambert||Dec 8, 1997 6:03 pm|
|Eivind Eklund||Dec 9, 1997 6:11 am|
|Eivind Eklund||Dec 9, 1997 6:32 am|
|Charles Henrich||Dec 9, 1997 8:43 am|
|Poul-Henning Kamp||Dec 9, 1997 9:18 am|
|Charles Henrich||Dec 9, 1997 9:39 am|
|Eivind Eklund||Dec 9, 1997 10:58 am|
|Charles Henrich||Dec 9, 1997 11:55 am|
|J Wunsch||Dec 9, 1997 3:09 pm|
|Mike Smith||Dec 9, 1997 3:25 pm|
|Terry Lambert||Dec 9, 1997 7:35 pm|
|Terry Lambert||Dec 9, 1997 7:54 pm|
|Bruce Evans||Dec 9, 1997 11:27 pm|
|John S. Dyson||Dec 10, 1997 9:27 am|
|Subject:||Re: VM system info|
|From:||Mike Smith (mi...@smith.net.au)|
|Date:||Dec 9, 1997 3:25:56 pm|
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?)
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)).
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.
(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).
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.