Assembler and Disassembler

The Mops' PowerPC assembler and disassembler were originally written by Xan Gregg for Power MacForth. They've been adapted for use in the Mops environment as modules. The source files are "pasmMod.txt" and "disasm". The syntax is traditional Forth postfix-style.

Assembler colon definitions

You write a code definition thus:

`:ppc_code  someName`\
` </nowiki><var><ppc instructions></var><nowiki>`\

This will create a normal header for someName in the dictionary, then align the CDP to a 4-byte boundary (as required for PowerPC code), and compile the code. Note that if you tick someName, the resulting xt on the stack will be the address of the first instruction, minus 2. The extra 2 bytes are used internally (by Mops) as flags. Remember to add 2 if you need the actual address of the first instruction. If, however, you use EXECUTE, you pass the xt in the normal way.

We don't provide a full rundown of the assembly syntax here; however the comments in the source files are fairly extensive. So if you're the type of person who might want to write assembly language, you'll probably be able to figure out what to do! �especially as the file "test pasm" in the 'Module Source' folder has a definition containing all the PowerPC instructions supported by the assembler. Remember that it's a Forth-style postfix assembler. We also give a short example at the end of this section, and there are a number of code definitions in the source files in 'PPC source', especially the file "setup".

We don't provide any way of writing a method with the assembler. This should never be necessary for performance, and if you really need access to machine-level features, you can write a :ppc\_code word and call it from your method.

Accessing the dictionary

If you need to get the address of an item in the code or data area of the dictionary, you can do it with this syntax:

r0 ' <var>someWord</var> <var>dicaddr,</var>

This generates an addi instruction, using the appropriate base register and offset to place the address of the location you want into a register. We used r0 in this example, but you could have used any free register. For a location in the data area, remember that ticking the name of the item won't get you there�you have to do something like this:

r0 ' <var>myValue</var> >body <var>dicaddr,</var>

You can execute any code you like between naming the register and putting dicaddr,. You are in execution mode, and can execute any Mops words, so long as you leave just one item on the stack. One proviso is that at the moment, the target address must be within 32k bytes distance from where the base register points, as otherwise the address can't be generated with a single addi instruction. If the assembler gives you an out-of-range error on a line with dicaddr, this is probably the reason.

Executing colon definitions from code

In a word, don't. Mops colon definitions will expect various numbers of their parameters in registers when they're called, and the algorithm for working this out is quite complex (and might even change!). So you should really only use code definitions for words that don't call any other words.

Executing other code definitions from code

There's no problem with doing this, since you have full control of the registers. Remembering that the first instruction of a code definition starts two bytes after where the xt points, you call another code definition this way:

' <var>someWord</var> 2+ bl,

The Assembler automatically converts the absolute address of the first instruction of someWord, which we generate with 'someWord 2+', to the offset that is required by the bl instruction.

Assembler source

The assembler-related source files are all in the 'Module source' folder. They are:

pasmMod.txt the assembler disasm the disassembler (loaded by "pasmMod.txt") test pasm a big test definition with all the PPC instructions vectors pasm test another big test definition with all the AltiVec instructions

On entry to a code definition, the top-of-stack item is in register r4, the second item is in r3, and the next stack item is in memory, pointed to by the data stack pointer, r18. You can do whatever you like with the stack (within reason), but on exit from your definition you must observe this same convention.

Within the definition, you can use registers r5-12 freely for whatever you like without having to save or restore them. You can also use r23-31, but as Mops uses these for locals, they might contain values in use by the calling code. So you will need to save and restore any of these that you use.

The same applies to the floating point stack. On entry to a code definition, the top-of-stack item is in register fr2, the second item is in fr1, and the next stack item is in memory, pointed to by the FP stack pointer, r19. You can use fr0 and fr3-13 without saving or restoring them. fr14-31 are used for FP locals, so you can use them if you save and restore them.

PowerPC register usage

Here's a summary of the register usage in the PowerMops runtime environment:

                      `r0`                                            scratch

r1 system stack pointer (leave it alone, normally)
r2 RTOC (Table Of Contents pointer -- leave alone)
r3 initially, second stack cell
r4 initially, top stack cell
r5 scratch
r6 scratch
r7 scratch
r8 scratch
r9 scratch
r10 scratch
r11 scratch, also used in system calls
r12 ditto
r13 base address of main dic code area
r14 base address of main dic data area
r15 base address of current module's code area
r16 base address of current module's data area
r17 return stack pointer (points to top cell)
r18 data stack pointer (points to top memory cell)
r19 floating point stack pointer (points to top memory cell)
r20 base address of current object
r21 loop counter I
r22 limit value for DO...LOOP
r23 can use if you save and restore
r24 ditto
r25 ditto
r26 ditto
r27 ditto
r28 ditto
r29 ditto
r30 ditto
r31 ditto
fr0 scratch
fr1 initially, second stack cell
fr2 initially, top stack cell
fr3 scratch
fr4 scratch
fr5 scratch
fr6 scratch
fr7 scratch
fr8 scratch
fr9 scratch
fr10 scratch
fr11 scratch
fr12 scratch
fr13 scratch
fr14 can use if you save and restore
fr15 ditto
fr16 ditto
fr17 ditto
fr18 ditto
fr19 ditto
fr20 ditto
fr21 ditto
fr22 ditto
fr23 ditto
fr24 ditto
fr25 ditto
fr26 ditto
fr27 ditto
fr28 ditto
fr29 ditto
fr30 ditto
fr31 ditto


Finally, here's a short example, from the file "pnuc1" (in 'PPC source'). This is the definition of PICK.

`:ppc_code PICK`\
` r4 0 cmpi, \is it 0 pick?`\
` eq if,`\
` r4 r3 r3 or, \yes - copy TOS`\
` else,`\
` r5 r4 2 0 29 rlwinm, \no- mult index by 4 by left shift`\
` r5 r5 -4 addi, \and subtract 4 to get SP offset`\
` r4 r18 r5 lwzx, \grab the cell`\
` then,`\
` blr, \and return.`\

Note that PICK doesn't push or pop from the data stack, but simply replaces the top cell (in r4) with the stack cell that it fetches. Also, since it doesn't call any other routine, there's no need to save and restore the return address which is in the link register on entry. If we had needed to save and restore the link register, we would have put the instructions

r0 mflr, \save lr on return stack
r0 -4 rRP stwu,

at the beginning, and

r0 mtlr, \restore lr

at the end before the blr,.

Note also that we need to special-case the '0 pick' case, since the desired cell isn't in the memory part of the stack, but is already in r3.

For an example of a much longer code definition, have a look at (EX) in the file "setup" (in 'PPC source').

Warning: If you are already familiar with the old 68k Mops Assembler, note that you must write instructions at the end of your code routine so that it will return. The PowerPC Assembler doesn't do this for you, since it can't always know where your return address is. (It might not necessarily be in the link register at that point�you might have put it in the count register or have saved it on the return stack or somewhere else.)


The disassembler will disassemble PowerPC code from a range of addresses you specify, dumping its output to the Mops window.

You call the disassembler with one of the following words:

disasm\_word someWord Disassembles the word someWord. disasm\_xt ( xt \-- ) Disassembles the word with the given xt. disasm\_rng ( from to \-- ) Disassembles within the given address range. disasm\_cnt class="STACK" nowrap | ( from \#inst \-- ) Starts at 'from', disassembles the given number of instructions. disasm ( from \-- ) Starts at 'from', keeps going till you hit a key or until a blr instruction is seen (which normally comes at the end of a definition).