isa-insn.txt

Values are shown in their natural big-endian representation.

Instruction 0xABCD, or 0baaaabbbbccccdddd:

           aaaa bbbb  cccc dddd
Bit        1111 1198  7654 3210
           5432 10

C syntax is used in explications; familiarity with it is assumed.

Ranges of [a:b] are inclusive of both endpoints (forgive me).

- I[15:0] == 0 ( DISTINGUISHED EXCEPTION GENERATOR )

	Cause the exception handler to become active, clearing bit 0 of SR 2,
	setting SR 8 to R0+2, setting R0 to the new SR 2 value, and setting SR 9 to 1.
	
- I[15:12] == 0b0001   ( BITWISE INSTRUCTIONS )
	- I[3:0]:  (D) Destination Register, LHS (0-15)
	- I[7:4]:  (S) Source Register, RHS (0-15)
	- I[11:8]: (M) Truth Table Number (0-15)
		- cf. https://en.wikipedia.org/wiki/Truth_table#Binary_operations
			0: F    1: NOR  2: NCI  3: ND
			4: NMI	5: NS	6: XOR	7: NAND
			8: AND	9: XNOR	10: S	11: MI
			12: D	13: CI	14: OR	15: T
		Note that this value can be treated as a LUT, using bits from D and S
		as indices into the table number.

- I[15:12] == 0b0010	( ARITHMETIC INSTRUCTIONS )
	- I[3:0]:  (D) Destination Register, LHS (0-15)
	- I[7:4]:  (S) Source Register, RHS (0-15)
	- I[11]:   (Si) Source Immediate
	- I[10:8]: (M) Operation Number (0-7)
		- 0: Add (D = D + S)
		- 1: Sub (D = D - S)
		- 2: Shl (D = D << S, fill 0)
		- 3: Shr (D = D >> S, fill 0)
		- 4: Asr (D = D >> S, fill sign)
		- 5: Rol (D = D rotate left S)
		- 6: Ror (D = D rotate right S)
		- 7: Neg (D = - S)

	If Si is set, then S is taken to be the value to be used for the operation.
	Otherwise, S is a register number.

- I[15:12] == 0b0011	( COMPARISON INSTRUCTIONS )
	- I[3:0]: (D) Destination Register, LHS (0-15)
	- I[7:4]: (S) Source Register, RHS (0-15)
	- I[8]:   EQ Flag: True when D = S
	- I[9]:   GT Flag: True when D > S
	- I[10]:  SN Flag: GT respects sign
	- I[11]:  IV FLag: Test is inverted
		- I[11:8] table: (AB = "above", BL = "below", both unsigned)
			0: F	1: EQ	2: AB	3: ABE
			4: F	5: EQ	6: GT	7: GTE
			8: T	9: NEQ	10: BLE	11: BL
			12: T	13: NEQ	14: LT	15: LTE

- I[15:14] == 0b01    ( DATA TRANSFER INSTRUCTIONS )
    - I[3:0]:   (D) Destination Register, LHS (0-15)
    - I[7:4]:   (S) Source Register, RHS (0-15)
    - I[10]:    (Dm) Destination indirect
    - I[9:8]:   (Da) Destination increment mode
    - I[13]:    (Sm) Source indirect
    - I[12:11]: (Sa) Source increment mode

The _indirect bit_, if set, uses the register contents as a memory address and generates the appropriate load/store behavior.

The _increment mode_ is a two bit value interpreted as:

    - 0b00 - no change is made to the registers
    - 0b01 - autoincrement: increment the value of the register by $WORDBYTES after the memory operation
    - 0b10 - autodecrement: decrement the value of the register by $WORDBYTES before the operation
    - 0b11 - autopostdecrement: decrement the value of the register by $WORDBYTES after the memory operation

- I[15:12] == 0b1000	( CONDITIONAL INSTRUCTIONS )
	- I[7:0]:  (S) *Signed* Offset (in *Instructions*)
	- I[11:8]: (C) Comparison Register (0-15)
		- Condition is passed if reg is nonzero

- I[15:11] == 0b1001  ( SUBWORD OPERATIONS  )
	- I[3:0]:  (D) Destination Register (0-15)
	- I[7:4]:  (Swi) Subword Index Register (0-15)
	- I[11]:   (Sex) Sign Extend
	- I[10:8]: (Sws) Subword Size (0-7)

	When Sws == 0, size is considered to be 8.

	Equivalent to the following sequence of code,
	which moves the Sws bytes starting at the
	Swith byte from the most insignificant byte
	and sign extends the result if bit 11 is set.

	#if (Sws == 0)
	#define Sws 8
	#endif
	XF *-SP, T0
	XF *-SP, T1
	SI T0, Sws*8
	SI T1, 1
	SHL T1, T0
	SUB T1, 1
	SI T0, 8*Swi
	SHL T1, T0
	AND D, T1
	SHR D, T0
	SHR T1, T0
	NOT T1
	ADD T1, 1
	ROL T1, 1
	MOV T0, T1
	AND T0, D
	ADD T0, Sex
	JNZ T0, .signset
	ADD PC, .end-$
.signset:
    OR D, T1
.end:
	XF T1, *SP+
	XF T0, *SP+

- I[15:13] == 0b101	( SYSTEM REGISTERS )
	- I[12]: (W) 1: Write, 0: Read
	- I[11:8]: (R) Register (0-15)
	- I[7:0]: (S) System Register (0-255)
		- System Registers (R: Read, W: Write):

			- S 0: Model/Stepping (R)
				- 0: Unknown or prototype
				- Otherwise: Reserved

			- S 1: Compiled Word Size (R)
				- in bits

			- S 2: Exception Handling Routine (RW)
				- bit 0: Exceptions Enabled. Cleared when entering routine.
				- all other bits: the PC will be set to this value when an
				  interrupt occurs.

			- S 3: Power State (W)
				- bit 0: Halt
				- all other bits: reserved, write 0

			- S 4: Instructions Retired (RW)
				- This counts up after every retired instruction.
				  Writing to this register starts counting from that
				  value. Initializes to 0 on reset.

			- S 5: Cycles Elapsed (RW)
				- This counts the number of cycles elapsed.
				  Writing to this register starts counting from that
				  value. Initializes to 0 on reset.

			- S 6: Core Frequency (R)
				- Frequency of the Cycles Elapsed counter, divided
				  by 1024 to produce kibiHertz.

			- S 7: ISA Extensions (R)
				- bit 0: Hardware multiplier
				- all other bits: reserved

            - S 8: Exception Continuation (RW)
			    - Stores the previous contents of the PC when handling
				  an exception.
			
			- S 9: Exception Cause (RW)
				- bit 0: Registered Exception. If this bit is set, the remainder
				         of the bits are interpreted according to the following
						 table:

				  - 0: Divide by Zero
				  - 1: Illegal instruction
				  - 2: Supervisor request
				 
				If the exception is not registered, then the cause is the physical
				address of the MMIO region for the device responsible for the
				exception.
			
			- S 10: Unofficial Debug Output Port
				- writes a byte to stdout of most simulators

			-S 192-255: Reserved for Vendor Extensions

- I[15:12] == 0b1100 ( SMALL IMMEDIATE )
    - I[3:0]:  (D) Destination Register
	- I[11:4]: (I) Immediate Value
	Stores the value in the register.

- I[15:12] == 0b1101 ( SELECT REGISTER )
	- I[3:0]:  (Z) Zero Register
	- I[7:4]:  (N) Nonzero Register
	- I[11:8]: (C) Condition Register
	Replace the condition register according to its value.

- I[15:12] == 0b1110 ( MISCELLANEOUS FUNCTIONALITY )
	- I[3:0]: (A) First Register
	- I[7:4]: (B) Second Register

	- I[11:8] == 0b0000 ( SWAP REGISTERS )
		A = B
		B = A

	- I[11:8] == 0b0001 ( MULTIPLY ) *
		A *= B

	- I[11:8] == 0b0010 ( DIVIDE ) *
		A /= B

	- I[11:8] == 0b0011 ( MODULUS ) *
		A %= B

	Instructions marked (*) are available only on models with a hardware
	multiplier (see SR 7).

	- I[11:8] == 0b0100 ( LOAD REG )
		A = regs[B]

	- I[11:8] == 0b0101 ( STORE REG )
		regs[B] = A

	- I[11:8] == 0b0110 ( LOAD OFFSET )
		A = *(A + imm(B)*$WORDBYTES)

	- I[11:8] == 0b0111 ( LOOP )
		A -= 1
		if A != 0 { PC += imm(B)*$IWORDBYTES }

	- I[11:8] == 0b0111 ( LOOP INDIRECT )
		A -= 1
		if A != 0 { PC += B }

	- I[11:8] == 0b1000 ( JZ )
		if A == 0 { PC += imm(B)*$IWORDBYTES }

	- I[11:8] == 0b1001 ( JZ INDIRECT )
		if A == 0 { PC += B }

	- I[11:8] == 0b1010 ( JNZ )
		if A != 0 { PC += imm(B)*$IWORDBYTES }

	- I[11:8] == 0b1011 ( JNZ INDIRECT )
		if A != 0 { PC += B }

	- I[11:8] == 0b1100 ( JGZ )
		if signed(A) > 0 { PC += imm(B)*$IWORDBYTES }

	- I[11:8] == 0b1101 ( JGZ INDIRECT )
		if signed(A) > 0 { PC += B }

	- I[11:8] == 0b1110 ( JLZ )
		if signed(A) < 0 { PC += imm(B)*$IWORDBYTES }

	- I[11:8] == 0b1111 ( JLZ INDIRECT )
		if signed(A) < 0 { PC += B }


- I[15:12] == 0b1111 ( LONG INSTRUCTION )

	Instructions starting with this nibble are reserved for extensions
	that use more than 16 bits of space for instructions. The encoded
	length preserves the ability of tools which do not understand any
	particular extensions to still understand the delineation points
	of the instruction stream.

	- I[11:8]: (L) Number of iwords to follow.