SPASM(1) User Commands SPASM(1) NAME spasm - spin assembler SYNOPSIS spasm [-l] [-d] FILE DESCRIPTION Spasm assembles the source file given by FILE. The file name may include the extension, or .spa will be assumed if no extension is specified. The assembled binary program will written to a file with the same root name plus a .bin extension. If -l is specified, it will print an assembly listing. If -d is specified, spasm will print debug information. Spasm is an assembly language that defines mnemonics for Spin bytecodes. Spin bytecodes are executed by the Spin interpreter, which is loaded at boot time from the internal ROM. The Spin interpreter is a stack-based virtual machine that uses the stack to store parameters that are used by operators, such as add, sub, etc. The operators store their results back onto the stack. There are other operators that transfer data back and forth between the stack and hub RAM. The Spin bytecodes are listed below. They are separated into four major groups -- lower, memory, math and extened operators. The lower group contains a mix of operators, including those that handle program flow, lookup, lookdown, case, and several other miscellaneous functions. The math operators implement the various math and logic functions that use two arguments. The memory operators implement load, store, execute and address functions. A load operation reads data from the hub RAM and pushes it onto the stack. A store operation pops a value off the stack and stores it in RAM. The address operator is used to push the absolute address of a hub RAM location onto the stack. The execute operation is used to execute an operation directly on a RAM location. The result can be optionally pushed to the stack. The operations that can be executed directly on a hub RAM location include the standard 32 math operations plus a small number of extended operations. The extended operators include pre and post increment and decrement, sign extension and the random function. The format of the memory mnemonics is as follows: operation = {ld, st, ex, la}, size = {b, w, l}, type = {i, l, o, a, v, s} mode = {c, x, 0, 1, m1, p} The operations are load, store, execute and load address as stated earlier. The size refers to byte, word and long. The types are immediate, local, object, absolute, variable and stack. The modes are compact, indexed, zero, one, minus one and packed. As an example, the instruction ldwi means load-word-immediate. It will load an immediate value onto the stack. The instruction stba will store a byte at the absolute address residing in the stack. There are compact instructions that use a single byte to address the first 8 long values residing in the method's stack frame or in an object's variable space. These use the size, type and mode characters "llc". As an example, the method result value can be set with the "stllc 0" instruction. The fourth long in the objet's variable section could be loaded with "ldllc 12". When an execute memory operation is specified it is followed by one of the math operators or an extended operator. An execute instruction may also specify the "load" extended operator to save the result on the stack. Examples of using execute instructions are as follows: exlo $8 add ' Add value on stack to the object long at offset $8 exwv $20 preinc ' Increment the VAR word at offset $20 exll $10 postdec load ' Decrement stack location $10 and load Spasm also includes psuedo-ops, which are shortened versions of the memory mnenomics. The psuedo-ops are made up only of the operation and size fields, plus the "x" charater if it is indexed. The psuedo-ops are mapped to explicit opcodes depending on the context of the operand. As an example "ldl 1" maps into "ldli1", and "ldl result" maps into "ldllc 0". The Spasm opcodes are listed below. The offsets used for the jump instructions are signed offsets that are relative to the address of the next instruction. A "jmp 0" instruction will just execute the next instruction. Signed offsets are encoded in either one or two bytes depending on the value of the most significant bit in the first byte. If the MSB is zero the remaining seven bits are treated as a signed 7-bit number in the range from -64 to 63. If the MSB is non-zero, the remaining seven bits are used as the most significant bits of a 15-bit signed number, and the next byte provides the eight least sigficant bits. The 15-bit signed offset has a range from -16384 to 16383. The memory opcodes use an unsigned offset that can also be encoded in one or two bytes. The MSB is used to determine whether it is one or two bytes just like for signed offset. However, since it is unsigned, the range for the one-byte offset is 0 to 128, and for two bytes it is 0 to 32768. Lower Opcodes ------------- 00 ldfrmr - Load call frame with return value required 01 ldfrm - Load call frame 02 ldfrmar - Load call frame with abort trap & return value 03 ldfrma - Load call frame with abort trap 04 jmp offset - Jump to signed object offset 05 call meth - Call method 06 callobj meth, obj - Call method in object 07 callobjx meth, obj - Call method in object with index 08 tjz offset - Test and jump if zero 09 djnz offset - Decrement and jump if not zero 0a jz offset - Jump if zero 0b jnz offset - Jump if not zero 0c casedone - Case done without a match 0d casevalue - Execute if value matches case value 0e caserange - Execute if case value within range 0f lookdone - Look up/down done without a match 10 lookupval - 11 lookdnval 12 lookuprng 13 lookdnrng 14 pop - Discard N bytes from the stack 15 run - Prepare new spin cog stack for execution 16 strsize - Determine the size of a string 17 strcomp - Compare two strings 18 bytefill - Fill memory with a constant byte value 19 wordfill - Fill memory with a constant word value 1a longfill - Fill memory with a constant long value 1b waitpeq - Wait till pins are equal to a value 1c bytemove - Copy bytes to a new location 1d wordmove - Copy words to a new location 1e longmove - Copy longs to a new location 1f waitpne - Wait till pins are not equal to value 20 clkset - Change the clock frequency and mode 21 cogstop - Stop the specified cog 22 lockret - Return a lock 23 waitcnt - Wait for cnt to equal a specified value 24 ldlsx 25 stlsx 26 exlsx 27 waitvid - Wait on video 28 coginitret - Start a cog and return the cog number 29 locknewret - Allocate a lock and return the lock number 2a locksetret - Set a lock and return the previous value 2b lockclrret - Clear a lock and return the previous value 2c coginit - Start a cog 2d locknew - Allocate a lock with no return value 2e lockset - Set a lock with no return value 2f lockclr - Clear a lock with no return value 30 abort - Perform an abort to the next abort trap 31 abortval - Perform an abort and return a value 32 ret - Return without loading a return value 33 retval - Return and load a return value on the stack 34 ldlim1 - Load a minus 1 35 ldli0 - Load zero 36 ldli1 - Load 1 37 ldlip value - Load a packed-byte constant 38 ldbi value - Load a single-byte constant 39 ldwi value - Load a two-byte constant 3a ldmi value - Load a three-byte constant 3b ldli value - Load a four-byte constant 3c --- - Unused opcode 3d ldregbit - Load a bit from a register 3d stregbit - Store a bit to a register 3e ldregbits - Load bits from a register 3e stregbits - Store bit to a register 3f ldreg - Load a register 3f streg - Store a register Compact Memory Opcodes -------------- 40 ldlvc offset - Load long variable compact 41 stlvc offset - Store long variable compact 42 exlvc offset - Execute on a long variable compact 43 lalvc offset - Load address of a long variable compact 60 ldllc offset - Load long local compact 61 stllc offset - Store long local compact 62 exllc offset - Execute on a long local compact 63 lallc offset - Load address of a long local compact Byte Memory Opcodes -------------- 80 ldba - Load byte absolute 81 stba - Store byte absolute 82 exba - Execute on a byte absolute 83 laba - Load address of a byte absolute 84 ldbo offset - Load byte object offset 85 stbo offset 86 exbo offset 87 labo offset 88 ldbv offset - Load byte variable offset 89 stbv offset 8a exbv offset 8b labv offset 8c ldbl offset - Load byte local offset 8d stbl offset 8e exbl offset 8f labl offset 90 ldbax - Load byte absolute with index 91 stbax 92 exbax 93 labax 94 ldbox offset - Load byte object offset with index 95 stbox offset 96 exbox offset 97 labox offset 98 ldbvx offset - Load byte variable offset with index 99 stbvx offset 9a exbvx offset 9b labvx offset 9c ldblx offset - Load byte local offset with index 9d stblx offset 9e exblx offset 9f lablx offset Word Memory Opcodes ------------------- a0 ldwa - Load word absolute a1 stwa a2 exwa a3 lawa a4 ldwo offset a5 stwo offset a6 exwo offset a7 lawo offset a8 ldwv offset a9 stwv offset aa exwv offset ab lawv offset ac ldwl offset ad stwl offset ae exwl offset af lawl offset b0 ldwax - Load word absolute with index b1 stwax b2 exwax b3 lawax b4 ldwox offset b5 stwox offset b6 exwox offset b7 lawox offset b8 ldwvx offset b9 stwvx offset ba exwvx offset bb lawvx offset bc ldwlx offset bd stwlx offset be exwlx offset bf lawlx offset Long Memory Opcodes ------------------- c0 ldla - Load long absolute c1 stla c2 exla c3 lala c4 ldlo offset c5 stlo offset c6 exlo offset c7 lalo offset c8 ldlv offset c9 stlv offset ca exlv offset cb lalv offset cc ldll offset cd stll offset ce exll offset cf lall offset d0 ldlax - Load long absolute with index d1 stlax d2 exlax d3 lalax d4 ldlox offset d5 stlox offset d6 exlox offset d7 lalox offset d8 ldlvx offset d9 stlvx offset da exlvx offset db lalvx offset dc ldllx offset dd stllx offset de exllx offset df lallx offset Math Opcodes ------------ e0 ror - Rotate right e1 rol - Rotate left e2 shr - Shift right e3 shl - Shift left e4 min - Maximum e5 max - Minimum e6 neg - Negate e7 com - Compliment e8 and - Bitwise and e9 abs - Absolute value ea or - Bitwise or eb xor - Bitwise exclusive or ec add - Add ed sub - Subtract ee sar - Shift arithmetic right ef rev - Bit reverse f0 andl - Logical and f1 encode - Shift "1" left f2 orl - Logical or f3 decode - Find left-most "1" bit f4 mul - Multiply f5 mulh - Multiply high f6 div - Divide f7 mod - Modulus f8 sqrt - Square root f9 cmplt - Less than fa cmpgt - Greater than fb cmpne - Not equal fc cmpeq - Equal fd cmple - Less than or equal fe cmpge - Greater than or equal ff notl - Logical not Extended opcodes ---------------- 00 load - Load the value 02 repeat - Repeat index from first to last 06 repeats - Repeat index from first to last with step 08 randf - Forward random number 0c randr - Reverse random number 10 sexb - Sign extend byte 14 sexw - Sign extend word 18 postclr - Post clear to zero 1c postset - Post set to all ones 26 preinc - Pre-increment 2e postinc - Post-increment 36 predec - Pre-decrement 3e postdec - Post-decrement AUTHOR Dave Hein COPYRIGHT Copyright (c) 2011, 2012 Dave Hein MIT License (See license.txt in the root directory) This is free software: you are free to change and redistribute it. There is no warranty, to the extent permitted by law. SPASM March 2012 SPASM(1)