spinix-hive/manpages/spasm.txt

352 lines
15 KiB
Plaintext
Raw Normal View History

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><size><type><mode>
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)