To see what is currently happening visit http://www.perl6.org/
docs/pdds/pdd06_pasm.pod - Parrot Assembly Language
This PDD describes the format of Parrot's bytecode assembly language.
Parrot's bytecode can be thought of as a form of machine language for a virtual super CISC machine. It makes sense, then, to define an assembly language for it for those people who may need to generate bytecode directly, rather than indirectly via the perl (or any other) language.
Parrot opcodes take the format of:
code destination[dest_key], source1[source1_key], source2[source2_key]
The brackets do not denote optional arguments as such--they are real brackets. They may be left out entirely, however. If any argument has a key the assembler will substitute the null key for arguments missing keys.
Conditional branches take the format:
code boolean[bool_key], true_dest
The key parameters are optional, and may be either an integer or a string. If either is passed they are associated with the parameter to their left, and are assumed to be either an array/list entry number, or a hash key. Any time a source or destination can be a PMC register, there may be a key.
Destinations for conditional branches are an integer offset from the current PC.
All registers have a type prefix of P, S, I, or N, for PMC, string, integer, and number respectively.
All assembly opcodes contain only ASCII lowercase letters, digits, and the underscore.
Upper case names are reserved for assembler directives.
Labels all end with a colon. They may have ASCII letters, numbers, and underscores in them. Labels that begin with a dollar sign (the only valid spot in a label a dollar sign can appear) are private to the subroutine they appear in.
Namespaces are noted with the NAMESPACE directive. It takes a single parameter, the name of the namespace. Multilevel namespaces are supported, and the namespaces should be double-colon separated.
Subroutine names are noted with the SUB directive. It takes a single parameter, the name of the subroutine, which is added to the namespace's symbol table. Sub names may be any valid Unicode alphanumeric character and the underscore.
Constants don't need to be named and put in a separate section of the assembly source. The assembler will take care of putting them in the appropriate part of the generated bytecode.
In the following list, there may be multiple (but unlisted) versions of an opcode. If an opcode takes a register that might be keyed, the keyed version of the opcode has a _k suffix. If an opcode might take multiple types of registers for a single parameter, the opcode function really has a _x suffix, where x is either P, S, I, or N, depending on whether a PMC, string, integer, or numeric register is involved. The suffix isn't necessary (though not an error) as the assembler can intuit the information from the code.
In those cases where an opcode can take several types of registers, and more than one of the sources or destinations are of variable type, then the register is passed in extended format. An extended format register number is of the form:
register_number | register_type
where register_type is 0x100, 0x200, 0x400, or 0x800 for PMC, string, integer, or number respectively. So N19 would be 0x413.
Note: Instructions tagged with a * will call a vtable method to handle the instruction if used on PMC registers.
In all cases, the letters x, y, and z refer to register numbers. The letter t refers to a generic register (P, S, I, or N). A lowercase p, s, i, or n means either a register or constant of the appropriate type (PMC, string, integer, or number)
The control flow opcodes check conditions and manage program flow.
Check register tx. If true, branch by X.
Check register tx. If false, branch by X.
Jump to the address held in register x (Px, Sx, or Ix).
Branch forward or backward by the amount in register x. (X may be either Ix, Nx, or Px) Branch offset may also be an integer constant.
Jump to the location specified by register X. Push the current location onto the call stack for later returning.
Branch to the location specified by X (either register or label). Push the current location onto the call stack for later returning.
Pop the location off the top of the stack and go there.
These ops handle manipulating the data in registers
Create a new PMC of class y stored in PMC register x.
Destroy the PMC in register X, leaving it undef
Copies y into x. Note that strings and PMCs are referred to by pointer, so if you do something like:
set S0, S1
this will copy the pointer in S1 into S0, leaving both registers pointing at the same string.
Exchange the contents of registers X and Y, which must be of the same type. (Generally cheaper than using the stack as an intermediary when setting up registers for function calls)
Takes the contents of Y and assigns them into the existing PMC in X.
While set just copies pointers from one register to another, assign actually does a value assignment, as:
$foo = $bar;
X's assign vtable method is invoked and it does whatever is appropriate.
Performs a "deeper" copy of y into x, using the vtable appropriate to the class of Py if cloning a PMC.
Take the value in register y and convert it to a string of type z, storing the result in string register x.
Add registers y and z and store the result in register x. (x = y + z) The registers must all be the same type, PMC, integer, or number.
Subtract register z from register y and store the result in register x. (x = y - z) The registers must all be the same type, PMC, integer, or number.
Multiply register y by register z and store the results in register x. The registers must be the same type.
Divide register y by register z, and store the result in register x.
Increment register x by nn. nn is an integer constant. If nn is omitted, increment is 1.
Decrement register x by nn. nn is an integer constant. If nn is omitted, decrement by 1.
Put the length of string y into integer register x.
Add string y to the end of string x.
Copies string y z times into string x.
These opcodes handle the transcendental math functions. The destination register here must always be either a numeric or a PMC register.
Return the sine of the number in Y
Return the cosine of the number in Y
Return the tangent of the number in Y
Return the secant of the number in Y
Return the arctangent of Y
Return the result of atan2 of Y
Return the arcsine of y
Return the arccosine of y
Return the arcsecant of y
Return the hyperbolic cosine of y
Return the hyperbolic sine of y
Return the hyperbolic tangent of y
Return the hyperbolic secant of y
Return the base 2 log of y
Return the base 10 log of y
Return the base e log of y
Return the base Z log of Y
Return Y to the Z power
Return e to the Y power
These opcodes deal with registers and stacks
Push the current set of PMC registers onto the register frame stack, and start a new set (which will all initially be NULL). Register frames hold only 16 registers, so we need to push two frames onto the stack. The first frame holds the contents of registers 0-15; the second holds the contents of registers 16-31.
Restore all of the PMC registers from the most recently pushed PMC
register frames. Since the register frames hold only 16 registers, we
pop two frames. We use the first frame to restore registers 16-31, and
the second frame to restore registers 0-15. Hence, pushp followed by
popp restores all of the PMC registers to their original state.
Pop a single PMC register frame off the PMC register frame stack and use it to restore the values of registers 16-31. Registers 0-15 retain their old values.
Pop a single PMC register frame off the PMC register frame stack and use it to restore the values of registers 0-15. Registers 16-31 retain their old values.
The same as pushp, for the integer register set.
The same as popp, for the integer register set.
The same as poptopp, for the integer register set.
The same as popbottomp, for the integer register set.
The same as pushp, for the string register set.
The same as popp, for the string register set.
The same as poptopp, for the string register set.
The same as popbottomp, for the string register set.
The same as pushp, for the floating-point register set.
The same as popp, for the floating-point register set.
The same as poptopp, for the floating-point register set.
The same as popbottomp, for the floating-point register set.
Clean out the current set of PMC registers, setting them to NULL
Clean out the current set of I registers, setting them to 0
Clean out the current set of S registers, setting them to NULL
Clean out the current set of N registers, setting them to 0
Set register X to a null value; for S and P registers, this will be NULL, while for I and N registers it is 0
Push register or constant X onto the generic stack
Restore register X from the generic stack by popping off the topmost entry. The type of this entry must match the register type.
Save all of the current set of registers onto the appropriate frame stacks. Equivalent to performing a separate push for each register type.
Restore all of the registers from the appropriate frame stacks. Equivalent to performing a separate pop for each register type.
As saveall but only acts on registers 16-31.
As restoreall but only affects registers 16-31.
Sets a named marker for the stacks for later use.
Put the type of generic stack entry Y into integer register X
Get the current depth of the generic stack
Fetch the entry that's at position Y from the top of the generic stack. This does not remove an entry from the stack, merely fetches the entry off it.
0 is the entry at the top of the stack, 1 is the entry immediately previous to that, and so on. Entry -1 is the very bottom-most entry in the stack. (While the stack may be a tree when looked at from the bottom up, you don't have access to any other branches when looking this way).
Reset the current register stacks to the state they were in when the warp was set. Resets only the frame pointers, doesn't guarantee the contents of the registers. Be very careful modifying the frame pointers by, for example, pushing register frames.
If a name is passed, warp back to the named point.
Reset the current register stacks to the state they were in before the last warp.
These operations are responsible for finding names in lexical or global scopes, as well as storing data into those slots. A static scope is captured by a scratchpad. The current dynamic scope is represented by the state of the lexical stack (which contains scratchpads). For more detail on these ops see the inline POD documentation in ops/var.ops.
Instructions for creating scratchpads and manipulating the lexical stack.
Instructions for storing in, and retrieving from the scratchpad currently at the top of the lexical stack. For each of these operations there is an equivalent form that uses keyed versions of the set instruction. The keyed variants require that a scratchpad be specified rather than implicitly operating on the scratchpad on the top of the stack.
Find the PMC for the global variable sy from the table sz and store it in register X
Find the PMC for the global in the default table and put it in X.
Find the global symbol table Y and store its PMC in X
Find the slot in the global table Y for the global named Z, and store its slot in register X.
Fetch the global in slot Z of the symbol table pointed to by Y
Store X in the default global symbol table with a name of Y.
These opcodes deal with exception handling at the lowest level. Exception handlers are dynamically scoped, and any exception handler set in a scope will be removed when that scope is exited.
Sets an exception handler in place. The code referred to by register Px will get called if an exception is thrown while the exception handler is in scope.
Clear out the most recently placed exception
Throw an exception represented by the object in PMC register x.
Only valid inside an exception handler. Rethrow the exception represented by the object in PMC register x. This object may have been altered by the exception handler.
These opcodes deal with PMCs as objects, rather than as opaque data items.
Make the variable in PMC x an object of type ty. The type can be a string, in which case we treat it as a package name.
Find the method Z for object Y, and return a PMC for it in X.
Sets X to TRUE if object Y can perform method Z; otherwise, X is set to FALSE.
Sets X to TRUE if object Y can implements interface Z; otherwise, X is set to FALSE.
These opcodes deal with loading in bytecode or executable code libraries, and fetching info about those libraries. This is all dealing with precompiled bytecode or shared libraries.
Load in the bytecode in file X. Search the library path if need be.
Load in the opcode library X, starting at opcode number Y. Search the path if needed.
Load in the string handling library named X
Return the number of opcodes in opcode library X
Get the name of the string encoding that the library X handles
Find the string library that handles strings of type Y. Return its name in X.
Reads and writes read and write records, for some value of record.
Create a new filehandle px
Open the file Y on filehandle X
Issue a read on the filehandle in y, and put the result in PMC X. PMC Z is the sync object.
Write the string Y to filehandle X. PMC Z is the sync object.
Wait for the I/O operation represented by sync object X to finish
Read from filehandle Y and put the results in PMC X. Blocks until the read completes.
Write string Y to filehandle X, waiting for the write to complete.
Seek filehandle X to position Y.
Return the current position of filehandle Y and put it in X. Returns -1 for filehandles where this can't be determined. (Such as stream connections)
Get informational item Z for filehandle Y and put the result in X. This fetches things like the number of entries in the IO pipe, number of outstanding I/O ops, number of ops on the filehandle, and so forth.
Take out a high-level lock on the PMC in register X
Unlock the PMC in register X
Push an unlock request on the stack
Create a new interpreter in X, using the passed flags.
Jump into interpreter X and run the code starting at offset Y from the current location. (This is temporary until we get something better)
Call routine Y in interpreter x, passing it the list of parameters Z. W is a synchronization object returned. It can be waited on like the sync objects returned from async I/O routines.
Get information item Y and put it in register X. Currently defined are:
The total amount of system memory allocated for later parceling out to Buffers. Doesn't include any housekeeping memory, memory for Buffer or PMC structs, or things of that nature.
The total number of dead object detection runs that have been made.
The total number of memory collection runs that have been made.
The number of PMCs considered active. This means the DOD scan hasn't noted them as dead.
The number of Buffers (usually STRINGs but could be other things) considered active.
The total number of PMCs the interpreter has available. Includes both active and free PMCs
The total number of Buffer structs the interpreter has available.
The number of new Buffer header block allocations that have been made since the last DOD run. (Buffers, when allocated, are allocated in chunks)
The number of times we've requested a block of memory from the system for allocation to Buffers since the last time we compacted the memory heap.
Fire off a dead object sweep
Fire off a garbage collection sweep
Pause the garbage collector. No collections will be done for this interpreter until the collector is unpaused.
Unpause the collector. This doesn't necessarily do a GC run, merely allows the interpreter to fire one off when it deems it necessary.
Keys are used to get access to individual elements of an aggregate variable. This is done to allow for opaque, packed, and multidimensional aggregate types.
A key entry may be an integer, string, or PMC. Integers are used for array lookups, strings for hash lookups, and PMCs for either.
Create a new key structure and put a pointer to it in register X.
Make a copy of the key Y and put a pointer to it in register X. Y may be either an S register or a constant.
Make the key structure X large enough to hold Y key entries
Put the number of elements in key Y into integer register X.
Nuke key X. Throws the structure away and invalidates the register.
Put the type of key Y's entry Z in register X. Current values are 0, 1, and 2 for Integer, String, and PMC, respectively.
Put the value from key Y, entry Z into register X.
Toss the topmost entry from key X.
Increment entry Y of key X by one.
Set key W, offset Y, to value X. If X is a PMC, then the fourth operand must be specified. It can have a value of 0, 1, or 2, corresponding to integer, string, or object. Aggregates use this to figure out how to treat the key entry.
Properties are a sort of runtime note attached to a PMC. Any PMC can have properties on it. Properties live in a flat namespace, and they are not in any way associated with the class of the PMC that they are attached to.
Properties may be used for runtime notes on variables, or other metadata that may change. They are not for object attributes.
Set the property named Y of PMC X to the PMC in Z
Get the property named Y from PMC Z and put the result in register X. Returns a NULL if the property doesn't exist.
Delete the property Y from PMC X
Fetch the properties from Y, put them in a Hash, and put the Hash in X.
Sets the 'current line' marker.
Sets the 'current file' marker.
Sets the 'current package' marker.
Fetches the 'current line' marker.
Fetches the 'current file' marker.
Fetches the 'current package' marker.
These are the ops we use to load in and interface to non-parrot libraries.
Load in the library whose name is specified by y, and put a handle to it into P register x.
Find a routine named Y, in library X (which you did, of course, open with loadlib), and put a sub PMC onto W for it. You can call this sub as if it were any other parrot subroutine.
Z has the function signature, which tells Parrot how to build the interface from parrot (and parrot's calling conventions) to the calling conventions of the library routine. Yes, this does mean that you must know the function signature, but if you don't know that why the heck would you be invoking the function, right?
The signature is a series of 1 or more characters, representing the types for the call. The first character is the return type, while the rest are the parameters. The types are:
So the signature for, for example, this SDL routine:
int SDL_BlitSurface(SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect);
would be ipppp, since it returns an integer and takes four
pointers. Presumably previous calls would have set those pointers up
properly.
Do note that parrot makes no guarantees as to the behaviour of the libraries, and currently does no type checking on the input parameters. We will fix that later.
The generated routine follows the calling conventions in PDD03. Note
that int, string, pmc, and float parameters are counted
separately. So if you have a signature of ippiidd the return goes
into I5, and the parameters come from P5, P6, I5, I6, N5, and N6,
respectively. A signature of ipdiidp has the identical same set of
registers used (and in the same order).
Invoke a subroutine in P0. Presumes that all the registers are set up right for the call. The invoked subroutine must preserve any registers that are not explicitly return parameters or calling convention metadata parameters. (Such as the number of I reg parameters, for example)
These opcodes deal with runtime creation of bytecode and compilation of source code.
Compile source string Z, with compiler unit Y, and stick a handle to a subroutine for the resulting bytecode segment (already loaded into the current interpreter) into X.
Y is a assembler/compiler object of some sort, as registered with the compreg opcode or the Parrot_compreg function. This will be something like "Perl5", "Perl6", "Perl5RE", "Perl6RE", "Python", "Ruby"... you get the picture.
Parrot knows of a "PASM1" compiler, i.e. a one statement PASM compiler implemented as PDB_eval. Imcc registers "PASM" and "PIR" compilers.
This is a high-level op, with the assumption that the resulting sub will be called. It's the equivalent of perl 5's string eval, except for the actual execution of the resulting code.
Get a compiler for source type Y.
Register the sub Y as a parser/compiler function named X. It will be called whenever anyone invokes the compile op with the name X.
None.
None.
None.
Maintainer: Dan Sugalski
Class: Internals
PDD Number: 6
Version: 1.8
Status: Developing
Last Modified: 02 December 2002
PDD Format: 1
Language: English
December 11, 2002
December 02, 2002
November 05, 2001
October 12, 2001
September 24, 2001
September 12, 2001
August 25, 2001
August 8, 2001
None. First version
We have an interpreter now! Yay! (Okay, a simple one, but still...) Changes made to reflect that.
None. First version