zxq5/damn_simple_architecture
1
1
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

update roadmap and ISA spec

Browse Source
This commit is contained in:
zxq5
2026-02-07 18:21:37 +00:00
parent 250b780e14
commit e9329eca95
3 changed files with 557 additions and 274 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DSA_Assembly_Reference.md
+474 -219
View File
File diff suppressed because it is too large Load Diff
docs/DSA_ISA_Specification.md
+73 -45
View File
@@ -12,7 +12,9 @@ The Damn Simple Architecture (DSA) is a 32-bit RISC-style architecture designed
| Halfword | 16 bits | 2-byte aligned | | Halfword | 16 bits | 2-byte aligned |
| Word | 32 bits | 4-byte aligned | | Word | 32 bits | 4-byte aligned |
All multi-byte values use little-endian byte order. **Note on Endianness:**
- Instructions and numeric data in memory: Little-endian
- Data defined via `db/dh/dw` directives: Big-endian (assembler-specific)
## Registers ## Registers
@@ -23,33 +25,32 @@ DSA provides 32 programmer-accessible registers plus several internal system reg
| Hex | Register | Type | Description | | Hex | Register | Type | Description |
|-----|----------|------|-------------| |-----|----------|------|-------------|
| 0x00-0x0F | **rg0-rgf** | General Purpose | 16 general-purpose registers for variables and temporary values | | 0x00-0x0F | **rg0-rgf** | General Purpose | 16 general-purpose registers for variables and temporary values |
| 0x10 | **acc** | Special | Accumulator for calculations and temporary storage<br/>⚠️ May be overwritten by pseudo-instructions | | 0x10 | **acc** | Special | Accumulator for calculations and temporary storage<br/>⚠️ Used as scratch by pseudo-instructions - volatile |
| 0x11 | **spr** | Special | Stack pointer - points to top of stack | | 0x11 | **spr** | Special | Stack pointer - points to top of stack |
| 0x12 | **bpr** | Special | Base pointer - used for stack frame management | | 0x12 | **bpr** | Special | Base pointer - used for stack frame management |
| 0x13 | **ret** | Special | Return address register - stores function return addresses | | 0x13 | **ret** | Special | Return address register - used for function returns |
| 0x14 | **idr** | Privileged | Interrupt descriptor table address<br/>Read/write triggers protection fault in user mode | | 0x14 | **idr** | Privileged | Interrupt descriptor table address<br/>Read/write triggers protection fault in user mode |
| 0x15 | **mmr** | Privileged | Hardware memory map table address<br/>Read/write triggers protection fault in user mode | | 0x15 | **mmr** | Privileged | Hardware memory map table address<br/>Read/write triggers protection fault in user mode |
| 0x16 | **zero** | Read-only | Constant zero value<br/>Reads always return 0, writes are discarded | | 0x16 | **zero** | Read-only | Constant zero value<br/>Reads always return 0, writes are discarded |
| 0x17 | **noreg** | Placeholder | Indicates unused register field<br/>Read/write triggers illegal instruction fault | | 0x17 | **noreg** | Placeholder | Indicates unused register field<br/>Read/write triggers illegal instruction fault<br/>Can also be referenced as **null** |
| 0x18-0x1F | - | Reserved | Reserved for future use | | 0x18-0x1F | - | Reserved | Reserved for future use |
**System Registers (indices 0x18-0x1C):**
These exist in the encoding space but are internal to the CPU implementation:
| Hex | Register | Description |
|-----|----------|-------------|
| 0x18 | **mar** | Memory Address Register (CPU internal) |
| 0x19 | **mdr** | Memory Data Register (CPU internal) |
| 0x1A | **sts** | Status Register (CPU internal) |
| 0x1B | **cir** | Current Instruction Register (CPU internal) |
| 0x1C | **pcx** | Program Counter (read-only, special access) |
**Note on PCX (Program Counter):** **Note on PCX (Program Counter):**
- PCX is a read-only system register that can be accessed in some contexts - PCX can be read in certain contexts (e.g., stored during CALL)
- Writing to PCX triggers a protection fault - Writing to PCX triggers a protection fault
- PCX is automatically updated by jump and branch instructions - 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 ### Status Register (STS) Layout
The status register is a 32-bit register with the following flag bits: The status register is a 32-bit register with the following flag bits:
@@ -108,7 +109,7 @@ Used for operations with a 16-bit immediate value.
**Usage:** **Usage:**
- Arithmetic: Immediate is a signed value - Arithmetic: Immediate is a signed value
- Memory access: Immediate is a signed byte offset from base address - Memory access: Immediate is a signed byte offset from base address
- Branches: Immediate is a signed offset from current PCX - Branches: Immediate is a signed offset added to base register
- Literal loads: Immediate is unsigned 16-bit value - Literal loads: Immediate is unsigned 16-bit value
### J-Type (Jump) Instructions ### J-Type (Jump) Instructions
@@ -131,7 +132,7 @@ Used for absolute jumps with large address ranges.
**Jump Range:** 256MB region around current PC (±128MB) **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. **Note:** J-type instructions are defined but currently unused. Use I-type JMP with register addressing for all jumps.
## Hardware Instructions ## Hardware Instructions
@@ -197,8 +198,8 @@ In machine code: SrcReg (SrcReg field), BaseReg (DestReg field), Offset (Immedia
| Hex | Mnemonic | Type | Operands | Description | | Hex | Mnemonic | Type | Operands | Description |
|-----|----------|------|----------|-------------| |-----|----------|------|----------|-------------|
| 0x0B | **LLI** | I | DestReg, Value | Load 16-bit value into lower 16 bits<br/>⚠️ **CLEARS upper 16 bits!** | | 0x0B | **LLI** | I | Value, DestReg | Load 16-bit value into lower 16 bits<br/>⚠️ **CLEARS upper 16 bits!** |
| 0x0C | **LUI** | I | DestReg, Value | Load 16-bit value into upper 16 bits<br/>Lower 16 bits unchanged | | 0x0C | **LUI** | I | Value, DestReg | Load 16-bit value into upper 16 bits<br/>Lower 16 bits unchanged |
**Usage for 32-bit Values:** **Usage for 32-bit Values:**
``` ```
@@ -208,29 +209,38 @@ LUI 0xABCD, rg0 ; rg0 = 0xABCD1234
**⚠️ CRITICAL:** Always execute LLI before LUI, as LLI clears the upper 16 bits! **⚠️ CRITICAL:** Always execute LLI before LUI, as LLI clears the upper 16 bits!
**Note on LUI:** The assembler may shift the immediate value right by 16 bits when encoding, so specify the upper 16 bits directly (e.g., `LUI 0xABCD, rg0` not `LUI 0xABCD0000, rg0`).
**Encoding Note:** **Encoding Note:**
In machine code: Value (Immediate field), DestReg field (SrcReg unused, set to noreg) In machine code: Value (Immediate field), DestReg (SrcReg field for LLI, SrcReg field for LUI)
### Jump and Branch Instructions ### Jump and Branch Instructions
| Hex | Mnemonic | Type | Operands | Description | | Hex | Mnemonic | Type | Operands | Description |
|-----|----------|------|----------|-------------| |-----|----------|------|----------|-------------|
| 0x0D | **JMP** | I | DestReg, Offset | Unconditional jump to (DestReg + Offset) | | 0x0D | **JMP** | I | Offset, BaseReg | Unconditional jump to (BaseReg + Offset) |
| 0x0E | **JEQ** | I | DestReg, Offset | Jump if Equal flag set | | 0x0E | **JEQ** | I | Offset, BaseReg | Jump if Equal flag set |
| 0x0F | **JNE** | I | DestReg, Offset | Jump if Equal flag NOT set | | 0x0F | **JNE** | I | Offset, BaseReg | Jump if Equal flag NOT set |
| 0x10 | **JGT** | I | DestReg, Offset | Jump if GreaterThan flag set | | 0x10 | **JGT** | I | Offset, BaseReg | Jump if GreaterThan flag set |
| 0x11 | **JGE** | I | DestReg, Offset | Jump if GreaterThan OR Equal flag set | | 0x11 | **JGE** | I | Offset, BaseReg | Jump if GreaterThan OR Equal flag set |
| 0x12 | **JLT** | I | DestReg, Offset | Jump if LessThan flag set | | 0x12 | **JLT** | I | Offset, BaseReg | Jump if LessThan flag set |
| 0x13 | **JLE** | I | DestReg, Offset | Jump if LessThan OR Equal flag set | | 0x13 | **JLE** | I | Offset, BaseReg | Jump if LessThan OR Equal flag set |
**Jump Calculation:** **Jump Calculation:**
- Target address = DestReg + SignExtend(Offset) - Target address = BaseReg + SignExtend(Offset)
- If DestReg = zero, this becomes absolute addressing with Offset - If BaseReg = zero, this becomes absolute addressing with Offset
- If DestReg = pcx, this becomes PC-relative addressing - If BaseReg = ret, this becomes return-style addressing
- Conditional jumps check flags in STS register - Conditional jumps check flags in STS register
**Common Patterns:**
```
JMP label, zero ; Absolute jump to label address
JMP 0, ret ; Jump to address in ret register
JMP 4, ret ; Jump to (ret + 4)
```
**Encoding Note:** **Encoding Note:**
In machine code: DestReg field, Offset (Immediate field) (SrcReg unused, set to noreg) In machine code: Offset (Immediate field), BaseReg (SrcReg field) (DestReg unused, set to noreg)
### Comparison ### Comparison
@@ -265,8 +275,8 @@ DestReg and ShiftAmt fields unused (set to noreg and 0)
- Other flags undefined after arithmetic (use CMP for comparisons) - Other flags undefined after arithmetic (use CMP for comparisons)
**Encoding Notes:** **Encoding Notes:**
- INC/DEC: Reg in SrcReg1 field, also copied to DestReg field - INC/DEC: Reg in SrcReg1 field, DestReg set to noreg
- IADD/ISUB: Immediate is signed 16-bit value - IADD/ISUB: Immediate is signed 16-bit value, all three operands required
### Bitwise Logical Operations ### Bitwise Logical Operations
@@ -285,7 +295,7 @@ DestReg and ShiftAmt fields unused (set to noreg and 0)
- Other flags undefined - Other flags undefined
**Encoding Note:** **Encoding Note:**
NOT uses only Src and Dest; SrcReg2 unused (set to noreg) NOT uses only Src (SrcReg1) and Dest (DestReg); SrcReg2 unused (set to noreg)
### Shift Operations ### Shift Operations
@@ -295,17 +305,22 @@ NOT uses only Src and Dest; SrcReg2 unused (set to noreg)
| 0x18 | **SHR** | R | Reg, ShiftAmount | Shift Reg right by ShiftAmount bits<br/>Zero-fill from left (logical shift) | | 0x18 | **SHR** | R | Reg, ShiftAmount | Shift Reg right by ShiftAmount bits<br/>Zero-fill from left (logical shift) |
**Shift Amount:** **Shift Amount:**
- Can be a 5-bit literal (0-31) in ShiftAmt field - **Literal shifts**: ShiftAmount is a 5-bit literal (0-31) in assembly
- Can be a register value (low 5 bits used) - Stored in ShiftAmt field of instruction
- If using register: Place in SrcReg2, set ShiftAmt to 0 - SrcReg2 set to noreg
- If using literal: Place in ShiftAmt field, set SrcReg2 to noreg - **Register shifts**: ShiftAmount is a register containing shift value
- Register specified in SrcReg2 field
- ShiftAmt field must be 0
- Only low 5 bits of register value used
**Note:** Current assembler implementation may only support literal shifts. Check assembler documentation.
**Flag Effects:** **Flag Effects:**
- Zero flag set if result is zero - Zero flag set if result is zero
**Encoding Notes:** **Encoding Notes:**
- Reg in both SrcReg1 and DestReg fields - Reg in both SrcReg1 and DestReg fields (shifted in place)
- For literal shifts: ShiftAmt field contains shift count - For literal shifts: ShiftAmt field contains shift count, SrcReg2 = noreg
- For register shifts: SrcReg2 contains register, ShiftAmt must be 0 - For register shifts: SrcReg2 contains register, ShiftAmt must be 0
### System and Control Instructions ### System and Control Instructions
@@ -331,6 +346,17 @@ NOT uses only Src and Dest; SrcReg2 unused (set to noreg)
- INT: InterruptCode in low 8 bits of Immediate field - INT: InterruptCode in low 8 bits of Immediate field
- IRT/HLT: All register fields set to noreg, ShiftAmt to 0 - IRT/HLT: All register fields set to noreg, ShiftAmt to 0
### Meta Instructions (Assembler/Linker)
These instructions are used by the assembler and linker but may not represent real CPU operations.
| Hex | Mnemonic | Description |
|-----|----------|-------------|
| 0x27 | **SEGMENT** | Segment marker (implementation-specific) |
| 0x3E | **DATA** | Raw data embedding |
**Note:** The SEGMENT instruction opcode may vary between implementations (0x27 in assembler, 0x3F in some contexts). Consult your specific toolchain documentation.
## Instruction Summary Table ## Instruction Summary Table
| Opcode | Mnemonic | Type | Category | | Opcode | Mnemonic | Type | Category |
@@ -374,6 +400,8 @@ NOT uses only Src and Dest; SrcReg2 unused (set to noreg)
| 0x24 | HLT | R | System | | 0x24 | HLT | R | System |
| 0x25 | IADD | I | Arithmetic | | 0x25 | IADD | I | Arithmetic |
| 0x26 | ISUB | I | Arithmetic | | 0x26 | ISUB | I | Arithmetic |
| 0x27 | SEGMENT | - | Meta |
| 0x3E | DATA | - | Meta |
## Exception Conditions ## Exception Conditions
@@ -393,9 +421,9 @@ See the DSA Assembly Language Reference for the complete calling convention and
## Notes on Design ## Notes on Design
1. **Word Size:** All addresses and general computation is 32-bit 1. **Word Size:** All addresses and general computation is 32-bit
2. **Endianness:** Little-endian byte order 2. **Endianness:** Little-endian for instructions and runtime data; assembler data directives may use big-endian
3. **Stack Growth:** Stack grows upward (incrementing addresses) 3. **Stack Growth:** Stack grows **downward** (toward lower addresses) - PUSH decrements SPR
4. **Alignment:** Natural alignment required for halfword and word accesses 4. **Alignment:** Natural alignment required for halfword and word accesses
5. **Sign Extension:** All immediate values are sign-extended unless noted 5. **Sign Extension:** All immediate values are sign-extended unless noted
6. **Zero Register:** Provides constant zero, writes are legal but discarded 6. **Zero Register:** Provides constant zero, writes are legal but discarded
7. **Reserved Encodings:** Opcodes 0x27-0x3F reserved for future use 7. **Reserved Encodings:** Opcodes 0x27-0x3D and 0x3F reserved or implementation-specific
docs/DSA_Project_Roadmap.md
+10 -10
View File
@@ -263,12 +263,12 @@
- [ ] Array syntax - [ ] Array syntax
- [ ] Struct syntax - [ ] Struct syntax
- [x] Pointer syntax - [x] Pointer syntax
- [ ] Namespaced call syntax - [x] Namespaced call syntax
- [x] AST node definitions - [x] AST node definitions
- [ ] Error recovery mechanisms - [ ] Error recovery mechanisms
- [ ] Comprehensive parser tests - [ ] Comprehensive parser tests
- [ ] Syntax error message quality testing - [ ] Syntax error message quality testing
- [ ] Implement C frontend by moving lexer/parser from `c_compiler` to the new `compiler` project structure - [x] Implement C frontend by moving lexer/parser from `c_compiler` to the new `compiler` project structure
- [ ] Evaluate possible memory management strategies (e.g., keep all variables on the stack vs spill only when calling functions) - [ ] Evaluate possible memory management strategies (e.g., keep all variables on the stack vs spill only when calling functions)
--- ---
@@ -290,7 +290,7 @@
- [ ] Optimize register allocation further - [ ] Optimize register allocation further
- [x] Implement proper function calling conventions - [x] Implement proper function calling conventions
- [ ] Add constant folding optimization - [ ] Add constant folding optimization
- [ ] Dead code elimination - [x] Dead code elimination
- [ ] Test each feature thoroughly - [ ] Test each feature thoroughly
--- ---
@@ -376,7 +376,7 @@
**Dependencies:** None **Dependencies:** None
**Deliverable:** `docs/build-system-design.md` **Deliverable:** `docs/build-system-design.md`
- [ ] Define project structure conventions - [x] Define project structure conventions
- [ ] Design build manifest format (`dsa-project.toml` or similar) - [ ] Design build manifest format (`dsa-project.toml` or similar)
- [ ] Dependency resolution strategy - [ ] Dependency resolution strategy
- [ ] Build cache design - [ ] Build cache design
@@ -391,12 +391,12 @@
**Dependencies:** 3.1.1, 1.2.2, 1.1.3, 2.1.3 **Dependencies:** 3.1.1, 1.2.2, 1.1.3, 2.1.3
**Deliverable:** `dsa-build` executable **Deliverable:** `dsa-build` executable
- [ ] Create crate: `dsa-build` - [x] Create crate: `dsa-build`
- [ ] Manifest parser - [ ] Manifest parser
- [ ] Dependency graph builder - [ ] Dependency graph builder
- [ ] Task orchestrator - [ ] Task orchestrator
- [ ] Compilation tasks - [x] Compilation tasks
- [ ] Assembly tasks - [x] Assembly tasks
- [ ] Linking tasks - [ ] Linking tasks
- [ ] Build cache implementation - [ ] Build cache implementation
- [ ] Parallel build support - [ ] Parallel build support
@@ -412,11 +412,11 @@
**Dependencies:** 3.1.2 **Dependencies:** 3.1.2
**Deliverable:** Enhanced `dsa-build` with project management **Deliverable:** Enhanced `dsa-build` with project management
- [ ] `dsa new <project>` — Create new project - [x] `dsa new <project>` — Create new project
- [ ] `dsa init` — Initialize in existing directory - [x] `dsa init` — Initialize in existing directory
- [ ] `dsa add <dependency>` — Add dependency - [ ] `dsa add <dependency>` — Add dependency
- [ ] Binary vs library project types - [ ] Binary vs library project types
- [ ] Template system for project scaffolding - [x] Template system for project scaffolding
- [ ] Documentation for each command - [ ] Documentation for each command
--- ---