initial

src/Help/prev-ssmhelp.prop

+cc=A Condition Code (CC) encodes a result of a comparison. Four bits are used to encode the fact that the result of a cmp instruction is zero (Z), negative (N), a carry was needed (C) or overflow was detected (V).
conditioncode=@cc

sr=SR stands for Status Register. The status, called SR (status register) is not a real register but just an interpretation of the top of the stack. The top of the stack is used to store the condition codes resulting after a compare. Four bits, Z, N, C and V of the SR are used to encode the comparison result being zero, negative, carried and overflowed. These bits are only used by branches on conditions (i.e. beq).
statusbits=See SR.

prepostcondition=A kind of pre and postcondition is used to denote the effect of instructions. Behaviour is expressed using equations relating the state of the machine before (pre) execution of an instruction to the state after (post). Values of memory (M), registers (PC,SP,MP,RR) are subscripted with 'pre' resp 'post' to refer to the respective values before/after execution. No equation for a value means that the pre and post values are equal.
\ No newline at end of file

src/Help/prev-ssminstrhelp.prop

+cmp_descr=Compare. Replaces 2 top stack values with the status of the comparison of those values. The status is put in SR. See also brf.
cmp_prepost=SP_post = SP_pre - 1, M_post[SP_post] = status(M_pre[SP_pre - 1] - M[SP_pre])
cmp_example=ldl -2 ; if x /= 1 then x = 1, ldc 1, cmp, beq skipLabel, ldc 1, stl -2, skipLabel: ...

beq_descr=Branch on condition. Notation bcc, where the cc in bcc can be eq (equal), ne (not equal), lt (less than), gt (greater than), le (less or equal) or ge (greater or equal). And some others not used often: pl (plus), mi (minus), cc (carry clear), cs (carry set), hi (high), ls (low or same).
beq_prepost=SP_post = SP_pre - 1, PC_post = PC_pre + M_pre[PC_pre + 1] + 2 (if condition matches)
beq_example=@cmp_example

bne_descr=@beq_descr
bne_prepost=@beq_prepost
bne_example=@beq_example

blt_descr=@beq_descr
blt_prepost=@beq_prepost
blt_example=@beq_example

ble_descr=@beq_descr
ble_prepost=@beq_prepost
ble_example=@beq_example

bgt_descr=@beq_descr
bgt_prepost=@beq_prepost
bgt_example=@beq_example

bge_descr=@beq_descr
bge_prepost=@beq_prepost
bge_example=@beq_example
\ No newline at end of file

src/Help/ssmhelp.prop

+# General help info for Simple Stack Machine

registers=Eight registers are available, some of which have a specific purpose. A register is private location in a processor, often faster accessible then external memory. Currently the Program Counter (PC), Stack Pointer (SP), Mark Pointer (MP) and Return Register (RR) as well as freely usable scratch registers are available, respectively identified by numbers 0..7. Registers are identified by the name R<x>, where <x> is the register number. Register with a specific purpose are also named with the name indicating their purpose.

PC=The Program Counter (PC) is used to remember what the current next instruction is. It contains the address (i.e. points to) the location of the next instruction. The machine fetches an instruction from the location pointed to by the PC. After each fetch it is automatically updated to point to the next instruction.
programcounter=@PC

SP=The Stack Pointer (SP) is used to push and pop values for usage in expression evaluation. The Stack is also used to store variables. These are often accessed via the MP.
stackpointer=@SP

MP=The Mark Pointer (MP) is used to access local variables, allocated on the stack. Each variable is accessed using a displacement relative to the MP.
markpointer=@MP

RR=The Return Register (RR) is used to return a value without placing it on a stack. Strictly seen this is not necessary but a convenience, since values also can be passed via the stack.
return register=@RR

instruction=An instruction is an encoding of some operation, executed in the machine. A set of instructions stored in memory is called the code. Some instructions have inline operands, that is, after their location in the code an extra operand is stored, a constant, e.g. in "ldc 1". In pre/post conditions this location is indicated by M[PCpre+1] since it can be found on that location. The behavior of an instruction is both informally described as well as using pre/postcondifitions.

memory=Memory stores words. A word is an 32 bits integer. Currently only a limited amount of memory words is reserver (2000), this is rather arbitrary, in the future memory size will adapt automatically to the amount needed.

stack=Stack is the part of memory used to store values needed for evaluating expressions. The stack is located after the code and grows from lower addresses to higher ones.

code=Code is the part of memory used to store instructions. It starts at address 0.

help=The Simple Stack Runner executes instructions for a hypothetical (and thus simple) machine. See memory, registers, syntax, instruction as starting points for help.

syntax=Syntax of instructions (as loaded from file) is: (label:)? (instr arg*)?. In other words, an (optional) instruction preceded by an (optional) label and followed by an argument if required. Comment may start with ";" or "//" (Java/C++ style) and ends at the end of the line. This characters are interpreted as start of comment. A label may be used as an argument. Example: "l1: beq l1 ; comment".

labels=A label is an identifier indicating a position in the code. When loading, the code location of a label is calculated (called resolution). This is done in the user interface of the program and after loading labels are not kept consistent (when adding new instructions for example).

False=Value False is encoded by a 0.

True=Value True is encoded by a -1 (all 1 bit pattern 0xFFFFFFFF). However, when testing in the context of a BRF instruction takes place, anything else than 0 is considered to be True.
\ No newline at end of file

src/Help/ssminstrhelp.prop

+# Instruction help info for Simple Stack Machine

ldc_descr=Load Constant. Pushes the inline constant on the stack.
ldc_prepost=SP_post = SP_pre + 1, M_post[SP_post] = M_pre[PC_pre+1]
ldc_example=@stl_example

lds_descr=Load from Stack. Pushes a value relative to the top of the stack.
lds_prepost=SP_post = SP_pre + 1, M_post[SP_post] = M_pre[SP_pre + M_pre[PC_pre+1]]
lds_example=lds -1 ; multiply and leave on stack, ldc 2, mul

ldms_descr=Load Multiple from Stack. Pushes values relative to the top of the stack. Same as single load variant but second inline parameter is size.
ldms_prepost=displ = M_pre[PC_pre + 1], size = M_pre[PC_pre + 2], SP_post = SP_pre + size, M_post[SP_post - size + 1 .. SP_post] = M_pre[SP_pre + displ .. SP_pre + displ + size - 1]
ldms_example=ldms -1 2; multiply and leave on stack, mul

sts_descr=Store into Stack. Pops a value from the stack and stores it in a location relative to the top of the stack.
sts_prepost=SP_post = SP_pre - 1, M_post[SP_pre + M_pre[PC_pre+1]] = M_pre[SP_pre]
sts_example=lds -1 ; substract and store in stack, ldc 2, sub, sts -2

stms_descr=Store Multiple into Stack. Pops values from the stack and stores it in a location relative to the top of the stack. Same as single store variant but second inline parameter is size.
stms_prepost=displ = M_pre[PC_pre + 1], size = M_pre[PC_pre + 2], SP_post = SP_pre - size, M_post[SP_pre + displ .. SP_pre + displ + size - 1] = M_pre[SP_post + 1 .. SP_post + size]
stms_example=lds -1 ; substract and store in stack, ldc 2, sub, stms -2 1 ; equivalent to sts -2

ldsa_descr=Load Stack Address. Pushes the address of a value relative to the stackpointer.
ldsa_prepost=SP_post = SP_pre + 1, M_post[SP_post] = SP_pre + M_pre[PC_pre+1]
ldsa_example=ldsa -2 ; update value on stack using its address, ldc 5, sta 0

ldl_descr=Load Local. Pushes a value relative to the markpointer.
ldl_prepost=SP_post = SP_pre + 1, M_post[SP_post] = M_pre[MP_pre + M_pre[PC_pre+1]]
ldl_example=ldl -1 ; divide and leave on stack, ldc 3, div

ldml_descr=Load Multiple Local. Pushes values relative to the markpointer. Same as single load variant but second inline parameter is size.
ldml_prepost=displ = M_pre[PC_pre + 1], size = M_pre[PC_pre + 2], SP_post = SP_pre + size, M_post[SP_post - size + 1 .. SP_post] = M_pre[MP_pre + displ .. MP_pre + displ + size - 1]
ldml_example=ldml -1 2 ; divide and leave on stack, ldc 3, div

stl_descr=Store Local. Pops a value from the stack and stores it in a location relative to the markpointer.
stl_prepost=SP_post = SP_pre - 1, M_post[MP_pre + M_pre[PC_pre+1]] = M_pre[SP_pre]
stl_example=ldl 2 ; increment local var, ldc 1, add, stl 2

stml_descr=Store Multiple Local. Pops values from the stack and stores it in a location relative to the markpointer. Same as single store variant but second inline parameter is size.
stml_prepost=displ = M_pre[PC_pre + 1], size = M_pre[PC_pre + 2], SP_post = SP_pre - size, M_post[MP_pre + displ .. MP_pre + displ + size - 1] = M_pre[SP_post + 1 .. SP_post + size]
stml_example=ldl 2 ; increment local var, ldc 1, add, stml 2 1 ; equivalent to stl 2

ldla_descr=Load Local Address. Pushes the address of a value relative to the markpointer.
ldla_prepost=SP_post = SP_pre + 1, M_post[SP_post] = MP_pre + M_pre[PC_pre+1]
ldla_example=ldla -2 ; update local using its address, ldc 5, sta 0

lda_descr=Load via Address. Dereferencing. Pushes the value pointed to by the value at the top of the stack. The pointer value is offset by a constant offset.
lda_prepost=SP_post = SP_pre, M_post[SP_post] = M_pre[M_pre[SP_pre] + M_pre[PC_pre+1]]
lda_example=ldla -2 ; a different way of doing ldl -2, lda 0

ldma_descr=Load Multiple via Address. Pushes values relative to by the value at the top of the stack. Same as single load variant but second inline parameter is size.
ldma_prepost=displ = M_pre[PC_pre + 1], size = M_pre[PC_pre + 2], SP_post = SP_pre + size - 1, M_post[SP_post - size + 1 .. SP_post] = M_pre[M_pre[SP_pre] + displ .. M_pre[SP_pre] + displ + size - 1]
ldma_example=none

ldaa_descr=Load Address of Address. Pushes the address of a value relative to the address on top of the stack. This instruction effectively adds a constant to the top of the stack.
ldaa_prepost=SP_post = SP_pre + 1, M_post[SP_post] = M_pre[SP_pre] + M_pre[PC_pre+1]
ldaa_example=ldaa -2

sta_descr=Store via Address. Pops 2 values from the stack and stores the second popped value in the location pointed to by the first. The pointer value is offset by a constant offset.
sta_prepost=SP_post = SP_pre - 2, M_post[M_pre[SP_pre] + M_pre[PC_pre+1]] = M_pre[SP_pre-1]
sta_example=@ldla_example

stma_descr=Store Multiple via Address. Pops values from the stack and stores it in a location relative to the value at the top of the stack. Same as single store variant but second inline parameter is size.
stma_prepost=displ = M_pre[PC_pre + 1], size = M_pre[PC_pre + 2], SP_post = SP_pre - size - 1, M_post[M_pre[SP_pre] + displ .. M_pre[SP_pre] + displ + size - 1] = M_pre[SP_post + 1 .. SP_post + size]
stma_example=none

ldr_descr=Load Register. Pushes a value from a register. Registers 0, 1, 2 and 3 are called PC (program counter), SP (stack pointer), MP (mark pointer) and RR (return register) respectively.
ldr_prepost=SP_post = SP_pre + 1, M_post[SP_post] = REG_pre[ M_pre[PC_pre+1] ]
ldr_example=ldr RR ; decrement register, ldc 1, sub, str RR

ldrr_descr=Load Register from Register. Copy the content of the second register to the first. Does not affect the stack.
ldrr_prepost=REG_post[ M_pre[PC_pre+1] ] = REG_pre[ M_pre[PC_pre+2] ]
ldrr_example=ldrr SP MP ; SP <- MP

str_descr=Store Register. Pops a value from the stack and stores it in a location relative to the markpointer. See also ldr.
str_prepost=SP_post = SP_pre - 1, REG_post[ M_pre[PC_pre+1] ] = M_pre[SP_pre]
str_example=@ldr_example

swp_descr=Swap values. Swaps the 2 topmost values on the stack.
swp_prepost=SP_post = SP_pre, M_post[SP_post] = M_pre[SP_pre-1], M_post[SP_post-1] = M_pre[SP_pre]
swp_example=ldc 1 ; variant for ldc 2 followed by ldc 1, ldc 2, swp

swpr_descr=Swap Register. Swaps the content of a register with the top of the stack.
swpr_prepost=SP_post = SP_pre, M_post[SP_post] = REG_pre[ M_pre[PC_pre+1] ], REG_post[ M_pre[PC_pre+1] ] = M_pre[SP_pre]
swpr_example=

swprr_descr=Swap 2 Registers. Swaps the content of a register with another register.
swprr_prepost=REG_post[ M_pre[PC_pre+1] ] = REG_pre[ M_pre[PC_pre+2] ], REG_post[ M_pre[PC_pre+2] ] = REG_pre[ M_pre[PC_pre+1] ]
swprr_example=swprr MP R7 ; swap MP with scratch register

ajs_descr=Adjust Stack. Adjusts the stackpointer with fixed amount.
ajs_prepost=SP_post = SP_pre + M_post[PC_pre+1]
ajs_example=ajs -2 ;lower stack by 2

add_descr=Addition. Replaces 2 top stack values with the addition of those values.
add_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] + M_pre[SP_pre]
add_example=@stl_example

mul_descr=Multiplication. Replaces 2 top stack values with the multiplication of those values.
mul_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] * M_pre[SP_pre]
mul_example=@ld_example

sub_descr=Substraction. Replaces 2 top stack values with the subtraction of those values.
sub_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] - M_pre[SP_pre]
sub_example=@st_example

div_descr=Division. Replaces 2 top stack values with the division of those values.
div_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] / M_pre[SP_pre]
div_example=@ldl_example

mod_descr=Division. Replaces 2 top stack values with the modulo of those values.
mod_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] % M_pre[SP_pre]
mod_example=ldl -2 ; x = x % y, ldl -3, mod, stl -2

and_descr=And. Replaces 2 top stack values with the bitwise and of those values.
and_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] & M_pre[SP_pre]
and_example=ldc 0xFF00 ; variant of ldc 0xF000, ldc 0xF0F0, and

or_descr=Or. Replaces 2 top stack values with the bitwise or of those values.
or_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] | M_pre[SP_pre]
or_example=ldc 0xFF00 ; variant of ldc 0xFFFF, ldc 0xF0F0, or

xor_descr=Exclusive Or. Replaces 2 top stack values with the bitwise exclusive or of those values.
xor_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] ^ M_pre[SP_pre]
xor_example=ldc 0xFF00 ; variant of ldc 0x0FF0, ldc 0xF0F0, xor

eq_descr=Test for equal. Replaces 2 top stack values with boolean result of the test. False is encoded as 0, True as 1. Used in combination with brf. This is a variant of cmp combined with beq.
eq_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] == M_pre[SP_pre]
eq_example=ldc 2, ldc 3, eq, brf FalseAction

ne_descr=Test for not equal. Replaces 2 top stack values with boolean result of the test. False is encoded as 0, True as 1. Used in combination with brf. This is a variant of cmp combined with bne.
ne_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] != M_pre[SP_pre]
ne_example=ldc 2, ldc 3, ne, brf FalseAction

lt_descr=Test for less then. Replaces 2 top stack values with boolean result of the test. False is encoded as 0, True as 1. Used in combination with brf. This is a variant of cmp combined with blt.
lt_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] < M_pre[SP_pre]
lt_example=ldc 2, ldc 3, lt, brf FalseAction

le_descr=Test for less or equal. Replaces 2 top stack values with boolean result of the test. False is encoded as 0, True as 1. Used in combination with brf. This is a variant of cmp combined with ble.
le_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] <= M_pre[SP_pre]
le_example=ldc 2, ldc 3, lr, brf FalseAction

gt_descr=Test for greater then. Replaces 2 top stack values with boolean result of the test. False is encoded as 0, True as 1. Used in combination with brf. This is a variant of cmp combined with bgt.
gt_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] > M_pre[SP_pre]
gt_example=ldc 2, ldc 3, gt, brf FalseAction

ge_descr=Test for greater or equal. Replaces 2 top stack values with boolean result of the test. False is encoded as 0, True as 1. Used in combination with brf. This is a variant of cmp combined with bge.
ge_prepost=SP_post = SP_pre - 1, M_post[SP_post] = M_pre[SP_pre - 1] >= M_pre[SP_pre]
ge_example=ldc 2, ldc 3, ge, brf FalseAction

neg_descr=Negation. Replaces top stack values with the (integer) negative of the value.
neg_prepost=SP_post = SP_pre, M_post[SP_post] = - M_pre[SP_pre]
neg_example=ldc 1 ; variant of ldc -1, neg

not_descr=Not. Replaces top stack values with the bitwise complement of the value.
not_prepost=SP_post = SP_pre, M_post[SP_post] = ~ M_pre[SP_pre]
not_example=ldc 0x0000FFFF ; variant of ldc 0xFFFF0000, not

bsr_descr=Branch to subroutine. Pushes the PC on the stack and jumps to the subroutine.
bsr_prepost=SP_post = SP_pre + 1, M_post[SP_post] = PC_pre + 2, PC_post = PC_pre + M_pre[PC_pre + 1] + 2
bsr_example=bra main, subroutine ldc 1, ldc 2, add, str RR, ret, main: bsr subroutine, ldr RR, ...

bra_descr=Branch Allways. Jumps to the destination. Replaces the PC with the destination address.
bra_prepost=PC_post = PC_pre + M_pre[PC_pre + 1] + 2
bra_example=@bsr_example

brf_descr=Branch on False. If a False value is on top of the stack, jump to the destination.
brf_prepost=SP_post = SP_pre - 1, PC_post = PC_pre + M_pre[PC_pre + 1] + 2 (if false on top of the stack)
brf_example=@eq_example

brt_descr=Branch on True. If a True value is on top of the stack, jump to the destination.
brt_prepost=SP_post = SP_pre - 1, PC_post = PC_pre + M_pre[PC_pre + 1] + 2 (if true on top of the stack)
brt_example=

jsr_descr=Jump to subroutine. Pops a destination from the stack, pushes the PC on the stack and jumps to the destination.
jsr_prepost=SP_post = SP_pre, PC_post = M_pre[SP_pre], M_post[SP_post] = PC_pre + 1
jsr_example=bra main, subroutine ldc 1, ldc 2, add, str RR, ret, main: ldc subroutine, jsr, ldr RR, ...

ret_descr=Return from subroutine. Pops a previously pushed PC from the stack and jumps to it.
ret_prepost=SP_post = SP_pre - 1, PC_post = M_pre[SP_pre]
ret_example=bra main, subroutine ldc 1, ldc 2, add, str RR, ret, main: bsr subroutine, ldr RR, ...

link_descr=Reserve memory for locals. Convenience instruction combining the push of MP and the adjustment of the SP.
link_prepost=MP_post = SP_pre  + 1, M_post[MP_post] = MP_pre, SP_post = MP_post + M_pre[PC_pre+1]
link_example=bra main, subroutine link 2 ; reserve for 2 locals, ldc 1, ldc 2, add, stl 1 ; store in 2nd local, ldl 1, str RR, unlink, ret, main: bsr subroutine, ldr RR, ...

unlink_descr=Free memory for locals. Convenience instruction combining the push of MP and the adjustment of the SP.
unlink_prepost=MP_post = M_pre[MP_pre], SP_post = MP_pre - 1
unlink_example=@link_example

nop_descr=No operation. Well, guess what...
nop_prepost=
nop_example=nop

halt_descr=Halt execution. Machine stops executing instructions.
halt_prepost=
halt_example=halt

trap_descr=Trap to environment function. Trap invokes a systemcall, which one is determined by its argument. Currently just 1 call exists, print the topmost element on the stack as an integer in the output window.
trap_prepost=
trap_example=ldc 5, trap 0 ; print 5 on output

annote_descr=Annotate. A meta instruction (not producing code), annotating the stack display in the user interface with text and color. Annote takes 5 arguments, (1) a register name, (2) a low offset w.r.t. the register (used as starting point for annotating), (3) a high offset, (4) a color, (5) text. Color can be one of {black, blue, cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, yellow}. Text including spaces need to be enclosed in double quotes. The annote instruction is tied to the preceding (non-meta) instruction and will be performed immediately after the execution of that instruction.
annote_prepost=
annote_example=annote SP -1 0 red "Pushed constants" ; annote top 2 stack values
\ No newline at end of file