Good documentation means more effort can be directed at improvement rather than
understanding.
RMS: says that good documentation is one of the major problems being faced by
the free software community. I agree with him on that point.
I agree with Mr. King that we do not want to pollute the code with too much
comentary. However, I think we need to be carful not to turn this into a craft
guild by under documenting the source.
(Spoken as someone trying to get into the guild. ;-)
I also wish to apologize for saying the wrong thing in one of my other messages.
I stated I wanted the documentation to appear in the source. I meant to say I
wanted the documentation to appear int the documentaion subtree of the ARM
source.
When learning most people start at the begining and that means head-armv.S.
-------------------
Here is how Steve and I documented that section of code being discussed. We feel
it strikes a good balance, experienced
hackers can easily ignore the comments and newbies get enough information to
allow them to figure out what is
happening.
?????? means a possible error in the comment.
/*
* Read processor ID register (CP#15, CR0), and determine
* processor type.
*
* Returns:
* r5, r6, r7 corrupted
* r8 = page table flags
* r9 = processor ID
* r10 = pointer to processor structure
*/
__lookup_processor_type:
adr r5, 2f
ldmia r5, {r7, r9, r10}
/*
* At this point: r5 := A+12
* r7 := proc_info_end
* r9 := A
* r10 := proc_info_begin
*/
sub r5, r5, r9 @ size of below structure
add r7, r7, r5 @ Offset to proc_info_end
add r10, r10, r5 @ Offset to proc_info_begin
mrc p15, 0, r9, c0, c0 @ get processor id
/*
* Loop through proc_info_list looking for a match to the CPU ID stored in r9.
*/
1: ldmia r10, {r5, r6, r8} @ cpu_value, cpu_mask, mmuflags
eor r5, r5, r9
tst r5, r6 @ apply cpu_mask
moveq pc, lr @ return if match found
add r10, r10, #36 @ sizeof(proc_info_list) proc_info?????
cmp r10, r7
blt 1b @ more records to process
mov r10, #0 @ match not found
mov pc, lr @ return
/*
* A+8 __proc_info_begin
* A+4 A
* A __proc_info_end
*/
2: .long __proc_info_end @ Look at /mm/proc-*.S and
.long 2b @ vmlinux.lds for details
.long __proc_info_begin
SAM
unsubscribe: body of `unsubscribe linux-arm' to [EMAIL PROTECTED]
++ Please use [EMAIL PROTECTED] for ++
++ kernel-related discussions. ++
