Front page | perl.perl6.internals |
Postings from May 2001
Proposed PDD format for Perl6's "assembly language standard"
Thread Next
From:
A. C. Yardley
Date:
May 21, 2001 16:27
Subject:
Proposed PDD format for Perl6's "assembly language standard"
Message ID:
158145760437.20010521183612@tanet.net
This is, obviously, premature, but, since the list has been rather
inactive over the last week or so (and this stuff has been much on
my mind as of late), I thought I'd throw this out there, fwiw.
I'm probably all wet ("And that's, OK" :-), but, recently, I began
to re-review my copy of Jon Meyer and Troy Downing, "JAVA Virtual
Machine" (pub. O'Reilly 1997) [hereinafter "JVM"].[1] One thing, among
others,[2] which struck me was the "Instruction Reference" contained in
Chapter 13 of the book.
The example layout is as follows:[3]
______________________________________________________________________
----------------------------------------------------------------------
B<I<example>>[4] an example of an instruction entry
B<I<Jasmin Syntax>>
example I<<param1>> I<<param2>> ...
B<I<Stack>>
B<Before> | B<After>
-------------------------------------
item1 | item2
item2 | item1
... | ...
-------------------------------------
B<I<Description>>
Explains the format for the instruction reference pages.
The first line on a refence page lists the name of an instruction
and gives a brief synopsis of the instruction.
The I<Jasmin Syntax> section indicates the Jasmin assembler syntax
for the instruction. In the example above, the instruction is shown
with two I<parameters>, one called I<<param1>> and the other called
I<<param2>>. The I<Jasmin Syntax> also includes additional notes
for Jasmin users.
The I<Stack> section describes the effect that the instruction has
on the operand stack. It shows a symbolic representation of the
stack state before and after the execution of the instruction. Each
row in the tables represents a one-word entry on the stack. The
first row represents the top of the stack. In the example above,
it's clear that the order of the top two words on the stack is
reversed by the instruction.
The section year are reading is the I<Description> section, which
gives details of how the instruction works and what its side effects
are.
B<I<Example>>
C<; This section often contains examples illustrating how>
C<; an instruction is used.>
C<; Examples are written using the Jasmin assembler syntax>
B<I<Exceptions>>
This section lists any exceptions generated by the instruction at
runtime, and it explains what cause each exception.
B<I<Bytecode>>
This section gives detals on how the instruction is laid out in the
bytecode of a class file. It shows a table listing the opcode for
the instruction, as well as any additional parameters that follow
the opcode in bytecode.
B<Type> | B<Description>
-----------------------------------------------------------------------
u1 | This line usually shows the opcode for the instruction
u1 | A "u1" field is an unsigned 1-byte integer field
u2 | A "u2" field is an unsigned 2-byte integer field
u4 | A "u4" field is an unsigned 4-byte integer field
s1 | A "s1" field is an signed 1-byte integer field
s2 | A "s2" field is an signed 2-byte integer field
s4 | A "s4" field is an signed 4-byte integer field
-----------------------------------------------------------------------
B<I<See Also>>
This section lists related instructions that you should read.
B<I<Notes>>
This section gives additional details that you should be aware of.[5]
______________________________________________________________________
----------------------------------------------------------------------
And, as a concrete example,
______________________________________________________________________
----------------------------------------------------------------------
B<I<aaload>> retrieve object reference from array
B<I<Jasmin Syntax>>
C<aaload>
B<I<Stack>>
B<Before> | B<After>
-------------------------------------
index | value
arrayref | ...
... |
-------------------------------------
B<I<Description>>
Retrieves an object reference from an array of objects and places it
on the stack. I<arrayref> is a reference to an array of objects,
I<index> is an int. The I<arrayref> and I<index> are removed from
the stack, and the object reference at the given I<index> in the
array is pushed onto the stack.
B<I<Example>>
C<; This is like the Java code:>
C<; Object x = arr[0];>
C<; where x is local variable 2 and arr is an array of objects in
local variable 1>
C<aload_1 ; load local variable 1 onto the stack>
C<iconst_0 ; push the integer 0 onto the stack>
C<aaload ; retrieve the entry>
C<astore_2 ; store the entry in local variable 2>
B<I<Exceptions>>
B<.> NullPointerException--I<aarayref> is C<null>
B<.> ArrayIndexOutOfBoundsException--I<index> is C< < 0 or >= >
I<arrayref.length>
B<I<Bytecode>>
B<Type> | B<Description>
-----------------------------------------------------------------------
u1 | aaload opcode = 0x32 (50)
-----------------------------------------------------------------------
B<I<See Also>>
iaload, faload, daload, laload, baload, caload, saload, iastore,
lastore, fastore, dastore, aastore, bastore, castore, sastore[6]
______________________________________________________________________
----------------------------------------------------------------------
What I propose is perl6-internals (or, per Dan, "the bytecode
definition group") adopt the above format for the PDDs on certain
aspects of Perl6's interpreter (i.e., again, per Dan, "assembly
language standard, ...").
I am willing, at the appropriate time, to volunteer to take on the
documentation project, if everyone, especially Dan, is amenable to
this.
Opinions? Remarks?
/acy
---------------
[1] Please note, I'm certainly not an apologist either for Java
or for the obvious misrepresentations (and, in some instances,
out-and-out FUD) about Perl contained in the book.
(Editorial remark: I must say, I'm, personally, rather disappointed
in O'Reilly's failure to catch the FUD-type remarks about Perl in
this book. But, then again, having been an Editor-in-Chief I can
understand how it happened.)
[2] There are also, imo, some other rather good features of the
book.
[3] As many, if not most, of you will undoubtedly notice, this
reference is not too dissimilar from most assembler references
(which, I imagine, is the point), other than it's a bit more
user-friendly, than most I've seen over the years.
[4] Please note, I haven't (and a quick grep didn't find one)
actually seen a B<I<...>> construct in POD. This said, perldoc did
correctly (for some value of "correct" on a Win32 box) parse it.
Regardless, I am not actually trying to conform the above reference
sections to the POD format; rather, I am trying to provide those who
do not have a copy of the book a "sense," a "flavor," of the layout
of the reference sections in the book.
[5] JVM at 193-194.
[6] JVM at 195-196
Thread Next
-
Proposed PDD format for Perl6's "assembly language standard"
by A. C. Yardley