Commit efc5e2b6 authored by atzedijkstra@gmail.com's avatar atzedijkstra@gmail.com
Browse files

initial

parents
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
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
# 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
# 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
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment