Parrot assembly language
Maintainer: Dan Sugalski Class: Internals PDD Number: 6 Version: 1.6 Status: Developing Last Modified: 05 November 2001 PDD Format: 1 Language:English
November 05, 2001
October 12, 2001
September 24, 2001
September 12, 2001
August 25, 2001
August 8, 2001
None. First version
Added GC opcodes
Now have a bsr in addition to a jsr
return is now ret
Added save and restore ops for saving and restoring individual registers
Conditional branches have just a true destination now
Added the I/O ops
Added in the threading ops
Added in the interpreter ops
Added in the low-level module loading ops
Added in transcendental functions and modulo
Finished the pad/global variable fetching bits
We have an interpreter now! Yay! (Okay, a simple one, but still...) Changes made to reflect that.
Added in object
Changed remnants of "perl" to "Parrot"
Branch destination may be integer constant
Added "Assembly Syntax" section
This PDD describes the format of Parrot's bytecode assembly language.
Parrot's'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 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.
String and integer constants don't need to be put in a separate
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. (Px, Sx, Ix, or Nx) If true, 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.
Copy the value of ty into tx, making appropriate conversions.
The following cases provide exceptions to this rule:
Copies the pmc pointer in Py into Px, both registers now refer to the same pmc. Use clone to copy pmc contents.
Performs a "deeper" copy of Py into Px, using the vtable appropriate to the class of Py.
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 frame of PMC registers onto their stack and start a new frame. The new registers are not initialized.
Push the current frame of PMC registers onto their stack and start a new frame. The new registers are copies of the previous frame.
Pop the current frame of PMC registers off the stack.
The same as push_p, for the integer register set.
The same as push_p_c, for the integer register set.
The same as pop_p, for the integer register set.
The same as push_p, for the string register set.
The same as push_p_c, for the string register set.
The same as pop_p, for the string register set.
The same as push_p, for the floating-point register set.
The same as push_p_c, for the floating-point register set.
The same as pop_p, for the floating-point register set.
Push register X onto the generic stack
Restore register X from the generic stack
Put the type of stack entry Y into integer register X
Sets a named marker for the stacks for later use.
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 and checking constraints on those slots. They also allocate and deallocate scratchpads and entries in those pads.
Pad descriptors are templates for a particular pad. They are specified in the constant area of a bytecode file, and contain the names, types, and attributes for the variables referenced in the scope the pad is for.
The pad 0 is special, and represents the empty pad.
Find the lexical of name sy and store the PMC pointer in register Px.
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 lexical in slot y of scratchpad z. If z is negative, search out from the current pad, if positive search inwards from the outermost pad. Put the resulting PMC pointer 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.
Create a new scratchpad using pad_descriptor as a template.
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.
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 filehndle 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.
lock Px
Take out a high-level lock on the PMC in register X
unlock Px
Unlock the PMC in register X
pushunlock Px
Push an unlock request on the stack
newinterp Px, flags
Create a new interpreter in X, using the passed flags.
runinterp Px, iy
Jump into interpreter X and run the code starting at offset Y from the current location. (This is temporary until we get something better)
callout Pw, Px, sy, pz
Call routine Y in interpreter x, passing it the list of parameters Z. V is a synchronization object returned. It can be waited on like the sync objects returned from async I/O routines.
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.
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.
To install Make, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Make
CPAN shell
perl -MCPAN -e shell install Make
For more information on module installation, please visit the detailed CPAN module installation guide.