damn_simple_architecture/docs/DSA_ISA_Specification.md

DSA Instruction Set Architecture Specification

Overview

The Damn Simple Architecture (DSA) is a 32-bit RISC-style architecture designed for simplicity and educational purposes. This document provides the complete instruction set architecture specification, including all hardware instructions, registers, and encoding formats.

Data Types and Sizes

Type	Size	Alignment
Byte	8 bits	1-byte aligned
Halfword	16 bits	2-byte aligned
Word	32 bits	4-byte aligned

All multi-byte values use little-endian byte order.

Registers

DSA provides 32 programmer-accessible registers plus several internal system registers.

Programmer-Accessible Registers

Hex	Register	Type	Description
0x00-0x0F	rg0-rgf	General Purpose	16 general-purpose registers for variables and temporary values
0x10	acc	Special	Accumulator for calculations and temporary storage ⚠️ May be overwritten by pseudo-instructions
0x11	spr	Special	Stack pointer - points to top of stack
0x12	bpr	Special	Base pointer - used for stack frame management
0x13	ret	Special	Return address register - stores function return addresses
0x14	idr	Privileged	Interrupt descriptor table address Read/write triggers protection fault in user mode
0x15	mmr	Privileged	Hardware memory map table address Read/write triggers protection fault in user mode
0x16	zero	Read-only	Constant zero value Reads always return 0, writes are discarded
0x17	noreg	Placeholder	Indicates unused register field Read/write triggers illegal instruction fault
0x18-0x1F	-	Reserved	Reserved for future use

Note on PCX (Program Counter):

• PCX is a read-only system register that can be accessed in some contexts
• Writing to PCX triggers a protection fault
• PCX is automatically updated by jump and branch instructions

System Registers (Internal)

These registers are used internally by the CPU and are not directly accessible via assembly instructions:

Register	Description
MAR	Memory Address Register - holds address for memory operations
MDR	Memory Data Register - holds data for memory transfers
CIR	Current Instruction Register - holds instruction being executed
STS	Status Register - stores comparison and arithmetic flags
PCX	Program Counter - stores address of next instruction

Status Register (STS) Layout

The status register is a 32-bit register with the following flag bits:

Bit	Name	Description	Boot Value
0	Equal	Set if last comparison result was equal	0
1	GreaterThan	Set if last comparison result was greater than	0
2	GreaterThanOrEqual	Set if last comparison was greater than or equal	0
3	LessThan	Set if last comparison result was less than	0
4	LessThanOrEqual	Set if last comparison was less than or equal	0
5	Zero	Set if last arithmetic/logic operation result was zero	0
6-31	-	Reserved	0

Instruction Encoding Formats

DSA uses three instruction encoding formats:

R-Type (Register) Instructions

Used for operations with register operands only, including shifts.

 31-26  |  25-21  |  20-16  |  15-11  |  10-6  |  5-0
--------+---------+---------+---------+--------+-------
 Opcode | SrcReg1 | SrcReg2 | DestReg | ShiftAmt | Unused

• Opcode (6 bits): Instruction operation code
• SrcReg1 (5 bits): First source register
• SrcReg2 (5 bits): Second source register
• DestReg (5 bits): Destination register
• ShiftAmt (5 bits): Shift amount (for shift instructions only, must be 0 otherwise)
• Unused (6 bits): Must be 0

Important Rules:

• ShiftAmt must be 0 for non-shift instructions (else illegal instruction fault)
• Unused register fields must be set to noreg (0x17) if not used
• Using registers in unexpected positions may cause illegal instruction fault

I-Type (Immediate) Instructions

Used for operations with a 16-bit immediate value.

 31-26  |  25-21  |  20-16  |    15-0
--------+---------+---------+-------------
 Opcode | SrcReg  | DestReg | 16-bit Immediate

• Opcode (6 bits): Instruction operation code
• SrcReg (5 bits): Source register (base for memory ops)
• DestReg (5 bits): Destination register (or offset register for jumps)
• Immediate (16 bits): Signed 16-bit immediate value or offset

Usage:

• Arithmetic: Immediate is a signed value
• Memory access: Immediate is a signed byte offset from base address
• Branches: Immediate is a signed offset from current PCX
• Literal loads: Immediate is unsigned 16-bit value

J-Type (Jump) Instructions

Used for absolute jumps with large address ranges.

 31-26  |         25-0
--------+----------------------
 Opcode |   26-bit Address

• Opcode (6 bits): Jump instruction code
• Address (26 bits): Partial address for jump

Address Calculation:

1. Left-shift the 26-bit address by 2 (word alignment)
2. OR with upper 4 bits of current PCX
3. Result is final 32-bit jump address

Jump Range: 256MB region around current PC (±128MB)

Note: J-type instructions are defined but currently unused. Use I-type JMP with register addressing for long jumps.

Hardware Instructions

Data Movement

Hex	Mnemonic	Type	Operands	Description
0x00	NOP	R	-	No operation - does nothing
0x01	MOV	R	SrcReg, DestReg	Copy value from SrcReg to DestReg
0x02	MOVS	R	SrcReg, DestReg	Copy with sign extension to fill 32 bits

MOV/MOVS Details:

• MOV performs direct copy (all 32 bits)
• MOVS sign-extends the value (useful after byte/halfword loads)
• Both instructions set the Zero flag if result is zero

Memory Access - Load Instructions

All loads require proper alignment or trigger an alignment fault.

Hex	Mnemonic	Type	Operands	Description
0x03	LDB	I	BaseReg, DestReg, Offset	Load byte (8-bit), zero-extend to 32 bits
0x04	LDBS	I	BaseReg, DestReg, Offset	Load byte (8-bit), sign-extend to 32 bits
0x05	LDH	I	BaseReg, DestReg, Offset	Load halfword (16-bit), zero-extend to 32 bits
0x06	LDHS	I	BaseReg, DestReg, Offset	Load halfword (16-bit), sign-extend to 32 bits
0x07	LDW	I	BaseReg, DestReg, Offset	Load word (32-bit)

Load Operation:

• Effective address = BaseReg + SignExtend(Offset)
• Offset is a signed 16-bit value
• Alignment requirements:
  • LDB/LDBS: No alignment required (byte-aligned)
  • LDH/LDHS: Must be 2-byte aligned
  • LDW: Must be 4-byte aligned

Encoding Note: In machine code, the order is: BaseReg (SrcReg field), DestReg field, Offset (Immediate field)

Memory Access - Store Instructions

All stores require proper alignment or trigger an alignment fault.

Hex	Mnemonic	Type	Operands	Description
0x08	STB	I	SrcReg, BaseReg, Offset	Store byte (8-bit) to memory
0x09	STH	I	SrcReg, BaseReg, Offset	Store halfword (16-bit) to memory
0x0A	STW	I	SrcReg, BaseReg, Offset	Store word (32-bit) to memory

Store Operation:

• Effective address = BaseReg + SignExtend(Offset)
• Offset is a signed 16-bit value
• Only the relevant bits are stored (8, 16, or 32)
• Alignment requirements:
  • STB: No alignment required (byte-aligned)
  • STH: Must be 2-byte aligned
  • STW: Must be 4-byte aligned

Encoding Note: In machine code: SrcReg (SrcReg field), BaseReg (DestReg field), Offset (Immediate field)

Immediate Load Instructions

Hex	Mnemonic	Type	Operands	Description
0x0B	LLI	I	DestReg, Value	Load 16-bit value into lower 16 bits ⚠️ CLEARS upper 16 bits!
0x0C	LUI	I	DestReg, Value	Load 16-bit value into upper 16 bits Lower 16 bits unchanged

Usage for 32-bit Values:

LLI 0x1234, rg0    ; rg0 = 0x00001234
LUI 0xABCD, rg0    ; rg0 = 0xABCD1234

⚠️ CRITICAL: Always execute LLI before LUI, as LLI clears the upper 16 bits!

Encoding Note: In machine code: Value (Immediate field), DestReg field (SrcReg unused, set to noreg)

Jump and Branch Instructions

Hex	Mnemonic	Type	Operands	Description
0x0D	JMP	I	DestReg, Offset	Unconditional jump to (DestReg + Offset)
0x0E	JEQ	I	DestReg, Offset	Jump if Equal flag set
0x0F	JNE	I	DestReg, Offset	Jump if Equal flag NOT set
0x10	JGT	I	DestReg, Offset	Jump if GreaterThan flag set
0x11	JGE	I	DestReg, Offset	Jump if GreaterThan OR Equal flag set
0x12	JLT	I	DestReg, Offset	Jump if LessThan flag set
0x13	JLE	I	DestReg, Offset	Jump if LessThan OR Equal flag set

Jump Calculation:

• Target address = DestReg + SignExtend(Offset)
• If DestReg = zero, this becomes absolute addressing with Offset
• If DestReg = pcx, this becomes PC-relative addressing
• Conditional jumps check flags in STS register

Encoding Note: In machine code: DestReg field, Offset (Immediate field) (SrcReg unused, set to noreg)

Comparison

Hex	Mnemonic	Type	Operands	Description
0x14	CMP	R	Reg1, Reg2	Compare Reg1 with Reg2, set flags in STS

Flag Setting:

• Equal: Set if Reg1 == Reg2
• GreaterThan: Set if Reg1 > Reg2 (signed)
• GreaterThanOrEqual: Set if Reg1 >= Reg2 (signed)
• LessThan: Set if Reg1 < Reg2 (signed)
• LessThanOrEqual: Set if Reg1 <= Reg2 (signed)
• Zero: Set if (Reg1 - Reg2) == 0 (same as Equal)

Encoding Note: DestReg and ShiftAmt fields unused (set to noreg and 0)

Arithmetic Instructions

Hex	Mnemonic	Type	Operands	Description
0x15	INC	R	Reg	Increment register by 1
0x16	DEC	R	Reg	Decrement register by 1
0x19	ADD	R	Src1, Src2, Dest	Dest = Src1 + Src2
0x1A	SUB	R	Src1, Src2, Dest	Dest = Src1 - Src2
0x25	IADD	I	Src, Literal, Dest	Dest = Src + SignExtend(Literal)
0x26	ISUB	I	Src, Literal, Dest	Dest = Src - SignExtend(Literal)

Flag Effects:

• Zero flag set if result is zero
• Other flags undefined after arithmetic (use CMP for comparisons)

Encoding Notes:

• INC/DEC: Reg in SrcReg1 field, also copied to DestReg field
• IADD/ISUB: Immediate is signed 16-bit value

Bitwise Logical Operations

Hex	Mnemonic	Type	Operands	Description
0x1B	AND	R	Src1, Src2, Dest	Dest = Src1 & Src2 (bitwise AND)
0x1C	OR	R	Src1, Src2, Dest	Dest = Src1 | Src2 (bitwise OR)
0x1D	NOT	R	Src, Dest	Dest = ~Src (bitwise NOT)
0x1E	XOR	R	Src1, Src2, Dest	Dest = Src1 ^ Src2 (bitwise XOR)
0x1F	NAND	R	Src1, Src2, Dest	Dest = ~(Src1 & Src2) (bitwise NAND)
0x20	NOR	R	Src1, Src2, Dest	Dest = ~(Src1 | Src2) (bitwise NOR)
0x21	XNOR	R	Src1, Src2, Dest	Dest = ~(Src1 ^ Src2) (bitwise XNOR)

Flag Effects:

• Zero flag set if result is zero
• Other flags undefined

Encoding Note: NOT uses only Src and Dest; SrcReg2 unused (set to noreg)

Shift Operations

Hex	Mnemonic	Type	Operands	Description
0x17	SHL	R	Reg, ShiftAmount	Shift Reg left by ShiftAmount bits Zero-fill from right
0x18	SHR	R	Reg, ShiftAmount	Shift Reg right by ShiftAmount bits Zero-fill from left (logical shift)

Shift Amount:

• Can be a 5-bit literal (0-31) in ShiftAmt field
• Can be a register value (low 5 bits used)
  • If using register: Place in SrcReg2, set ShiftAmt to 0
  • If using literal: Place in ShiftAmt field, set SrcReg2 to noreg

Flag Effects:

• Zero flag set if result is zero

Encoding Notes:

• Reg in both SrcReg1 and DestReg fields
• For literal shifts: ShiftAmt field contains shift count
• For register shifts: SrcReg2 contains register, ShiftAmt must be 0

System and Control Instructions

Hex	Mnemonic	Type	Operands	Description
0x22	INT	I	InterruptCode	Trigger interrupt with 8-bit code Saves return address to ret register Sets bpr to kernel stack
0x23	IRT	R	-	Return from interrupt Restores execution context
0x24	HLT	R	-	Halt processor execution Stops fetch-decode-execute cycle

INT Behavior:

1. Save current PCX to ret register
2. Switch bpr to kernel stack address
3. Look up interrupt handler address in interrupt descriptor table (idr)
4. Jump to handler at interrupt vector

IRT Behavior:

1. Restore previous execution context
2. Return to address in ret register
3. Restore user stack pointer

Encoding Notes:

• INT: InterruptCode in low 8 bits of Immediate field
• IRT/HLT: All register fields set to noreg, ShiftAmt to 0

Instruction Summary Table

Opcode	Mnemonic	Type	Category
0x00	NOP	R	Control
0x01	MOV	R	Data Movement
0x02	MOVS	R	Data Movement
0x03	LDB	I	Memory Load
0x04	LDBS	I	Memory Load
0x05	LDH	I	Memory Load
0x06	LDHS	I	Memory Load
0x07	LDW	I	Memory Load
0x08	STB	I	Memory Store
0x09	STH	I	Memory Store
0x0A	STW	I	Memory Store
0x0B	LLI	I	Immediate Load
0x0C	LUI	I	Immediate Load
0x0D	JMP	I	Jump
0x0E	JEQ	I	Branch
0x0F	JNE	I	Branch
0x10	JGT	I	Branch
0x11	JGE	I	Branch
0x12	JLT	I	Branch
0x13	JLE	I	Branch
0x14	CMP	R	Comparison
0x15	INC	R	Arithmetic
0x16	DEC	R	Arithmetic
0x17	SHL	R	Shift
0x18	SHR	R	Shift
0x19	ADD	R	Arithmetic
0x1A	SUB	R	Arithmetic
0x1B	AND	R	Logical
0x1C	OR	R	Logical
0x1D	NOT	R	Logical
0x1E	XOR	R	Logical
0x1F	NAND	R	Logical
0x20	NOR	R	Logical
0x21	XNOR	R	Logical
0x22	INT	I	System
0x23	IRT	R	System
0x24	HLT	R	System
0x25	IADD	I	Arithmetic
0x26	ISUB	I	Arithmetic

Exception Conditions

The following conditions trigger exceptions:

Exception	Trigger Condition
Illegal Instruction	- Invalid opcode - noreg used as source/destination - ShiftAmt non-zero for non-shift instruction - Register field violations
Protection Fault	- Write to pcx register - Read/write idr or mmr in user mode - Read from noreg - Write to zero register (discarded, no fault)
Alignment Fault	- LDH/LDHS/STH with odd address - LDW/STW with address not divisible by 4
Memory Access Violation	- Access to unmapped or protected memory - Stack overflow/underflow

Calling Convention

See the DSA Assembly Language Reference for the complete calling convention and ABI specification.

Notes on Design

1. Word Size: All addresses and general computation is 32-bit
2. Endianness: Little-endian byte order
3. Stack Growth: Stack grows upward (incrementing addresses)
4. Alignment: Natural alignment required for halfword and word accesses
5. Sign Extension: All immediate values are sign-extended unless noted
6. Zero Register: Provides constant zero, writes are legal but discarded
7. Reserved Encodings: Opcodes 0x27-0x3F reserved for future use