Zach Welch writes:
> ((Now, all of the above I had written in a different message to send to the
> group before I saw Russel's response to S A McConnell (which follows). I
> have to agree to some extent with SAM in that the ARM portions of the kernel
> are not entirely as well documented as some might think, the above is only
> one example. In fact, I only today managed to figure out the entire flow of
> control between __entry and start_kernel, which is _not_ documented clearly
> at all.))
Each section of code has a description of what it does in head-armv.S.
> I disagree. Adequate for "THE developer of ARM Linux" perhaps, but not for
> the rest of us mere mortals. ;^) The initial page table setup should, at the
> very least, tell the programmer where to look for the definition of the
> structure that is being created.
Err, no, not really. The documentation incorporated into the kernel is
merely there to let people who know what they're doing. It's not designed
so that someone who knows nothing about ARM can work out what's going on.
To do so would significantly increase the size of the source code, which
people already think is too big. Don't forget that the Linux kernel is
organised to make the "hackers" life easier, not to make it easy for
others to understand or even learn.
> I abosultely agree on this point, with one small exception. Reference
> manuals are the ultimate source of information, but the code should contain
> enough information to figure out _where_ in _which_ of the several books
> piled next to my computer I should start looking in. Nothing more.
For something as simple as the ARM page tables, its something that any
programmer who is thinking about looking at ARM code should know before.
The split between the ARM ARM and the individual TRMs is quite well
defined - one describes the "architecture" and the other is the "specific
implementation details". Therefore, most, if not all of the stuff outside
the proc-*.S files relates to the ARM ARM, and the stuff inside proc-*.S
relates to the TRMs.
> I BELIEVE that an extended description should be inserted before every
> logical step that can be described in one line of comment. This is not to
> say that every op gets a line of comment, but I BELIEVE that you should be
> able to recreate the function of the code by looking solely at the comments.
I disagree. I'm sure you'd say that about C code if you didn't know
anything about C.
> I know that in some ways this example directly violates the Linux Coding
> Style Guide in several places, but I BELIEVE that style does not fully apply
> here - its goal is to direct C programmers in their efforts. Assembly
> language is a whole other beast, and should be treated as such.
Several points in reply here:
1. You missed out the most important comments of all there - the ones at
the head of the section of code that tells you what the following code
is doing. This should really be all you need.
2. The comments should definitely not be there to describe how the
instruction set works, which is almost what your comments were doing.
This is something that the person working on the code should know
already.
You've got to know what you're doing, really. The general idea behind
most of the assembler code that is now in the kernel is that it should
be generic across many processors, and as such the newly acquanted
programmer should not have to delve into this code deeply.
If you do need to delve into it deeply, and you don't know much about
ARM code, then that is the time to contact the mailing lists stating what
you'd like to do - since this is code which runs on many different
processors, you've got to be aware of all the issues surounding all
the ARM processors that Linux is expected to run on.
May I give you an example of where your theory falls down?
You wouldn't get the plumber to comment every T and bend in your heating
system so that the gas engineer can modify your plumbing or vice versa?
Wouldn't you prefer to get someone in who was qualified to change the
plumbing in, rather than someone who may flood your house with water?
_____
|_____| ------------------------------------------------- ---+---+-
| | Russell King [EMAIL PROTECTED] --- ---
| | | | http://www.arm.linux.org.uk/ / / |
| +-+-+ --- -+-
/ | THE developer of ARM Linux |+| /|\
/ | | | --- |
+-+-+ ------------------------------------------------- /\\\ |
unsubscribe: body of `unsubscribe linux-arm' to [EMAIL PROTECTED]
++ Please use [EMAIL PROTECTED] for ++
++ kernel-related discussions. ++
