Re: Take a deep breath...

Kohtala Marko (
15 Jul 1997 19:44:43 +0300

"Steven N. Hirsch" <> writes:
> On Mon, 14 Jul 1997, David S. Miller wrote:
> I almost guarantee that 10% more effort put into documentation and
> commenting would reap great rewards in terms of contributed input from the
> community at large. Then, you CAN go off and design and implement the
> "latest and greatest" - AFTER having paved the way for others to maintain
> and fine-tune the previous "latest and greatest".

I agree mostly. The design is often based on a limited set of
fundamental rules to follow and these should be more readily and
explicitly available.

However, I find that the greatest problem both in documentation and
designing something for the kernel is that the kernel keeps changing
quite a lot. I do not disapprove of the changes, they are needed, but
it still is a problem to deal with.

Some tools like ctags/etags and id-utils help a lot, but still leave a
lot to be desired. They help reading and following the source code by
helping in generating indices over the whole code.

I have been playing with an idea of adding some LClint directives into
linux source and perhaps extending LClint to provide some additional
information about the source code (call graphs, uses of structures,
uses of structure members, ranges of values used). The extracted
information could be used to generate documentation, for example for
structures the places of usage, those corners of call graphs using the
structure, summaries of what functions are called by those functions a
member of structure is known to point at. Of functions the context it
is run in (from which known functions the call originates), possibly
what locks/semaphores are held on the call.

I am not writing about some intelligent code to design converter, but
a tool to collect that data which is easy to find in source, query the
data and format it to annotated graphs and text. For example, ranges
of parameter and structure member values can be collected easily by
taking all the places where constant values are used/assigned. Any
uses of variable just adds a note of some unknown values being
used. This would help in many places (with function pointers
especially) and even if imperfect, not worse than nothing.

Some tools for this already exist, but I have not found a set of tools
that I find worth using. LClint could be developed into data
extraction and better design verification tool. Data query and
formatting tools are available, but I have not found any work on a
good schema for the data.

People interested in writing books can then insert these graphs and
texts into their books in middle of other explanations of the kernel
design. Most likely a book like this should be maintained to contain
the most important design ideas and the data confirming the design.

As a bonus, LClint would check the source not to violate some design
decisions. I am sure the developers of LClint would be glad to have
our feedback on what is needed and even perhaps add the useful

Marko Kohtala -,