Subject: RE: *TODO* Document the pseudo-ops (adr, ops)

From: Jeff Sutherland <[email-masked]>
Date: Tue, 25 Apr 2000 16:49:40 -0400

> >into the arch/arm/kernel source pretty heavily. In my 
> pursuit, I ran across
> >the 'adr' opcode several times. Being unfamiliar with the 
> opcode, I looked
> >through the 'info' page only to discover the following message:
> >
> >*TODO* Document the pseudo-ops (adr, ops)
> 
> "adr rN, label" loads the (run-time) address of `label' into rN.  It 
> actually translates to "add rN, pc, #(label - . - 8)" or 
> something similar.
> 
> p.

  nop is another favourite.  There is no ARM processor instruction for no
operation.  My assembler translates "nop" into
 "mov r0, r0" which essentially does nothing (the whole purpose of nop).
The more you work with the ARM processor, the more you will like it.  There
are some tricky things to watch out for, such as the pc always being 8 bytes
ahead of the current instruction, and manipulating the caches and MMU, the
details of which are left for the reader to discover :)

//Jeff

unsubscribe: body of `unsubscribe linux-arm' to [email-masked]
++        Please use [email-masked] for           ++
++                        kernel-related discussions.                      ++

---

From: S A McConnell <[email-masked]>
Date: Wed, 26 Apr 2000 08:14:43 -0500

> There are some tricky things to watch out for, such as the pc always being 8
bytes
> details of which are left for the reader to discover :)

I would love to see some documentation about the MMU setup for the ARM and how
the tables are constructed. Since I started looking at the kernel in January I
have been wondering why there is no documentation.

Does anyone have some written notes that they are willing to share? I asked a
question back in January on this subject and did not get a response.

Scott McConnell

---

From: S A McConnell <[email-masked]>
Date: Wed, 26 Apr 2000 08:37:24 -0500

I have captured the comments of Jeff Sutherland, Philip Blundell and Russell
King about assembler errata into a text file.

I discovered these things the hardway.  If you have other facts I will try to
keep the text  current.

Does this seem like a good idea?

SAM
S A McConnell

---

From: Paul Koning <[email-masked]>
Date: Wed, 26 Apr 2000 09:59:13 -0400 (EDT)

>>>>> "S" == S A McConnell <[email-masked]> writes:

 >>  There are some tricky things to watch out for, such as the pc
 S> bytes
 >> ahead of the current instruction, and manipulating the caches and
 >> MMU, the details of which are left for the reader to discover :)

 S> I would love to see some documentation about the MMU setup for the
 S> ARM and how the tables are constructed. Since I started looking at
 S> the kernel in January I have been wondering why there is no
 S> documentation.

You can get a lot from the StrongARM data book and the ARM
architecture manual.  In fact, it's hard to see how you can do
meaningful work in the ARM-specific code without having those two
books on your desk...

      paul

---

From: Erik Mouw <[email-masked]>
Date: Wed, 26 Apr 2000 16:37:39 +0200 (MET DST)

> Does this seem like a good idea?

Sounds good. Where are you going to submit the text file? In the ArmLinux
source, or in the gcc documentation?

Erik

-- 
J.A.K. (Erik) Mouw, Information and Communication Theory Group, Department
of Electrical Engineering, Faculty of Information Technology and Systems,
Delft University of Technology, PO BOX 5031,  2600 GA Delft, The Netherlands
Phone: +31-15-2783635  Fax: +31-15-2781843  Email: [email-masked]
WWW: http://www-ict.its.tudelft.nl/~erik/

---

From: S A McConnell <[email-masked]>
Date: Wed, 26 Apr 2000 10:48:42 -0500

>source, or in the gcc documentation?

A good question.

I was thinking it should be in the Arm Linux source.  But it would make since for
it to also appear in the info pages for the assembler.

SAM

---

From: Russell King - ARM Linux Admin <[email-masked]>
Date: Wed, 26 Apr 2000 19:34:34 +0100 (BST)

> Does this seem like a good idea?

If you want to put the bare-ends HTML around it, I'll apply the almost
standard look-and-feel headers/footers to it and drop it into the ARM Linux
site developer area.  This is the kind of thing it was created for.
   _____
  |_____| ------------------------------------------------- ---+---+-
  |   |        Russell King       [email-masked]      --- ---
  | | | |            http://www.arm.linux.org.uk/            /  /  |
  | +-+-+                                                     --- -+-
  /   |               THE developer of ARM Linux              |+| /|\
 /  | | |                                                     ---  |
    +-+-+ -------------------------------------------------  /\\\  |

---

From: Russell King - ARM Linux Admin <[email-masked]>
Date: Wed, 26 Apr 2000 19:29:08 +0100 (BST)

S A McConnell writes:
> > There are some tricky things to watch out for, such as the pc always
> > being 8 bytes ahead of the current instruction, and manipulating the
> > caches and MMU, the details of which are left for the reader to
> > discover :)

The above is all covered in both the ARM architecture reference manual and
the individual processor technical reference manuals.

> I would love to see some documentation about the MMU setup for the ARM
> and how the tables are constructed. Since I started looking at the
> kernel in January I have been wondering why there is no documentation.

Again, the structure of the MMU tables is described in the ARM architecture
reference manual and the individual processor TRMs - there are some parts of
the tables which are processor implementation specific.

The various bits where the tables are initialised are commented.  The
initial setup code that allows the kernel to get going is very well self-
documented.  Looking at the other code, it also seems to have adequate
comments for what the code is doing.

Please note that the kernel sources are not supposed to contain reference
information, but are supposed to contain enough for a programmer to
understand what the code is doing.  The general guidance given here is that
the code should be written such that it is understandable, and with comments
that do not describe what every line of code does, but describes the purpose
behind what the code is doing.

I hope this helps.
   _____

---

From: Philip Blundell <[email-masked]>
Date: Wed, 26 Apr 2000 19:58:56 +0100

>I was thinking it should be in the Arm Linux source.  But it would make since 
>for it to also appear in the info pages for the assembler.

Great.  Improvements for the GAS manual are always welcome.  You can send 
them to me directly, or to <[email-masked]>.  Patches against 
the texinfo source are ideal, but just plain text would do.

It's true that the pseudo-ops like ADR should probably be explicitly 
documented, since they don't feature in the ARM architecture manual and 
suchlike references.

p.

---

From: "Zach Welch" <[email-masked]>
Date: Wed, 26 Apr 2000 15:22:23 -0700

Ok, I can't resist jumping in again. Thanks to everyone for their prompt and
detailed responses; I can't tell you how happy it makes me to see that the
ARM Linux crowd jumps on the opportunity to help out. Since yesterday, I've
come to understand much more of the initialization than I did previously.

There are quite a few puzzles to unwind during initialization. For instance,
I was a bit confused by how proc_info structures (arch/arm/mm/proc-*.S) were
searched during initialization. Further snooping revealed the
arch/arm/vmlinux-armv.lds.in file, which goes a long way in explaining this.
A simple comment in the head-armv.S that describes this bit of magic would
be invaluable. (See below for my example)

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

----- Original Message -----
From: Russell King - ARM Linux Admin <[email-masked]>
Sent: Wednesday, April 26, 2000 11:29 AM
Subject: Re: *TODO* Document the pseudo-ops (adr, ops)
[snip]
> > kernel in January I have been wondering why there is no documentation.
[snip]
> comments for what the code is doing.

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. Also, where is then used? That would answer
why the code is here in the first place. How do I understand it well enough
to change it? A simple reference as to what files to look in would be
immensely helpful. In addition...

> behind what the code is doing.

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.

As for the density of comments, I believe your statement stands on its own
for high level programming languages, and generally agrees with the Linux
Kernel Coding Style Guide. However, I partially disagree when it comes to
assembly; I'm sorry but it doesn't just document itself.

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.
In other words, you should be able to remove the code and be able to
reimplement those portions of the code. (I'm not entirely happy with the way
I've phrased this last paragraph, and I'm sure I'll catch flak for it).

To show that I'm not all talk, here's an example of what I mean from
head-armv.S before and after my meddling. I intend to pepper things as I run
across them in a similar fashion, so I would appreciate feedback on my
efforts, particularly since I hope to make these changes stick in the main
distribution.

<------------ snip ---------------->

__lookup_processor_type:
  adr r5, 2f
  ldmia r5, {r7, r9, r10}
  sub r5, r5, r9
  add r7, r7, r5
  add r10, r10, r5
  mrc p15, 0, r9, c0, c0  @ get processor id
1:  ldmia r10, {r5, r6, r8}  @ value, mask, mmuflags
  eor r5, r5, r9
  tst r5, r6
  moveq pc, lr
  add r10, r10, #36   @ sizeof(proc_info_list)
  cmp r10, r7
  blt 1b
  mov r10, #0
  mov pc, lr

2:  .long __proc_info_end
  .long 2b
  .long __proc_info_begin

<------------ snip ---------------->

__lookup_processor_type:
  /* load __proc_info_lookup_table */
  adr r5, __proc_info_lookup_table
  ldmia r5, {r7, r9, r10}

  /* calclulate difference between where we thought .proc.info was
    going to be placed and where the linker actually put it  ??? */
  sub r5, r5, r9

  /* readjust __proc_info_end and __proc_info_begin */
  add r7, r7, r5
  add r10, r10, r5

  mrc p15, 0, r9, c0, c0  @ get processor id

  /* now check against the current proc_info table entry */
1:  ldmia r10, {r5, r6, r8}  @ value, mask, mmuflags
  eor r5, r5, r9
  tst r5, r6
  moveq pc, lr

  /* table entry does not match actual proc id, move to next entry */
  add r10, r10, #36   @ sizeof(proc_info_list)
  cmp r10, r7
  blt 1b

  /* no more entries, return error */
  mov r10, #0
  mov pc, lr

  /* proc_info_lookup_table - one entry for each processor type */
 /* __proc_info_end and __proc_info_begin are defined by the linker -
  see the file arch/arm/vmlinux-armv.lds.in */
/*  proc_info structure is declared in include/asm-arm/procinfo.h */
/*  proc_info structures are defined in arch/arm/mm/proc-*.S */
__proc_info_lookup_table:
  .long __proc_info_end
  .long __proc_info_lookup_table
  .long __proc_info_begin

<------------ snip ---------------->

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. It's too
dense to read, never mind modify, without thorough documentation. I BELIEVE
that, when you sit down in front of the kernel source For The First Time,
you should be able to _mentally_ walk through the code. Furthermore, those
of you who have been doing this for a while may be able to read the assembly
without comments and know what's going on, but the comments aren't for you,
are they?

Now that I've shared these quasi-religious beliefs, feel free to bash away
at the cornerstones of my reasoning.... (I know, I too find it hard to
believe that everyone won't agree with me outright... :) :)

Cheers,

Zach Welch
Firmware Architect
At Work Computers
www.atworkcom.com

---

From: Russell King - ARM Linux Admin <[email-masked]>
Date: Wed, 26 Apr 2000 23:55:57 +0100 (BST)

> control between __entry and start_kernel, which is _not_ documented clearly

Each section of code has a description of what it does in head-armv.S.

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

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

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

> 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-masked]      --- ---
  | | | |            http://www.arm.linux.org.uk/            /  /  |
  | +-+-+                                                     --- -+-
  /   |               THE developer of ARM Linux              |+| /|\
 /  | | |                                                     ---  |
    +-+-+ -------------------------------------------------  /\\\  |

---

From: "Zach Welch" <[email-masked]>
Date: Wed, 26 Apr 2000 17:59:02 -0700

my comments are inline with Russel's reply

----- Original Message -----

> Each section of code has a description of what it does in head-armv.S.

In my opinion these DO NOT sufficiently describe each section.

> others to understand or even learn.

I believe that I understand ARM fairly well. I certainly know more than
nothing about it. In addition, I believe trying to maintain a small size of
the source base by reducing the limiting the overall number of comments is
self-defeating. I would be happy to see the code size increase drastically
if it was purely from more commenting. Very infrequently do comments
actually decrease the value of the code (the most notable exception being
when they're wrong).

> the proc-*.S files relates to the ARM ARM, and the stuff inside proc-*.S

I'm not disagreeing with the seperation of code, which I think is _very_
well accomplished. My concern is with bringing it together in the mind of
the programmer. I used the page table example because it had just come up,
which turns out not to have been a clear case. The proc_info trick comes
closer to making my point.

> I disagree.  I'm sure you'd say that about C code if you didn't know

NO, because in C you can use "meaningful" variable and function names, flow
control is much more obvious, and you don't have to contort operands to make
them fit into the assemblers limited vocabulary. It's not to difficult to
"speak" your way through C code, in many instances, even if you don't
understand the details. In assembly, all you've got is the details, and this
is the point I am trying to make: inline comments are the only thing that
give that higher picture of things back to programmer.

In the Linux coding style guide, it talks about using <10 locals. Aren't
registers the same thing? And yet, the code in head-armv.s doesn't
(sufficiently, IMO) describe how these are being flung around. The same
arguement applies here - I can't keep the contents of all the registers
straight in my mind as they are carried from one block to another.

>    is doing.  This should really be all you need.

Yes, it should. But in many cases, it isn't. When trying to get a high level
view of the code, those are the most important. But to see how the pieces
actually fit together, you really need that next level of detail (that I'm
preaching for).

>    This is something that the person working on the code should know

I went a little overboard with my example, but I certainly am NOT describing
what the instruction set is doing. For instance, the sub r5, r5, r9
instruction is completely opaque until the programmer figures out exactly
what the comment says. By way of another example, right before __switch_data
label, the add pc, r10, #12 instruction (which jumps to initialize the
processor dependent mm code) is similarly mindboggling until you figure out
that the proc_info structure actually has an opcode built into it (which is
a pretty big deviation from the traditional seperation of data and code).
Presently, neither of these tricks are mentioned at all, and it is these
kinds of things that _need_ to be documented!!!

> the ARM processors that Linux is expected to run on.

I do know what I am doing (Really!), I am familiar with ARM, and I _want_ to
delve deeply into how the kernel is working. I should NOT be required to go
any further than the distribution to do it. All the magic should be
documented. Relying on someone else to understand the magic can have tragic
consequences - if they're hit by a bolt of lightning, all that information
goes up in smoke.

I am not disputing the value of mailing lists and peer assistence, but it
should not be the fastest way to get that information. Describing some
problems takes longer than it does to go chasing down references that could
be made in the comments. And figuring out stuff for yourself (in the true
hacker spirit) goes much further than getting a simple answer to fix one
problem. You often get exposed to other aspects of the system that you were
previously unaware, expanding your entire knowledge base.

>  plumbing in, rather than someone who may flood your house with water?

I don't think this example is valid - we're all plumbers here. Some more
experienced than others, but plumbers nonetheless. And anyone who's had to
work on their own plumbing will tell you that having a _detailed_ blueprint
is essential, particularly if you can't immediately see the parts you'll be
working on or don't even know that those parts even existed. Also, I must
re-emphasize that I DO NOT want every T and bend commented, and it should
not be necessary to do so.

Argh, I really didn't want to get involved in this type of debate (wholly
opinionated and unresolvable to anyone's complete satisfaction), but I
honestly believe that the quality of the comments could be improved markedly
from where they currently are. This stems directly from the fact that I (an
experienced programmer who was already fairly well familiar with ARM) would
_really_ have appreciated better comments having been there, and that I'd
like to see future programmers get off easier.

Cheers,

Zach

---

From: Russell King - ARM Linux Admin <[email-masked]>
Date: Thu, 27 Apr 2000 09:06:46 +0100 (BST)

> my comments are inline with Russel's reply

This is pretty standard for unix-orientated people ;)

> self-defeating.

Err, no one's talking about removing comments.

> the programmer.

However, adding a comment into the code every two or so code lines is
just not on - it adds too much clutter for the people writing the code,
and then not only does the code have to be maintained, but also the
comments.  This usually ends up with the code being maintained, and the
comments not.  The comments eventually becomes wrong, and then there is
no point in having the comments there because they are now misleading.

The above is a view held not just by me, but by the vast majority of
kernel developers.

> I used the page table example because it had just come up,

I'll agree that there could be some more commenting about the linker
trick used there, but that trick is used through out the kernel code
now, so "its nothing new".  However, I agree that a well placed comment
there would not be unreasonable.

> (sufficiently, IMO) describe how these are being flung around.

The ARM only has 16 registers.  3 of these have a well-defined meaning.
For a typical assembler function, all the other 13 are generally not used
unless it's some large complex function.  Take the code in head-armv.S:

__entry:			4 registers used
__ret:				1 registers used
__mmap_switched:		9 registers used but commented sucinctly
create_page_tables:		7 registers used but commented
__error:			3 registers used
__lookup_processor_type:	6 registers used
__lookup_architecture_type:	8 registers used

So generally we're talking about <10 "local variables" in almost every
case, which is within the human minds comprehension.

(You've also gone back to the "how" which the coding style explicitly
 mentions that you should not do, and I agree.  Comments should only
 describe "what", no matter what the context of the comment.)

> The same arguement applies here - I can't keep the contents of all
> the registers straight in my mind as they are carried from one block
> to another.

You don't have to.  Any that are transferred between the various "functions"
is documented in the comments before the function, thus:

/*
 * 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
 */

Ok, so the following bit of code does what the comment says.  Without seeing
the code, it indicates that r5, r6 and r7 will not be preserved, and that is
expected to be in r8, r9 and r10.

Notice that you do not need to know how this information is obtained - in
fact that may well change to some other method, but the above principle
will still hold true because that is the purpose of the code.

When you know the purpose of the code, and decide that you need to know
in great detail how it works, you're really only looking at (in this
example that you originally picked) 18 lines of code (not withstanding your
and my comments above about __proc_info).

That's 18 lines with 6 registers used.  That should be well within the scope
of the human mind to understand.

> actually fit together, you really need that next level of detail (that I'm

See comment above.

> By way of another example, right before __switch_data

Ok looking at this one in depth then.  Ok, what does r10 hold?  Well,
__lookup_processor_type appears to have something to do with it - its
tested shortly after to see if its an invalid processor.  Ok, lets look
at that code.

 *      r10 = pointer to processor structure

Ah, r10 contains that.  Ok, so

	add pc, r10, #12

is jumping into the processor structure.  This must mean that the structure
contains opcodes itself.  Ok, looking in include/asm-arm/procinfo.h, it
re-inforces this:

 * NOTE! The following structure is defined by assembly
 * language, NOT C code.  For more information, check:
 *  arch/arm/mm/proc-*.S and arch/arm/kernel/head-armv.S

So, what do arch/arm/mm/proc-*.S contain?

__sa1110_proc_info:
...
                b       __sa110_setup

Ah, ok, an instruction within the structure.

Oh, btw, the above is very common in most hand-written ARM assembler.

> kinds of things that _need_ to be documented!!!

Why do they need to be documented when they are almost self explanitory.

> any further than the distribution to do it.

Err, no.  You should get the high level view about what its doing.  Then,
refer to the manuals to find out the information about the area that the
code is concerned with, and then go back to the distribution.  You are not
expected to maintain code without the reference documentation, and any
attempt to do otherwise is just plain wrong.  That is true of safety-crit
systems as well, incidentally.

> All the magic should be

I believe that Philip Blundell and Nico Pitre have a good understanding of
how the bits of code work.  Maybe you ought to ask them for their opinions?

> not be necessary to do so.

It is valid.  Most houses do not have these detailed blueprints.  In fact,
I'd guess that when a plumber turns up on your door that he has very little
or no knowledge about how your house is plumbed.  He has to do some
measure of investigation without "comments", use his experiance from other
jobs he's done previously, and use the knowledge that he's been taught at
plumber school.

> like to see future programmers get off easier.

I believe that you're the one trying to air their opinions here.  I've been
trying to state the facts.

If you are talking about having a comment added to describe "what" a
specific bit of code is doing, then that is reasonable.  Just don't go
overboard and try to get "how" when that's not really what you're after
in the first place. ;)
   _____
  |_____| ------------------------------------------------- ---+---+-
  |   |        Russell King       [email-masked]      --- ---
  | | | |            http://www.arm.linux.org.uk/            /  /  |
  | +-+-+                                                     --- -+-
  /   |               THE developer of ARM Linux              |+| /|\
 /  | | |                                                     ---  |
    +-+-+ -------------------------------------------------  /\\\  |

---

From: S A McConnell <[email-masked]>
Date: Thu, 27 Apr 2000 07:01:33 -0500

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.

/*

__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

---

From: Paul Koning <[email-masked]>
Date: Thu, 27 Apr 2000 09:12:12 -0400 (EDT)

I'll keep this short...

Having spent years working on products written entirely in assembler
(large operating systems and assorted applications) as well as
products written entirely or nearly so in high level languages, I have
this observation:

Standard coding style for software written in assembler is that most
source lines have a comment on them.  The comment states what the line
does, since the opcode and register names generally don't carry that
much information.  (In particular, even though *some* assemblers allow
it, the use of mnemonic names for registers is highly unusual.)  This
is in addition to the "block comment" at the top of each function,
where the purpose of the function, registers in/out/clobbered etc. are
documented.

Conversely, standard coding style for high level language code is to
have the function level block comment only, except in large and
complex functions where block comments at smaller intervals are
sometimes used.  But line by line comments are not used since the code
itself can be clear enough.

My impression of Linux assembler code -- and this is not particularly
aimed at Russell, since I've spent more time looking at other people's
code -- is that it is documented C-style rather than traditional
assembler style.  That makes sense if you consider that it's written
by people who do most of their coding in C.

      paul

---

From: Wookey <[email-masked]>
Date: Thu, 27 Apr 2000 14:18:53 +0100 (BST)

On Thu 27 Apr, Zach Welch wrote:

> Argh, I really didn't want to get involved in this type of debate
> (wholly opinionated and unresolvable to anyone's complete
> satisfaction), but I honestly believe that the quality of the comments
> could be improved markedly from where they currently are. This stems
> directly from the fact that I (an experienced programmer who was
> already fairly well familiar with ARM) would _really_ have appreciated
> better comments having been there, and that I'd like to see future
> programmers get off easier.

OK. Now I haven't touched the kernel code yet, so I can't say one way or
the other what I think of the current level of commenting, but Zach's
comments suggest that there is a need for something to make it easier to
'get up to speed' on relevant issues.

Given that we do not really have agreement here on what should go in the
source itself, perhaps a separate document describing the ARM-specific
parts of the kernel and relevant resources is the way to go?

I have started bringing together info, and writing stuff up to make what
should become 'ARMlinux: the book' in the medium term. (In the short term
these docs are going on the web). One chapter of this should certainly be
on overview of the kernel: source structure, design decisions etc. This
could do the job of filling the gotchas that Zach describes, I hope.

What I don't have is the knowledge to write this. Would any of you kernel
people like to contribute an outline that I can edit into proper docs? I
suspect there are only a few people here with the relevant knowledge...
Even just suggestions of what should be in would be a start, and I'll
endeavour to discover said info from those who know :-) Once this is done
I think we would not have too much trouble keeping it updated as things
change (athough, of course such a document, (as with all documents) will
be somewhat behind the state-of-the-art).

Good idea? Bad idea? comments welcome.

It occurs to me that perhaps this discussion should be on arm-kernel, but
we've started here now...

Wookey
-- 
Aleph One Ltd, Bottisham, CAMBRIDGE, CB5 9BA, UK  Tel (00 44) 1223 811679
work: http://www.aleph1.co.uk/     play: http://www.chaos.org.uk/~wookey/

---

From: Russell King - ARM Linux Admin <[email-masked]>
Date: Thu, 27 Apr 2000 14:51:17 +0100 (BST)

> parts of the kernel and relevant resources is the way to go?

Separate documents aren't generally a good idea either.  The problem here is
that they soon get out of step.  From what I've heard on the linux kernel
mailing list, it has some sections dating back to the 1.2.xx days, even
though the code has moved on since then.  The problem is that it contains
errors wrt the latest code.

What has recently been incorporated into the kernel is "DocBook"-style
documentation.  This allows the header comments for C functions to be
incorporated into a document.

I'm not saying that this is a good way for assembler - in fact it's the
wrong thing to do really.
   _____
  |_____| ------------------------------------------------- ---+---+-
  |   |        Russell King       [email-masked]      --- ---
  | | | |            http://www.arm.linux.org.uk/            /  /  |
  | +-+-+                                                     --- -+-
  /   |               THE developer of ARM Linux              |+| /|\
 /  | | |                                                     ---  |
    +-+-+ -------------------------------------------------  /\\\  |