[LLVMdev] Re: Bytecodes & docs

[Reid Spencer]

Please note that the latest patch to the BytecodeFormat.html provides
some additional clarity, as noted below. The patch is here:

http://mail.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20040816/017313.html

On Tue, 2004-08-17 at 17:25, Reid Spencer wrote:
> >> > (3) In Reid's documentation, his "opcode" link is bad.  His doc does
> >> > not yet contain an opcode section.  Presumably this would contain the info
> >> > from the include file Instruction.def.
> >>
> >> This is also a doc bug. Its fixed by just referencing the
> >> Instruction.def file on the cvsweb which will always contain the correct
> >> list of instruction opcode values for the latest release. Note that that
> >> might not be correct for *your* release :)
> > 
> > This is not a good fix for people like me who may be a few versions back 
> > from the latest release from time to time.  This info should really be 
> > duplicated in the body of the doc.
> 
> Okay, I see your point. If you'd care to submit a patch, I'll add it in. :) 
> Otherwise, this will have to wait a bit until I can spend some time at it (I 
> have to figure out which instructions go with which versions).

Opcodes are now both fully documented and referenced to the cvsweb.

> >> Because types and values got disassociated in 1.3 (Type no longer
> >> derives from Value), they are handled in separate data structures
> >> internally and written to the symbol table block separately. The
> >> documentation is only slightly deficient in this area as it didn't
> >> correctly identify the type of lists used for the types and value
> >> planes.  The documentation has been updated to correctly reflect the
> >> nature of the lists.
> >>
> >> Robert: if you could, please review:
> >>
> >> http://llvm.x10sys.com/llvm/docs/BytecodeFormat.html#symtab
> >>
> >> and let me know if it makes sense now.
> > 
> > IMHO still not clear.  The problem here is that too many things in this 
> > documentation are referred to as "slot number".  I know that's how the 
> > comments read in the code, but it's unclear.  The term is used both to 
> > describe an index into a type slot and the slot itself.  We need some 
> > clearer nomenclature here.

Slot numbers simply are indices. I've enhanced the documentation to make
this a little more clear.  

> > My suggestion would be to drop the word "slot" entirely and go with 
> > something like "type index" and "value index" for these two kinds of 
> > things.

Slot is a useful term and will continue to be used or else the
*developers* will get confused :) and you don't want that. :)

Sorry if its unfamiliar. The documentation has a pretty good explanation
of what they are in the #slots section.
 
> > Also, painful I know, I would split "symbol table entry" up into two 
> > sections, one for types, one for actual symbols, just so you can make 
> > the description of that first field in each crystal clear.

I did just that. 

Reid.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20040818/b0ed9c92/attachment.sig>