updated docs
This commit is contained in:
@@ -0,0 +1,944 @@
|
||||
# DSA Assembly Language Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document is the comprehensive reference for writing DSA assembly programs. It covers assembly syntax, pseudo-instructions, directives, the module system, calling conventions, and provides complete examples.
|
||||
|
||||
**Related Documents:**
|
||||
- For hardware instruction details and encoding: See *DSA ISA Specification*
|
||||
- For build system and toolchain: See project documentation
|
||||
|
||||
## Assembly Syntax
|
||||
|
||||
### General Rules
|
||||
|
||||
- **Case Insensitive:** Mnemonics can be uppercase or lowercase (`mov` = `MOV`)
|
||||
- **Comments:** Use `//` for line comments or `/* */` for block comments
|
||||
- **Labels:** Identifier followed by colon (e.g., `main:`, `loop:`)
|
||||
- **Whitespace:** Flexible spacing between operands
|
||||
- **Numbers:**
|
||||
- Decimal: `100`, `255`
|
||||
- Hexadecimal: `0x10`, `0xFFFF`
|
||||
- Binary: `0b1010` (if supported by assembler)
|
||||
|
||||
### Operand Order Convention
|
||||
|
||||
DSA assembly uses **GAS-style syntax** (source → destination):
|
||||
|
||||
```asm
|
||||
mov rg0, rg1 ; Copy rg0 TO rg1 (destination is last)
|
||||
add rg0, rg1, rg2 ; rg2 = rg0 + rg1 (destination is last)
|
||||
```
|
||||
|
||||
For load/store with immediates:
|
||||
```asm
|
||||
lli 0x1234, rg0 ; Load immediate 0x1234 INTO rg0
|
||||
ldw rg0, rg1, 8 ; Load from (rg0+8) INTO rg1
|
||||
stw rg0, rg1, 8 ; Store rg0 TO address (rg1+8)
|
||||
```
|
||||
|
||||
## Registers
|
||||
|
||||
| Register(s) | Type | Description | Usage Notes |
|
||||
|-------------|------|-------------|-------------|
|
||||
| **rg0-rgf** | General | 16 general-purpose registers | Use for variables, temporaries |
|
||||
| **acc** | Special | Accumulator | ⚠️ Volatile - pseudo-instructions may overwrite |
|
||||
| **spr** | Special | Stack pointer | Points to top of stack |
|
||||
| **bpr** | Special | Base pointer | Used for stack frames |
|
||||
| **ret** | Special | Return address | Holds return address for functions |
|
||||
| **zero** | Read-only | Always zero | Reads return 0, writes discarded |
|
||||
| **pcx** | Read-only | Program counter | Cannot be written directly |
|
||||
| **idr** | Privileged | Interrupt descriptor table | Kernel mode only |
|
||||
| **mmr** | Privileged | Memory map register | Kernel mode only |
|
||||
| **noreg** | Placeholder | No register | Used in encoding, triggers fault if accessed |
|
||||
|
||||
**Register Conventions:**
|
||||
- **acc**: Used by pseudo-instructions for temporary values - do not rely on it being preserved
|
||||
- **rgf**: Used by label-addressing pseudo-instructions as a scratch register
|
||||
- **rg0-rge**: Available for general use; calling convention defines which are preserved
|
||||
|
||||
## Hardware Instructions
|
||||
|
||||
This section shows assembly syntax. For encoding details, see the ISA Specification.
|
||||
|
||||
### Data Movement
|
||||
|
||||
```asm
|
||||
mov src_reg, dest_reg ; Copy value from src_reg to dest_reg
|
||||
movs src_reg, dest_reg ; Copy with sign extension
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
mov rg0, rg1 ; rg1 = rg0
|
||||
movs acc, rg2 ; rg2 = sign_extend(acc)
|
||||
```
|
||||
|
||||
### Memory Load Instructions
|
||||
|
||||
```asm
|
||||
ldb base_reg, dest_reg [, offset] ; Load byte (zero-extend)
|
||||
ldbs base_reg, dest_reg [, offset] ; Load byte (sign-extend)
|
||||
ldh base_reg, dest_reg [, offset] ; Load halfword (zero-extend)
|
||||
ldhs base_reg, dest_reg [, offset] ; Load halfword (sign-extend)
|
||||
ldw base_reg, dest_reg [, offset] ; Load word
|
||||
```
|
||||
|
||||
**Offset:** Optional signed 16-bit offset (defaults to 0)
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
ldb rg0, rg1 ; Load byte from address in rg0
|
||||
ldw rg0, rg1, 8 ; Load word from (rg0 + 8)
|
||||
ldhs rg2, rg3, -4 ; Load signed halfword from (rg2 - 4)
|
||||
```
|
||||
|
||||
**Alignment Requirements:**
|
||||
- `ldb/ldbs`: No alignment required
|
||||
- `ldh/ldhs`: Must be 2-byte aligned
|
||||
- `ldw`: Must be 4-byte aligned
|
||||
|
||||
### Memory Store Instructions
|
||||
|
||||
```asm
|
||||
stb src_reg, base_reg [, offset] ; Store byte
|
||||
sth src_reg, base_reg [, offset] ; Store halfword
|
||||
stw src_reg, base_reg [, offset] ; Store word
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
stb rg0, rg1 ; Store byte to address in rg1
|
||||
stw rg0, rg1, 12 ; Store word to (rg1 + 12)
|
||||
sth acc, spr, -2 ; Store halfword to (spr - 2)
|
||||
```
|
||||
|
||||
**Alignment Requirements:** Same as loads
|
||||
|
||||
### Immediate Load Instructions
|
||||
|
||||
```asm
|
||||
lli immediate, dest_reg ; Load lower 16 bits (CLEARS upper 16!)
|
||||
lui immediate, dest_reg ; Load upper 16 bits (preserves lower 16)
|
||||
```
|
||||
|
||||
**⚠️ CRITICAL:** `lli` clears the upper 16 bits! Always use `lli` before `lui`.
|
||||
|
||||
**Loading 32-bit Constants:**
|
||||
```asm
|
||||
lli 0x1234, rg0 ; rg0 = 0x00001234
|
||||
lui 0xABCD, rg0 ; rg0 = 0xABCD1234
|
||||
```
|
||||
|
||||
**Loading Addresses:** See `lwi` pseudo-instruction
|
||||
|
||||
### Jump and Branch Instructions
|
||||
|
||||
```asm
|
||||
jmp addr [, offset_reg] ; Unconditional jump
|
||||
jeq addr [, offset_reg] ; Jump if equal
|
||||
jne addr [, offset_reg] ; Jump if not equal
|
||||
jgt addr [, offset_reg] ; Jump if greater than
|
||||
jge addr [, offset_reg] ; Jump if greater or equal
|
||||
jlt addr [, offset_reg] ; Jump if less than
|
||||
jle addr [, offset_reg] ; Jump if less or equal
|
||||
```
|
||||
|
||||
**Jump Modes:**
|
||||
```asm
|
||||
; Absolute jump (using zero register)
|
||||
jmp label, zero ; Jump to label address
|
||||
jmp 0x4000, zero ; Jump to absolute address 0x4000
|
||||
|
||||
; Register-based jump
|
||||
jmp 0, ret ; Jump to address in ret register
|
||||
jmp 4, ret ; Jump to (ret + 4)
|
||||
|
||||
; PC-relative (if assembler supports)
|
||||
jeq loop_start ; Jump to loop_start if equal flag set
|
||||
```
|
||||
|
||||
**Conditional Jumps:** Based on flags set by `cmp` instruction
|
||||
|
||||
### Comparison
|
||||
|
||||
```asm
|
||||
cmp reg1, reg2 ; Compare reg1 with reg2, set flags
|
||||
```
|
||||
|
||||
**Flags Set:**
|
||||
- Equal: `reg1 == reg2`
|
||||
- GreaterThan: `reg1 > reg2`
|
||||
- LessThan: `reg1 < reg2`
|
||||
- GreaterThanOrEqual: `reg1 >= reg2`
|
||||
- LessThanOrEqual: `reg1 <= reg2`
|
||||
|
||||
**Example:**
|
||||
```asm
|
||||
cmp rg0, zero ; Compare rg0 with 0
|
||||
jeq is_zero ; Branch if rg0 == 0
|
||||
jgt is_positive ; Branch if rg0 > 0
|
||||
jlt is_negative ; Branch if rg0 < 0
|
||||
```
|
||||
|
||||
### Arithmetic Instructions
|
||||
|
||||
```asm
|
||||
add src1, src2, dest ; dest = src1 + src2
|
||||
sub src1, src2, dest ; dest = src1 - src2
|
||||
iadd src, immediate, dest ; dest = src + immediate
|
||||
isub src, immediate, dest ; dest = src - immediate
|
||||
inc reg ; reg = reg + 1
|
||||
dec reg ; reg = reg - 1
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
add rg0, rg1, rg2 ; rg2 = rg0 + rg1
|
||||
sub rg0, rg1, rg2 ; rg2 = rg0 - rg1
|
||||
iadd rg0, 10, rg0 ; rg0 = rg0 + 10
|
||||
isub rg1, 5, rg2 ; rg2 = rg1 - 5
|
||||
inc spr ; spr = spr + 1
|
||||
dec spr ; spr = spr - 1
|
||||
```
|
||||
|
||||
**Note:** For `iadd`/`isub`, destination can be the same as source for in-place operations.
|
||||
|
||||
### Bitwise Logical Operations
|
||||
|
||||
```asm
|
||||
and src1, src2, dest ; dest = src1 & src2
|
||||
or src1, src2, dest ; dest = src1 | src2
|
||||
xor src1, src2, dest ; dest = src1 ^ src2
|
||||
not src, dest ; dest = ~src
|
||||
nand src1, src2, dest ; dest = ~(src1 & src2)
|
||||
nor src1, src2, dest ; dest = ~(src1 | src2)
|
||||
xnor src1, src2, dest ; dest = ~(src1 ^ src2)
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
and rg0, rg1, rg2 ; rg2 = rg0 & rg1
|
||||
or rg0, rg1, rg2 ; rg2 = rg0 | rg1
|
||||
not rg0, rg1 ; rg1 = ~rg0
|
||||
xor rg0, rg0, rg0 ; rg0 = 0 (XOR register with itself)
|
||||
```
|
||||
|
||||
### Shift Operations
|
||||
|
||||
```asm
|
||||
shl reg, shift_amount ; Shift left by amount (0-31)
|
||||
shr reg, shift_amount ; Shift right by amount (0-31)
|
||||
```
|
||||
|
||||
**Shift Amount:**
|
||||
- Can be a literal: `shl rg0, 2` (shift by 2)
|
||||
- Can be a register: `shl rg0, rg1` (shift by value in rg1, uses low 5 bits)
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
shl rg0, 2 ; rg0 = rg0 << 2
|
||||
shr rg1, 3 ; rg1 = rg1 >> 3
|
||||
shl rg0, rg1 ; rg0 = rg0 << (rg1 & 0x1F)
|
||||
```
|
||||
|
||||
**Note:** Shift right is logical (zero-fill), not arithmetic
|
||||
|
||||
### System and Control Instructions
|
||||
|
||||
```asm
|
||||
hlt ; Halt processor
|
||||
nop ; No operation
|
||||
int interrupt_code ; Trigger interrupt (8-bit code)
|
||||
irt ; Return from interrupt
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
hlt ; Stop execution
|
||||
nop ; Do nothing (timing/alignment)
|
||||
int 0x21 ; Trigger interrupt 0x21
|
||||
irt ; Return from interrupt handler
|
||||
```
|
||||
|
||||
## Pseudo-Instructions
|
||||
|
||||
Pseudo-instructions are assembly-level constructs that expand into one or more hardware instructions.
|
||||
|
||||
### Data Definition Directives
|
||||
|
||||
```asm
|
||||
db label: value1 [, value2, ...] ; Define bytes
|
||||
dh label: value1 [, value2, ...] ; Define halfwords (16-bit)
|
||||
dw label: value1 [, value2, ...] ; Define words (32-bit)
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
db message: "Hello, World!", 0 ; String with null terminator
|
||||
db bytes: 0x01, 0x02, 0x03 ; Array of bytes
|
||||
dh numbers: 1000, 2000, 3000 ; Array of halfwords
|
||||
dw stack_base: 0x10000 ; Single word value
|
||||
dw table: 0, 0, 0, 0 ; Array of 4 words
|
||||
```
|
||||
|
||||
**String Encoding:** Strings are encoded as byte sequences with escape sequences:
|
||||
- `\n` = newline (0x0A)
|
||||
- `\t` = tab (0x09)
|
||||
- `\r` = carriage return (0x0D)
|
||||
- `\\` = backslash
|
||||
- `\"` = double quote
|
||||
- `\0` = null (0x00)
|
||||
|
||||
### Memory Reservation Directives
|
||||
|
||||
```asm
|
||||
resb label: size ; Reserve 'size' bytes
|
||||
resh label: size ; Reserve 'size' halfwords
|
||||
resw label: size ; Reserve 'size' words
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
resb buffer: 256 ; Reserve 256 bytes
|
||||
resh array: 100 ; Reserve 100 halfwords (200 bytes)
|
||||
resw heap: 1024 ; Reserve 1024 words (4096 bytes)
|
||||
```
|
||||
|
||||
**Note:** Reserved memory is uninitialized (contents undefined).
|
||||
|
||||
### Stack Operations
|
||||
|
||||
```asm
|
||||
push reg ; Push register onto stack
|
||||
pop reg ; Pop stack into register
|
||||
```
|
||||
|
||||
**Expansion:**
|
||||
```asm
|
||||
; push rg0 expands to:
|
||||
iadd spr, 4, spr ; spr = spr + 4 (stack grows up)
|
||||
stw rg0, spr, 0 ; Store rg0 to [spr]
|
||||
|
||||
; pop rg0 expands to:
|
||||
ldw spr, rg0, 0 ; Load [spr] into rg0
|
||||
isub spr, 4, spr ; spr = spr - 4
|
||||
```
|
||||
|
||||
**Note:** DSA stack grows upward (toward higher addresses).
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
push rg0 ; Save rg0 on stack
|
||||
push rg1 ; Save rg1 on stack
|
||||
; ... do work ...
|
||||
pop rg1 ; Restore rg1
|
||||
pop rg0 ; Restore rg0
|
||||
```
|
||||
|
||||
### Load Address Pseudo-Instruction
|
||||
|
||||
```asm
|
||||
lwi label, dest_reg ; Load address of label into register
|
||||
```
|
||||
|
||||
**Expansion:**
|
||||
```asm
|
||||
; lwi message, rg0 expands to:
|
||||
lli message, rg0 ; Load lower 16 bits of address
|
||||
lui message, rg0 ; Load upper 16 bits of address
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```asm
|
||||
db message: "Hello!", 0
|
||||
|
||||
lwi message, rg0 ; rg0 = address of message
|
||||
ldb rg0, rg1 ; rg1 = first byte of message ('H')
|
||||
```
|
||||
|
||||
### Memory Access with Labels
|
||||
|
||||
Load and store instructions can use labels directly:
|
||||
|
||||
```asm
|
||||
ldb label, dest_reg [, offset]
|
||||
ldh label, dest_reg [, offset]
|
||||
ldw label, dest_reg [, offset]
|
||||
stb src_reg, label [, offset]
|
||||
sth src_reg, label [, offset]
|
||||
stw src_reg, label [, offset]
|
||||
```
|
||||
|
||||
**Expansion (uses rgf as scratch):**
|
||||
```asm
|
||||
; ldb buffer, rg2 expands to:
|
||||
lli buffer, rgf ; Load lower 16 bits of buffer address
|
||||
lui buffer, rgf ; Load upper 16 bits of buffer address
|
||||
ldb rgf, rg2, 0 ; Load byte from address in rgf
|
||||
|
||||
; stw rg1, current expands to:
|
||||
lli current, rgf ; Load lower 16 bits of current address
|
||||
lui current, rgf ; Load upper 16 bits of current address
|
||||
stw rg1, rgf, 0 ; Store word to address in rgf
|
||||
```
|
||||
|
||||
**⚠️ Important:** These pseudo-instructions use `rgf` as a scratch register! Do not use `rgf` for other purposes when using label-based memory access.
|
||||
|
||||
**Examples:**
|
||||
```asm
|
||||
dw counter: 0
|
||||
|
||||
ldw counter, rg0 ; Load value of counter
|
||||
iadd rg0, 1, rg0 ; Increment
|
||||
stw rg0, counter ; Store back
|
||||
```
|
||||
|
||||
### Function Call Pseudo-Instructions
|
||||
|
||||
```asm
|
||||
call namespace::function ; Call function from included module
|
||||
return ; Return from function
|
||||
```
|
||||
|
||||
**Expansion:**
|
||||
```asm
|
||||
; call print::print expands to:
|
||||
lwi print::print, ret ; Load function address into ret
|
||||
jmp 0, ret ; Jump to function (saves return in pcx)
|
||||
; (The assembler/linker resolves namespace::function to address)
|
||||
|
||||
; return expands to:
|
||||
jmp 0, ret ; Jump to address in ret register
|
||||
```
|
||||
|
||||
**Note:** The actual return address handling may be more complex depending on the calling convention.
|
||||
|
||||
### Module System
|
||||
|
||||
```asm
|
||||
include namespace "path/to/file.dsa"
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```asm
|
||||
include print "lib/print.dsa"
|
||||
include math "lib/math.dsa"
|
||||
|
||||
; Can now call:
|
||||
call print::print
|
||||
call math::multiply
|
||||
```
|
||||
|
||||
**Namespace Resolution:**
|
||||
- Functions in included modules are accessible via `namespace::label`
|
||||
- Namespace is the identifier before the filename
|
||||
- Labels in included files are prefixed with the namespace
|
||||
|
||||
## Calling Convention
|
||||
|
||||
DSA uses a standard calling convention for function calls.
|
||||
|
||||
### Stack Frame Layout
|
||||
|
||||
```
|
||||
Higher Addresses
|
||||
├─────────────┤
|
||||
│ Arg N │ ← spr + (8 + 4*(N-1))
|
||||
│ ... │
|
||||
│ Arg 2 │ ← spr + 16
|
||||
│ Arg 1 │ ← spr + 12
|
||||
│ Arg 0 │ ← spr + 8 (first argument)
|
||||
├─────────────┤
|
||||
│ Ret Addr │ ← spr + 4 (return address)
|
||||
├─────────────┤
|
||||
│ Old BPR │ ← spr + 0 (saved base pointer)
|
||||
├─────────────┤ ← bpr, spr (current frame)
|
||||
│ Locals │ (local variables, if any)
|
||||
Lower Addresses
|
||||
```
|
||||
|
||||
### Calling Sequence
|
||||
|
||||
**Caller Responsibilities:**
|
||||
|
||||
1. **Push arguments in reverse order** (last argument first):
|
||||
```asm
|
||||
push arg2
|
||||
push arg1
|
||||
push arg0
|
||||
```
|
||||
|
||||
2. **Call the function:**
|
||||
```asm
|
||||
call namespace::function
|
||||
```
|
||||
|
||||
3. **Clean up arguments** after return:
|
||||
```asm
|
||||
pop zero ; Discard or retrieve arg0
|
||||
pop zero ; Discard arg1
|
||||
pop zero ; Discard arg2
|
||||
```
|
||||
|
||||
**Callee Responsibilities:**
|
||||
|
||||
1. **Set up stack frame:**
|
||||
```asm
|
||||
function:
|
||||
push bpr ; Save old base pointer
|
||||
mov spr, bpr ; Establish new base pointer
|
||||
```
|
||||
|
||||
2. **Access arguments:**
|
||||
```asm
|
||||
ldw bpr, rg0, 8 ; Load arg0 from spr+8
|
||||
ldw bpr, rg1, 12 ; Load arg1 from spr+12
|
||||
ldw bpr, rg2, 16 ; Load arg2 from spr+16
|
||||
```
|
||||
|
||||
3. **Execute function body:**
|
||||
```asm
|
||||
; Function logic here
|
||||
add rg0, rg1, acc ; Example: acc = arg0 + arg1
|
||||
```
|
||||
|
||||
4. **Store return value** (optional, overwrites arg0):
|
||||
```asm
|
||||
stw acc, bpr, 8 ; Store result where arg0 was
|
||||
```
|
||||
|
||||
5. **Restore stack frame:**
|
||||
```asm
|
||||
mov bpr, spr ; Restore stack pointer
|
||||
pop bpr ; Restore old base pointer
|
||||
```
|
||||
|
||||
6. **Return to caller:**
|
||||
```asm
|
||||
return
|
||||
```
|
||||
|
||||
### Complete Example
|
||||
|
||||
```asm
|
||||
; Function: add two numbers
|
||||
; Args: arg0, arg1
|
||||
; Returns: sum in arg0 position
|
||||
|
||||
add_function:
|
||||
push bpr ; Save base pointer
|
||||
mov spr, bpr ; Set up stack frame
|
||||
|
||||
ldw bpr, rg0, 8 ; Load arg0
|
||||
ldw bpr, rg1, 12 ; Load arg1
|
||||
add rg0, rg1, acc ; acc = arg0 + arg1
|
||||
|
||||
stw acc, bpr, 8 ; Store result
|
||||
|
||||
mov bpr, spr ; Restore stack
|
||||
pop bpr ; Restore base pointer
|
||||
return
|
||||
|
||||
; Caller:
|
||||
main:
|
||||
lwi stack_base, bpr
|
||||
mov bpr, spr
|
||||
|
||||
lli 5, rg0
|
||||
lli 7, rg1
|
||||
|
||||
push rg1 ; Push arg1 (7)
|
||||
push rg0 ; Push arg0 (5)
|
||||
call local::add_function
|
||||
pop rg2 ; Get result (12)
|
||||
pop zero ; Discard arg1
|
||||
|
||||
hlt
|
||||
|
||||
dw stack_base: 0x10000
|
||||
```
|
||||
|
||||
### Register Usage Conventions
|
||||
|
||||
| Register(s) | Usage | Preserved? |
|
||||
|-------------|-------|------------|
|
||||
| rg0-rg3 | Function arguments, temporaries | No (caller-saved) |
|
||||
| rg4-rge | Local variables | Yes (callee-saved if used) |
|
||||
| rgf | Scratch (used by label addressing) | No |
|
||||
| acc | Temporary calculations | No |
|
||||
| spr | Stack pointer | Yes (must be restored) |
|
||||
| bpr | Base pointer | Yes (must be restored) |
|
||||
| ret | Return address | Managed by call/return |
|
||||
|
||||
**Notes:**
|
||||
- Functions should save and restore rg4-rge if they use them
|
||||
- rg0-rg3 may be overwritten by called functions
|
||||
- acc and rgf are volatile - assume they're overwritten
|
||||
|
||||
## Complete Examples
|
||||
|
||||
### Example 1: Multiplication Library
|
||||
|
||||
```asm
|
||||
// multiply.dsa
|
||||
// Multiplies two numbers using repeated addition
|
||||
//
|
||||
// Usage:
|
||||
// include multiply "multiply.dsa"
|
||||
// push arg1
|
||||
// push arg0
|
||||
// call multiply::multiply
|
||||
// pop result
|
||||
// pop zero ; discard second argument
|
||||
|
||||
multiply:
|
||||
push bpr
|
||||
mov spr, bpr
|
||||
|
||||
ldw bpr, rg0, 8 ; Load multiplier
|
||||
ldw bpr, rg1, 12 ; Load multiplicand
|
||||
|
||||
lli 0, acc ; Initialize result to 0
|
||||
|
||||
loop_start:
|
||||
add acc, rg0, acc ; acc += multiplier
|
||||
dec rg1 ; multiplicand--
|
||||
|
||||
cmp rg1, zero
|
||||
jgt loop_start ; Continue if multiplicand > 0
|
||||
|
||||
stw acc, bpr, 8 ; Store result for caller
|
||||
|
||||
mov bpr, spr
|
||||
pop bpr
|
||||
return
|
||||
```
|
||||
|
||||
### Example 2: Print Library
|
||||
|
||||
```asm
|
||||
// print.dsa
|
||||
// Prints null-terminated string to display memory
|
||||
//
|
||||
// Usage:
|
||||
// include print "print.dsa"
|
||||
//
|
||||
// push string_address
|
||||
// call print::print
|
||||
// pop zero
|
||||
//
|
||||
// call print::reset ; Reset cursor (no args)
|
||||
|
||||
dw display: 0x20000 ; Display memory base address
|
||||
dw current: 0x20000 ; Current cursor position
|
||||
|
||||
// Print function
|
||||
print:
|
||||
push bpr
|
||||
mov spr, bpr
|
||||
|
||||
ldw bpr, rg0, 8 ; Get string address argument
|
||||
ldw current, rg1 ; Get current cursor position
|
||||
|
||||
print_loop:
|
||||
ldb rg0, acc ; Load character
|
||||
stb acc, rg1 ; Store to display
|
||||
|
||||
iadd rg0, 1, rg0 ; Advance string pointer
|
||||
iadd rg1, 1, rg1 ; Advance cursor
|
||||
|
||||
cmp acc, zero ; Check for null terminator
|
||||
jne print_loop ; Continue if not null
|
||||
|
||||
stw rg1, current ; Save cursor position
|
||||
|
||||
mov bpr, spr
|
||||
pop bpr
|
||||
return
|
||||
|
||||
// Reset cursor function
|
||||
reset:
|
||||
push bpr
|
||||
mov spr, bpr
|
||||
|
||||
ldw display, rg1 ; Load display base
|
||||
stw rg1, current ; Reset cursor to start
|
||||
|
||||
mov bpr, spr
|
||||
pop bpr
|
||||
return
|
||||
```
|
||||
|
||||
### Example 3: Main Program
|
||||
|
||||
```asm
|
||||
// main.dsa
|
||||
// Demonstrates using included libraries
|
||||
|
||||
include print "./print.dsa"
|
||||
|
||||
dw stack: 0x10000
|
||||
db string: "'To confuse your enemy, you must first confuse yourself' - Probably Sun Tzu.", 0
|
||||
|
||||
init:
|
||||
// Set up stack
|
||||
ldw stack, bpr
|
||||
mov bpr, spr
|
||||
|
||||
start:
|
||||
// Load string address
|
||||
lwi string, rg1
|
||||
|
||||
// Call print function
|
||||
push rg1
|
||||
call print::print
|
||||
pop rg1 ; Clean up (rg1 now contains arg we passed)
|
||||
|
||||
hlt
|
||||
```
|
||||
|
||||
### Example 4: Conditional Logic
|
||||
|
||||
```asm
|
||||
// Demonstrates comparisons and branching
|
||||
|
||||
dw value: 42
|
||||
|
||||
main:
|
||||
ldw value, rg0
|
||||
|
||||
cmp rg0, zero
|
||||
jeq is_zero
|
||||
jgt is_positive
|
||||
jlt is_negative
|
||||
|
||||
is_zero:
|
||||
// Handle zero case
|
||||
lwi zero_msg, rg1
|
||||
jmp print_and_exit
|
||||
|
||||
is_positive:
|
||||
// Handle positive case
|
||||
lwi positive_msg, rg1
|
||||
jmp print_and_exit
|
||||
|
||||
is_negative:
|
||||
// Handle negative case
|
||||
lwi negative_msg, rg1
|
||||
jmp print_and_exit
|
||||
|
||||
print_and_exit:
|
||||
push rg1
|
||||
call print::print
|
||||
pop zero
|
||||
hlt
|
||||
|
||||
db zero_msg: "Value is zero", 0
|
||||
db positive_msg: "Value is positive", 0
|
||||
db negative_msg: "Value is negative", 0
|
||||
```
|
||||
|
||||
### Example 5: Loop with Counter
|
||||
|
||||
```asm
|
||||
// Count from 0 to 9
|
||||
|
||||
dw stack: 0x10000
|
||||
|
||||
main:
|
||||
ldw stack, bpr
|
||||
mov bpr, spr
|
||||
|
||||
lli 0, rg0 ; Counter = 0
|
||||
lli 10, rg1 ; Limit = 10
|
||||
|
||||
loop:
|
||||
// Do something with counter in rg0
|
||||
push rg0
|
||||
call process_value
|
||||
pop zero
|
||||
|
||||
inc rg0 ; Counter++
|
||||
cmp rg0, rg1 ; Compare with limit
|
||||
jlt loop ; Loop if counter < limit
|
||||
|
||||
hlt
|
||||
|
||||
process_value:
|
||||
push bpr
|
||||
mov spr, bpr
|
||||
|
||||
ldw bpr, rg0, 8 ; Get value
|
||||
; Process value here...
|
||||
|
||||
mov bpr, spr
|
||||
pop bpr
|
||||
return
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Stack Management
|
||||
- Always balance push/pop operations
|
||||
- Set up stack frame in every function
|
||||
- Clean up arguments after function calls
|
||||
- Use `pop zero` to discard unwanted values
|
||||
|
||||
### 2. Register Usage
|
||||
- Don't rely on `acc` being preserved
|
||||
- Don't use `rgf` for variables (used by label addressing)
|
||||
- Save callee-saved registers if you modify them
|
||||
- Use `zero` register for zero constants
|
||||
|
||||
### 3. Memory Access
|
||||
- Ensure proper alignment for halfword/word access
|
||||
- Use label-based addressing for clearer code
|
||||
- Check that labels are defined before use
|
||||
|
||||
### 4. Function Design
|
||||
- Document calling convention in comments
|
||||
- Validate input arguments when appropriate
|
||||
- Use consistent parameter order
|
||||
- Return values via stack or designated register
|
||||
|
||||
### 5. Code Organization
|
||||
- Use meaningful label names
|
||||
- Comment complex operations
|
||||
- Group related functions in modules
|
||||
- Use includes for code reuse
|
||||
|
||||
### 6. Performance
|
||||
- Minimize memory accesses (use registers)
|
||||
- Avoid unnecessary comparisons
|
||||
- Use shifts for multiplication/division by powers of 2
|
||||
- Consider instruction pipelining if supported
|
||||
|
||||
## Assembler Directives
|
||||
|
||||
### Alignment (if supported)
|
||||
```asm
|
||||
.align 4 ; Align to 4-byte boundary
|
||||
.align 2 ; Align to 2-byte boundary
|
||||
```
|
||||
|
||||
### Origin (if supported)
|
||||
```asm
|
||||
.org 0x1000 ; Set location counter to 0x1000
|
||||
```
|
||||
|
||||
### Section Control (if supported)
|
||||
```asm
|
||||
.text ; Code section
|
||||
.data ; Data section
|
||||
.bss ; Uninitialized data section
|
||||
```
|
||||
|
||||
**Note:** Assembler directive support depends on the specific DSA assembler implementation.
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Loading 32-bit Constants
|
||||
```asm
|
||||
lli lower_16_bits, reg
|
||||
lui upper_16_bits, reg
|
||||
```
|
||||
|
||||
### Zero a Register
|
||||
```asm
|
||||
mov zero, reg ; Method 1
|
||||
xor reg, reg, reg ; Method 2
|
||||
lli 0, reg ; Method 3
|
||||
```
|
||||
|
||||
### Copy Memory
|
||||
```asm
|
||||
ldw src_addr, rg0 ; Load from source
|
||||
stw rg0, dest_addr ; Store to destination
|
||||
```
|
||||
|
||||
### Multiply by Power of 2
|
||||
```asm
|
||||
shl reg, 3 ; Multiply by 8 (2^3)
|
||||
```
|
||||
|
||||
### Divide by Power of 2
|
||||
```asm
|
||||
shr reg, 2 ; Divide by 4 (2^2)
|
||||
```
|
||||
|
||||
### Boolean NOT
|
||||
```asm
|
||||
cmp reg, zero
|
||||
jeq was_zero ; If reg == 0, result is 1
|
||||
lli 0, reg
|
||||
jmp done
|
||||
was_zero:
|
||||
lli 1, reg
|
||||
done:
|
||||
```
|
||||
|
||||
### Min/Max
|
||||
```asm
|
||||
; max(rg0, rg1) -> rg2
|
||||
mov rg0, rg2 ; Assume rg0 is max
|
||||
cmp rg0, rg1
|
||||
jge done
|
||||
mov rg1, rg2 ; rg1 was larger
|
||||
done:
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Alignment Fault:**
|
||||
- Check that halfword loads/stores use even addresses
|
||||
- Check that word loads/stores use addresses divisible by 4
|
||||
|
||||
**Illegal Instruction:**
|
||||
- Verify opcode is valid
|
||||
- Check that shift amount is 0 for non-shift instructions
|
||||
- Ensure you're not using `noreg` as a source/destination
|
||||
|
||||
**Stack Corruption:**
|
||||
- Verify push/pop balance
|
||||
- Check that functions restore `bpr` before returning
|
||||
- Ensure caller cleans up arguments
|
||||
|
||||
**Wrong Results:**
|
||||
- Verify `lli` is called before `lui` when loading constants
|
||||
- Check that you're not relying on `acc` or `rgf` being preserved
|
||||
- Verify signed vs. unsigned loads (ldb vs. ldbs)
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
1. Add `nop` instructions as breakpoint markers
|
||||
2. Print register values using display memory
|
||||
3. Use single-step execution to trace program flow
|
||||
4. Verify stack pointer values at function boundaries
|
||||
5. Check label addresses in disassembly
|
||||
|
||||
## Appendix: Instruction Quick Reference
|
||||
|
||||
| Category | Instructions |
|
||||
|----------|-------------|
|
||||
| **Data Movement** | mov, movs |
|
||||
| **Memory Load** | ldb, ldbs, ldh, ldhs, ldw |
|
||||
| **Memory Store** | stb, sth, stw |
|
||||
| **Immediate Load** | lli, lui |
|
||||
| **Jump/Branch** | jmp, jeq, jne, jgt, jge, jlt, jle |
|
||||
| **Comparison** | cmp |
|
||||
| **Arithmetic** | add, sub, iadd, isub, inc, dec |
|
||||
| **Logical** | and, or, xor, not, nand, nor, xnor |
|
||||
| **Shift** | shl, shr |
|
||||
| **System** | hlt, nop, int, irt |
|
||||
| **Pseudo** | db, dh, dw, resb, resh, resw, push, pop, lwi, call, return, include |
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0** - Initial comprehensive reference
|
||||
- Combined hardware instructions and pseudo-instructions
|
||||
- Added complete calling convention
|
||||
- Included practical examples
|
||||
- Documented common patterns and best practices
|
||||
@@ -0,0 +1,401 @@
|
||||
# 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<br/>⚠️ 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<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 |
|
||||
| 0x17 | **noreg** | Placeholder | Indicates unused register field<br/>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<br/>⚠️ **CLEARS upper 16 bits!** |
|
||||
| 0x0C | **LUI** | I | DestReg, Value | Load 16-bit value into upper 16 bits<br/>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<br/>Zero-fill from right |
|
||||
| 0x18 | **SHR** | R | Reg, ShiftAmount | Shift Reg right by ShiftAmount bits<br/>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<br/>Saves return address to ret register<br/>Sets bpr to kernel stack |
|
||||
| 0x23 | **IRT** | R | - | Return from interrupt<br/>Restores execution context |
|
||||
| 0x24 | **HLT** | R | - | Halt processor execution<br/>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<br/>- noreg used as source/destination<br/>- ShiftAmt non-zero for non-shift instruction<br/>- Register field violations |
|
||||
| **Protection Fault** | - Write to pcx register<br/>- Read/write idr or mmr in user mode<br/>- Read from noreg<br/>- Write to zero register (discarded, no fault) |
|
||||
| **Alignment Fault** | - LDH/LDHS/STH with odd address<br/>- LDW/STW with address not divisible by 4 |
|
||||
| **Memory Access Violation** | - Access to unmapped or protected memory<br/>- 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
|
||||
@@ -0,0 +1,875 @@
|
||||
# DSA Project Roadmap & Task Breakdown
|
||||
|
||||
> **Damn Simple Architecture** — Full ecosystem development plan including emulator, assembler, compiler, debugger, and tooling infrastructure.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Phase 1: Foundation & Core Infrastructure](#phase-1-foundation--core-infrastructure)
|
||||
- [1.1 Binary Format & Linking System](#11-binary-format--linking-system)
|
||||
- [1.2 Assembler Rewrite](#12-assembler-rewrite)
|
||||
- [1.3 Documentation Updates](#13-documentation-updates)
|
||||
2. [Phase 2: Compiler Development](#phase-2-compiler-development)
|
||||
- [2.1 Language Design & Implementation](#21-language-design--implementation)
|
||||
- [2.2 Standard Library](#22-standard-library)
|
||||
3. [Phase 3: Build System & Package Management](#phase-3-build-system--package-management)
|
||||
- [3.1 Build System](#31-build-system)
|
||||
- [3.2 Package Management System](#32-package-management-system)
|
||||
4. [Phase 4: Debugger & Development Tools](#phase-4-debugger--development-tools)
|
||||
- [4.1 Debug Symbol System](#41-debug-symbol-system)
|
||||
- [4.2 Debugger Implementation](#42-debugger-implementation)
|
||||
- [4.3 Enhanced Editor Integration](#43-enhanced-editor-integration)
|
||||
5. [Phase 5: Integration & Polish](#phase-5-integration--polish)
|
||||
6. [Phase 6: Future Enhancements (NTH)](#phase-6-future-enhancements-nth)
|
||||
7. [Summary Timeline](#summary-timeline)
|
||||
8. [Critical Path](#critical-path)
|
||||
9. [Recommended Work Order](#recommended-work-order)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Foundation & Core Infrastructure
|
||||
|
||||
**Estimated Duration: 3–4 weeks**
|
||||
|
||||
---
|
||||
|
||||
### 1.1 Binary Format & Linking System
|
||||
|
||||
> **Priority: CRITICAL** — Everything depends on this.
|
||||
> **Total Estimate: 1.5 weeks**
|
||||
|
||||
---
|
||||
|
||||
#### 1.1.1 Design New Binary Format Specification
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** None
|
||||
**Deliverable:** `docs/binary-format-spec.md`
|
||||
|
||||
- [ ] Research existing object file formats (ELF, COFF, Mach-O) for inspiration
|
||||
- [ ] Design `.dsb` object file format specification
|
||||
- [ ] Symbol table structure
|
||||
- [ ] Relocation table format
|
||||
- [ ] Section definitions (code, data, rodata, bss)
|
||||
- [ ] Debug information structure
|
||||
- [ ] Metadata headers
|
||||
- [ ] Design `.dse` executable format specification
|
||||
- [ ] Entry point definition
|
||||
- [ ] Memory layout requirements
|
||||
- [ ] Linking metadata
|
||||
- [ ] Document format specifications in markdown
|
||||
- [ ] Create format version strategy for future compatibility
|
||||
|
||||
---
|
||||
|
||||
#### 1.1.2 Implement DSB Object File Writer
|
||||
|
||||
**Estimate: 3 days**
|
||||
**Dependencies:** 1.1.1
|
||||
**Deliverable:** `dsa-binary-format` crate v0.1.0
|
||||
|
||||
- [ ] Create new crate: `dsa-binary-format`
|
||||
- [ ] Implement object file structures
|
||||
- [ ] Header structure
|
||||
- [ ] Symbol table builder
|
||||
- [ ] Section manager
|
||||
- [ ] Relocation entry creator
|
||||
- [ ] Write serialization logic
|
||||
- [ ] Add validation and error handling
|
||||
- [ ] Write unit tests for each structure
|
||||
- [ ] Integration tests for complete object files
|
||||
|
||||
---
|
||||
|
||||
#### 1.1.3 Build Linker Program
|
||||
|
||||
**Estimate: 4 days**
|
||||
**Dependencies:** 1.1.2
|
||||
**Deliverable:** `dsa-link` executable
|
||||
|
||||
- [ ] Create new crate: `dsa-linker`
|
||||
- [ ] Implement symbol resolution
|
||||
- [ ] Global symbol table
|
||||
- [ ] Symbol conflict detection
|
||||
- [ ] Weak symbol handling
|
||||
- [ ] Implement relocation processing
|
||||
- [ ] Address calculation
|
||||
- [ ] Patch generation
|
||||
- [ ] Cross-section references
|
||||
- [ ] Build executable generator
|
||||
- [ ] Combine sections
|
||||
- [ ] Generate final memory layout
|
||||
- [ ] Write `.dse` output
|
||||
- [ ] Add linker script support (basic)
|
||||
- [ ] Comprehensive error messages
|
||||
- [ ] Test suite with complex linking scenarios
|
||||
|
||||
---
|
||||
|
||||
### 1.2 Assembler Rewrite
|
||||
|
||||
> **Priority: HIGH** — Required for all compiled code.
|
||||
> **Total Estimate: 1.5 weeks**
|
||||
|
||||
---
|
||||
|
||||
#### 1.2.1 Assembler Architecture Design
|
||||
|
||||
**Estimate: 1 day**
|
||||
**Dependencies:** 1.1.1
|
||||
**Deliverable:** `docs/assembler-architecture.md`
|
||||
|
||||
- [ ] Design multi-pass architecture
|
||||
- [ ] Pass 1: Symbol collection
|
||||
- [ ] Pass 2: Macro expansion
|
||||
- [ ] Pass 3: Code generation
|
||||
- [ ] Pass 4: Relocation generation
|
||||
- [ ] Plan error handling strategy
|
||||
- [ ] Design threading model for parallel file processing
|
||||
- [ ] Define module/import resolution system
|
||||
- [ ] Plan integration points with DSC compiler
|
||||
|
||||
---
|
||||
|
||||
#### 1.2.2 Implement Core Assembler
|
||||
|
||||
**Estimate: 5 days**
|
||||
**Dependencies:** 1.1.2, 1.2.1
|
||||
**Deliverable:** `dsa-asm` executable v2.0.0
|
||||
|
||||
- [ ] Create new crate: `dsa-assembler-ng` (next-gen)
|
||||
- [ ] Implement lexer with better error recovery
|
||||
- [ ] Build parser with detailed error messages
|
||||
- [ ] Instruction parsing
|
||||
- [ ] Directive handling
|
||||
- [ ] Macro system
|
||||
- [ ] Include resolution
|
||||
- [ ] Symbol table management
|
||||
- [ ] Code generator outputting to DSB format
|
||||
- [ ] Multi-threading for file parsing
|
||||
- [ ] Comprehensive test suite
|
||||
- [ ] Error message testing
|
||||
|
||||
---
|
||||
|
||||
#### 1.2.3 Import System & DSC Integration
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 1.2.2, 2.1.2
|
||||
**Deliverable:** Working import system
|
||||
|
||||
- [ ] Design import protocol between DSC and assembler
|
||||
- [ ] Implement symbol table merging
|
||||
- [ ] Handle pre-compiled object imports
|
||||
- [ ] Test DSC → Assembly → Object pipeline
|
||||
- [ ] Document integration process
|
||||
|
||||
---
|
||||
|
||||
### 1.3 Documentation Updates
|
||||
|
||||
> **Priority: MEDIUM** — Can be done alongside development.
|
||||
> **Total Estimate: 3 days (distributed)**
|
||||
|
||||
---
|
||||
|
||||
#### 1.3.1 Update Assembly Documentation
|
||||
|
||||
**Estimate: 1 day**
|
||||
**Dependencies:** 1.2.2
|
||||
**Deliverable:** Updated `docs/dsa-assembly-reference.md`
|
||||
|
||||
- [ ] Review all instruction documentation
|
||||
- [ ] Document new pseudo-instructions
|
||||
- [ ] Update calling convention docs
|
||||
- [ ] Add examples for new features
|
||||
- [ ] Document assembler directives
|
||||
- [ ] Macro system documentation
|
||||
|
||||
---
|
||||
|
||||
#### 1.3.2 Architecture Documentation
|
||||
|
||||
**Estimate: 1 day**
|
||||
**Dependencies:** None (can start anytime)
|
||||
**Deliverable:** `docs/dsa-architecture.md`
|
||||
|
||||
- [ ] Document ISA specification
|
||||
- [ ] Memory model documentation
|
||||
- [ ] Interrupt handling
|
||||
- [ ] Hardware peripheral specs
|
||||
- [ ] Timing/performance characteristics
|
||||
|
||||
---
|
||||
|
||||
#### 1.3.3 Build Tools Documentation
|
||||
|
||||
**Estimate: 1 day**
|
||||
**Dependencies:** 1.2.2, 1.1.3, 3.1.2
|
||||
**Deliverable:** `docs/build-tools-guide.md`
|
||||
|
||||
- [ ] Assembler usage guide
|
||||
- [ ] Linker usage guide
|
||||
- [ ] Build system guide
|
||||
- [ ] Tutorial: Building a simple program
|
||||
- [ ] Tutorial: Multi-file projects
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Compiler Development
|
||||
|
||||
**Estimated Duration: 3–4 weeks**
|
||||
|
||||
---
|
||||
|
||||
### 2.1 Language Design & Implementation
|
||||
|
||||
> **Priority: HIGH** — Core functionality.
|
||||
> **Total Estimate: 2.5 weeks**
|
||||
|
||||
---
|
||||
|
||||
#### 2.1.1 Language Syntax Design
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** None
|
||||
**Deliverable:** `docs/language-spec.md`
|
||||
|
||||
- [x] Define syntax goals (simplicity, systems programming)
|
||||
- [ ] Design type system
|
||||
- [x] Primitive types
|
||||
- [x] Pointers/references
|
||||
- [ ] Structs
|
||||
- [ ] Arrays
|
||||
- [x] Function types
|
||||
- [x] Control flow syntax
|
||||
- [x] Function declaration syntax
|
||||
- [x] Module/import system
|
||||
- [x] Operator precedence
|
||||
- [ ] Write EBNF grammar
|
||||
- [x] Create example programs
|
||||
|
||||
---
|
||||
|
||||
#### 2.1.2 Lexer & Parser Implementation
|
||||
|
||||
**Estimate: 4 days**
|
||||
**Dependencies:** 2.1.1
|
||||
**Deliverable:** Parser in `dsc-compiler` crate
|
||||
|
||||
- [x] Adapt existing C lexer to new syntax
|
||||
- [ ] Implement new parser for designed syntax
|
||||
- [ ] Array syntax
|
||||
- [ ] Struct syntax
|
||||
- [x] Pointer syntax
|
||||
- [ ] Namespaced call syntax
|
||||
- [x] AST node definitions
|
||||
- [ ] Error recovery mechanisms
|
||||
- [ ] Comprehensive parser tests
|
||||
- [ ] Syntax error message quality testing
|
||||
- [ ] 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)
|
||||
|
||||
---
|
||||
|
||||
#### 2.1.3 Code Generation Improvements
|
||||
|
||||
**Estimate: 5 days**
|
||||
**Dependencies:** 2.1.2, 1.2.2
|
||||
**Deliverable:** Working code generator
|
||||
|
||||
- [x] Review and fix existing codegen issues
|
||||
- [ ] Implement missing language features
|
||||
- [ ] Structs
|
||||
- [ ] Arrays
|
||||
- [x] Pointers/memory operations
|
||||
- [ ] For loops
|
||||
- [ ] Switch statements
|
||||
- [ ] Break/continue
|
||||
- [ ] Optimize register allocation further
|
||||
- [x] Implement proper function calling conventions
|
||||
- [ ] Add constant folding optimization
|
||||
- [ ] Dead code elimination
|
||||
- [ ] Test each feature thoroughly
|
||||
|
||||
---
|
||||
|
||||
#### 2.1.4 Type Checking & Semantic Analysis
|
||||
|
||||
**Estimate: 3 days**
|
||||
**Dependencies:** 2.1.2
|
||||
**Deliverable:** Type checker integrated in compiler
|
||||
|
||||
- [ ] Implement type checker
|
||||
- [ ] Symbol table for scoping
|
||||
- [ ] Type inference where applicable
|
||||
- [ ] Const checking
|
||||
- [ ] Definite assignment analysis
|
||||
- [ ] Comprehensive semantic error messages
|
||||
- [ ] Test suite for type errors
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Standard Library
|
||||
|
||||
> **Priority: MEDIUM** — Needed for useful programs.
|
||||
> **Total Estimate: 1 week**
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.1 Core Runtime Library (in Assembly)
|
||||
|
||||
**Estimate: 3 days**
|
||||
**Dependencies:** 1.2.2
|
||||
**Deliverable:** `lib/runtime/` directory
|
||||
|
||||
- [ ] Memory allocation (malloc/free)
|
||||
- [ ] String operations
|
||||
- [ ] Math functions
|
||||
- [x] Multiply
|
||||
- [ ] Divide (fix as very slow and broken)
|
||||
- [ ] I/O functions (improved print, read)
|
||||
- [x] Print number
|
||||
- [x] Print hex value
|
||||
- [x] Print word
|
||||
- [x] Print byte
|
||||
- [x] Print from string ptr
|
||||
- [x] Print whitespace and newline
|
||||
- [x] Reset display
|
||||
- [x] Reset cursor
|
||||
- [ ] System call interface
|
||||
- [ ] Tests for each function
|
||||
|
||||
---
|
||||
|
||||
#### 2.2.2 Standard Library (in DSC)
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 2.1.3, 2.2.1
|
||||
**Deliverable:** `lib/std/` directory
|
||||
|
||||
- [ ] String module
|
||||
- [ ] Collections (array utilities, maybe simple list)
|
||||
- [ ] File I/O module
|
||||
- [ ] Math utilities
|
||||
- [ ] Tests and examples
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Build System & Package Management
|
||||
|
||||
**Estimated Duration: 2–3 weeks**
|
||||
|
||||
---
|
||||
|
||||
### 3.1 Build System
|
||||
|
||||
> **Priority: HIGH** — Required for complex projects.
|
||||
> **Total Estimate: 1.5 weeks**
|
||||
|
||||
---
|
||||
|
||||
#### 3.1.1 Build System Design
|
||||
|
||||
**Estimate: 1 day**
|
||||
**Dependencies:** None
|
||||
**Deliverable:** `docs/build-system-design.md`
|
||||
|
||||
- [ ] Define project structure conventions
|
||||
- [ ] Design build manifest format (`dsa-project.toml` or similar)
|
||||
- [ ] Dependency resolution strategy
|
||||
- [ ] Build cache design
|
||||
- [ ] Incremental build strategy
|
||||
- [ ] Multi-target support
|
||||
|
||||
---
|
||||
|
||||
#### 3.1.2 Build Tool Implementation
|
||||
|
||||
**Estimate: 5 days**
|
||||
**Dependencies:** 3.1.1, 1.2.2, 1.1.3, 2.1.3
|
||||
**Deliverable:** `dsa-build` executable
|
||||
|
||||
- [ ] Create crate: `dsa-build`
|
||||
- [ ] Manifest parser
|
||||
- [ ] Dependency graph builder
|
||||
- [ ] Task orchestrator
|
||||
- [ ] Compilation tasks
|
||||
- [ ] Assembly tasks
|
||||
- [ ] Linking tasks
|
||||
- [ ] Build cache implementation
|
||||
- [ ] Parallel build support
|
||||
- [ ] Clean, rebuild commands
|
||||
- [ ] Watch mode for development
|
||||
- [ ] Comprehensive tests
|
||||
|
||||
---
|
||||
|
||||
#### 3.1.3 Project Management Commands
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 3.1.2
|
||||
**Deliverable:** Enhanced `dsa-build` with project management
|
||||
|
||||
- [ ] `dsa new <project>` — Create new project
|
||||
- [ ] `dsa init` — Initialize in existing directory
|
||||
- [ ] `dsa add <dependency>` — Add dependency
|
||||
- [ ] Binary vs library project types
|
||||
- [ ] Template system for project scaffolding
|
||||
- [ ] Documentation for each command
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Package Management System
|
||||
|
||||
> **Priority: MEDIUM** — Enables code sharing.
|
||||
> **Total Estimate: 1.5 weeks**
|
||||
|
||||
---
|
||||
|
||||
#### 3.2.1 Package Registry Design
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 3.1.1
|
||||
**Deliverable:** `docs/package-registry-design.md`
|
||||
|
||||
- [ ] Decide: Git monorepo vs custom hosting
|
||||
- [ ] Design package naming conventions
|
||||
- [ ] Version resolution strategy (semver)
|
||||
- [ ] Package manifest format
|
||||
- [ ] Security considerations
|
||||
- [ ] Package storage format (source/binary/both)
|
||||
- [ ] API design for registry server
|
||||
|
||||
---
|
||||
|
||||
#### 3.2.2 Local Package Manager Tool
|
||||
|
||||
**Estimate: 4 days**
|
||||
**Dependencies:** 3.2.1, 3.1.2
|
||||
**Deliverable:** `dsa-pkg` tool integrated with `dsa-build`
|
||||
|
||||
- [ ] Create crate: `dsa-pkg`
|
||||
- [ ] Package index synchronization
|
||||
- [ ] Dependency resolver
|
||||
- [ ] Package download/cache system
|
||||
- [ ] Integration with build system
|
||||
- [ ] Commands:
|
||||
- [ ] `dsa install <package>`
|
||||
- [ ] `dsa publish`
|
||||
- [ ] `dsa search <query>`
|
||||
- [ ] `dsa update`
|
||||
- [ ] Lock file generation
|
||||
- [ ] Test with mock registry
|
||||
|
||||
---
|
||||
|
||||
#### 3.2.3 Package Registry Implementation
|
||||
|
||||
**Estimate: 3 days**
|
||||
**Dependencies:** 3.2.1
|
||||
**Deliverable:** Package registry (URL or repo)
|
||||
|
||||
- [ ] If **Git monorepo** approach:
|
||||
- [ ] Set up repository structure
|
||||
- [ ] CI/CD for validation
|
||||
- [ ] Submission process
|
||||
- [ ] Package browser website
|
||||
- [ ] If **custom hosting**:
|
||||
- [ ] Simple web server (Rust + Axum/Actix)
|
||||
- [ ] Package upload API
|
||||
- [ ] Package search API
|
||||
- [ ] Basic web UI
|
||||
- [ ] Database for metadata
|
||||
- [ ] Documentation for publishing
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Debugger & Development Tools
|
||||
|
||||
**Estimated Duration: 3–4 weeks**
|
||||
|
||||
---
|
||||
|
||||
### 4.1 Debug Symbol System
|
||||
|
||||
> **Priority: HIGH** — Foundation for debugging.
|
||||
> **Total Estimate: 1 week**
|
||||
|
||||
---
|
||||
|
||||
#### 4.1.1 Debug Symbol Format Design
|
||||
|
||||
**Estimate: 1 day**
|
||||
**Dependencies:** 1.1.1
|
||||
**Deliverable:** `docs/debug-symbol-format.md`
|
||||
|
||||
- [ ] Design symbol table format
|
||||
- [ ] Function addresses → names
|
||||
- [ ] Line number → address mapping
|
||||
- [ ] Variable location information
|
||||
- [ ] Type information
|
||||
- [ ] Define symbol table file format
|
||||
- [ ] Plan for embedding in DSE/DSB files
|
||||
|
||||
---
|
||||
|
||||
#### 4.1.2 Symbol Generation in Tools
|
||||
|
||||
**Estimate: 3 days**
|
||||
**Dependencies:** 4.1.1, 1.2.2, 2.1.3
|
||||
**Deliverable:** Debug symbols in build output
|
||||
|
||||
- [ ] Modify assembler to emit debug symbols
|
||||
- [ ] Modify compiler to emit debug symbols
|
||||
- [ ] Source file/line tracking
|
||||
- [ ] Variable scope tracking
|
||||
- [ ] Linker merges debug symbols
|
||||
- [ ] Test symbol generation pipeline
|
||||
|
||||
---
|
||||
|
||||
#### 4.1.3 Symbol Table Loader in Emulator
|
||||
|
||||
### Pre-Debugger Editor Integration Tasks
|
||||
|
||||
- **Integrate compiler into editor**
|
||||
- Add a build command that invokes the full compiler pipeline (lexer → parser → codegen).
|
||||
- Show compilation output and errors in the console panel.
|
||||
|
||||
- **DSC language support**
|
||||
- Enable syntax highlighting and auto‑completion for DSC files within the editor.
|
||||
- Provide a dedicated “Build DSC” command that uses the integrated compiler.
|
||||
|
||||
- **Editor diagnostics**
|
||||
- Wire compiler error messages to the editor’s gutter so users can click to jump to source lines.
|
||||
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 4.1.2
|
||||
**Deliverable:** Symbol loading in emulator crate
|
||||
|
||||
- [ ] Implement symbol table parser
|
||||
- [ ] Build address → symbol lookup (HashMap)
|
||||
- [ ] Build symbol → address lookup
|
||||
- [ ] Memory efficient storage
|
||||
- [ ] Tests for symbol resolution
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Debugger Implementation
|
||||
|
||||
> **Priority: HIGH** — Major productivity boost.
|
||||
> **Total Estimate: 2 weeks**
|
||||
|
||||
---
|
||||
|
||||
#### 4.2.1 Core Debugger Features
|
||||
|
||||
**Estimate: 5 days**
|
||||
**Dependencies:** 4.1.3
|
||||
**Deliverable:** Debugger backend
|
||||
|
||||
- [ ] Execution control
|
||||
- [ ] Step instruction
|
||||
- [ ] Step over function calls
|
||||
- [ ] Continue to breakpoint
|
||||
- [ ] Run to cursor
|
||||
- [ ] Breakpoint system
|
||||
- [ ] Address breakpoints
|
||||
- [ ] Conditional breakpoints
|
||||
- [ ] Watchpoints (memory access)
|
||||
- [ ] Register inspection
|
||||
- [ ] Memory inspection
|
||||
- [ ] Stack trace generation
|
||||
- [ ] Test debugger commands
|
||||
|
||||
---
|
||||
|
||||
#### 4.2.2 Disassembler with Symbol Resolution
|
||||
|
||||
**Estimate: 3 days**
|
||||
**Dependencies:** 4.1.3
|
||||
**Deliverable:** Enhanced disassembler
|
||||
|
||||
- [ ] Instruction decoder
|
||||
- [ ] Format with labels instead of addresses
|
||||
- [ ] Show function names at call sites
|
||||
- [ ] Inline comments with variable names
|
||||
- [ ] Color coding for instruction types
|
||||
- [ ] Tests for disassembly output
|
||||
|
||||
---
|
||||
|
||||
#### 4.2.3 Pseudo-Instruction Decompiler
|
||||
|
||||
> ⚠️ **COMPLEX TASK** — Separate pass to decompile assembly into readable pseudo-instructions.
|
||||
|
||||
**Estimate: 4 days**
|
||||
**Dependencies:** 4.2.2
|
||||
**Deliverable:** Pseudo-instruction view mode
|
||||
|
||||
- [ ] Pattern recognition for common sequences
|
||||
- [ ] Function prologue/epilogue
|
||||
- [ ] Multiplication using shifts/adds
|
||||
- [ ] Division
|
||||
- [ ] Conditional moves
|
||||
- [ ] Control flow reconstruction
|
||||
- [ ] If/else detection
|
||||
- [ ] Loop detection
|
||||
- [ ] Switch statement detection
|
||||
- [ ] Expression reconstruction
|
||||
- [ ] Format as higher-level pseudo-code
|
||||
- [ ] Extensive pattern testing
|
||||
|
||||
---
|
||||
|
||||
#### 4.2.4 Execution History Tracking
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 4.2.1
|
||||
**Deliverable:** Execution trace feature
|
||||
|
||||
- [ ] Circular buffer for instruction history
|
||||
- [ ] Register state snapshots over time
|
||||
- [ ] Configurable history depth
|
||||
- [ ] Efficient memory usage
|
||||
- [ ] Playback/reverse debugging (basic)
|
||||
- [ ] Export trace to file
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Enhanced Editor Integration
|
||||
|
||||
> **Priority: MEDIUM** — UX improvement.
|
||||
> **Total Estimate: 1 week**
|
||||
|
||||
---
|
||||
|
||||
#### 4.3.1 Tiling Window System
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** None (UI work)
|
||||
**Deliverable:** Panel system in emulator
|
||||
|
||||
- [ ] Research Rust tiling libraries (`egui_tiles`, or custom)
|
||||
- [ ] Design panel layout system
|
||||
- [ ] Code editor panel
|
||||
- [ ] Disassembly panel
|
||||
- [ ] Register panel
|
||||
- [ ] Memory panel
|
||||
- [ ] Console panel
|
||||
- [ ] Implement drag-and-drop panel management
|
||||
- [ ] Save/load layouts
|
||||
|
||||
---
|
||||
|
||||
#### 4.3.2 Assembly Editor Improvements
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 4.3.1
|
||||
**Deliverable:** Enhanced assembly editor
|
||||
|
||||
- [ ] Syntax highlighting for DSA assembly
|
||||
- [ ] Auto-completion for instructions
|
||||
- [ ] Label/symbol auto-completion
|
||||
- [ ] Error highlighting
|
||||
- [ ] Inline documentation tooltips
|
||||
- [ ] Jump-to-definition for labels
|
||||
|
||||
---
|
||||
|
||||
#### 4.3.3 High-Level Language Editor
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 4.3.1, 2.1.4
|
||||
**Deliverable:** DSC language editor
|
||||
|
||||
- [ ] Syntax highlighting for DSC language
|
||||
- [ ] Basic auto-completion
|
||||
- [ ] Bracket matching
|
||||
- [ ] Error highlighting from compiler
|
||||
- [ ] Go-to-definition (using debug symbols)
|
||||
- [ ] Inline type hints
|
||||
|
||||
---
|
||||
|
||||
#### 4.3.4 Integrate Build Tools and Compiler into Editor
|
||||
|
||||
Estimate: 1 day
|
||||
Dependencies: 4.3.1, 3.1.2, 2.1.2
|
||||
Deliverable: Integrated build experience with compiler support
|
||||
|
||||
- [ ] Build button/command in UI that invokes the full compiler pipeline
|
||||
- [ ] Show build output and compilation errors in console panel
|
||||
- [ ] Error navigation (click to jump to source)
|
||||
- [ ] Hot reload on successful build
|
||||
- [ ] Build status indicator
|
||||
- [ ] Hook DSC language support into editor for syntax highlighting and auto‑completion
|
||||
- [ ] Provide dedicated DSC build command that uses the new compiler integration
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Integration & Polish
|
||||
|
||||
**Estimated Duration: 1–2 weeks**
|
||||
|
||||
---
|
||||
|
||||
### 5.1 Tool Integration
|
||||
|
||||
> **Priority: HIGH** — Everything works together.
|
||||
> **Total Estimate: 1 week**
|
||||
|
||||
---
|
||||
|
||||
#### 5.1.1 Unified Toolchain
|
||||
|
||||
**Estimate: 3 days**
|
||||
**Dependencies:** All previous phases
|
||||
**Deliverable:** `dsa` unified command-line tool
|
||||
|
||||
- [ ] Create meta-crate: `dsa-tools`
|
||||
- [ ] Unified CLI with subcommands
|
||||
- [ ] `dsa build`
|
||||
- [ ] `dsa run`
|
||||
- [ ] `dsa debug`
|
||||
- [ ] `dsa test`
|
||||
- [ ] `dsa pkg`
|
||||
- [ ] Shared configuration system
|
||||
- [ ] Tool interop testing
|
||||
- [ ] Documentation for workflow
|
||||
|
||||
---
|
||||
|
||||
#### 5.1.2 Emulator Integration
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 5.1.1, 4.3.4
|
||||
**Deliverable:** Fully integrated development environment
|
||||
|
||||
- [ ] Add build tools as emulator dependencies
|
||||
- [ ] In-editor build triggered from emulator
|
||||
- [ ] Debugger uses build output directly
|
||||
- [ ] Source-level debugging with line mapping
|
||||
- [ ] Test full edit → build → debug cycle
|
||||
|
||||
---
|
||||
|
||||
#### 5.1.3 Documentation & Tutorials
|
||||
|
||||
**Estimate: 2 days**
|
||||
**Dependencies:** 5.1.2
|
||||
**Deliverable:** Complete documentation suite
|
||||
|
||||
- [ ] Getting started guide
|
||||
- [ ] Full tutorial: Building a simple game
|
||||
- [ ] Debugger usage guide
|
||||
- [ ] Best practices document
|
||||
- [ ] Troubleshooting guide
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Future Enhancements (NTH)
|
||||
|
||||
> **Priority: LOW** — Nice to have, long-term goal.
|
||||
> **Estimated Duration: 4+ weeks**
|
||||
|
||||
---
|
||||
|
||||
### 6.1 Command-Line Emulator
|
||||
|
||||
> ⚠️ **COMPLEX LONG-TERM GOAL** — Requires significant design and UX consideration.
|
||||
|
||||
---
|
||||
|
||||
#### 6.1.1 Design Phase
|
||||
|
||||
**Estimate: 1 week**
|
||||
**Dependencies:** None
|
||||
**Deliverable:** `docs/cli-emulator-design.md`
|
||||
|
||||
- [ ] UX research for terminal-based debuggers
|
||||
- [ ] Design TUI layout (using `ratatui` or similar)
|
||||
- [ ] Command syntax design
|
||||
- [ ] Scripting support design
|
||||
- [ ] Accessibility considerations
|
||||
|
||||
---
|
||||
|
||||
#### 6.1.2 Implementation
|
||||
|
||||
**Estimate: 3+ weeks**
|
||||
**Dependencies:** 6.1.1, Phase 4 complete
|
||||
**Deliverable:** `dsa-emu-cli` executable
|
||||
|
||||
- [ ] TUI framework setup
|
||||
- [ ] Core emulator integration
|
||||
- [ ] Command parser
|
||||
- [ ] Panel rendering (code, registers, memory, etc.)
|
||||
- [ ] Keyboard shortcuts
|
||||
- [ ] Mouse support
|
||||
- [ ] Configuration system
|
||||
- [ ] Extensive usability testing
|
||||
|
||||
---
|
||||
|
||||
## Summary Timeline
|
||||
|
||||
| Phase | Duration | Key Dependencies |
|
||||
| ----------------------------- | --------- | ------------------- |
|
||||
| Phase 1: Foundation | 3–4 weeks | None |
|
||||
| Phase 2: Compiler | 3–4 weeks | Phase 1 complete |
|
||||
| Phase 3: Build System | 2–3 weeks | Phases 1–2 complete |
|
||||
| Phase 4: Debugger | 3–4 weeks | Phases 1–3 complete |
|
||||
| Phase 5: Integration | 1–2 weeks | Phases 1–4 complete |
|
||||
| Phase 6: CLI Emulator _(NTH)_ | 4+ weeks | Phase 4 complete |
|
||||
|
||||
**Total Estimated Time: 12–17 weeks (3–4 months) for Phases 1–5**
|
||||
|
||||
---
|
||||
|
||||
## Critical Path
|
||||
|
||||
The following tasks are on the critical path and will block other work if delayed:
|
||||
|
||||
```
|
||||
1.1.1 Binary format design
|
||||
└── 1.1.2 Object file writer
|
||||
└── 1.1.3 Linker
|
||||
└── 1.2.2 Assembler rewrite
|
||||
└── 2.1.3 Compiler codegen
|
||||
└── 3.1.2 Build system
|
||||
└── 4.1.2 Debug symbols
|
||||
└── 4.2.1 Debugger
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommended Work Order
|
||||
|
||||
| Weeks | Focus | Tasks |
|
||||
| ----- | ------------------------------------- | ------------------------------------------------- |
|
||||
| 1–2 | Binary Format & Linker | 1.1.1 → 1.1.2 → 1.1.3 |
|
||||
| 3–4 | Assembler Rewrite | 1.2.1 → 1.2.2 |
|
||||
| 5–6 | Compiler Syntax & Parser | 2.1.1 → 2.1.2 _(start 1.3 docs in parallel)_ |
|
||||
| 7–9 | Compiler Codegen & Types | 2.1.3 → 2.1.4 _(start 2.2.1 runtime in parallel)_ |
|
||||
| 10–11 | Build System | 3.1.1 → 3.1.2 → 3.1.3 |
|
||||
| 12–13 | Package Management _(if desired now)_ | 3.2.1 → 3.2.2 → 3.2.3 |
|
||||
| 14–15 | Debug Symbols | 4.1.1 → 4.1.2 → 4.1.3 |
|
||||
| 16–18 | Core Debugger | 4.2.1 → 4.2.2 → 4.2.4 |
|
||||
| 19–20 | Editor Enhancements | 4.3.1 → 4.3.2 → 4.3.3 → 4.3.4 |
|
||||
| 21–22 | Integration & Polish | 5.1.1 → 5.1.2 → 5.1.3 |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Time estimates assume ~6–8 productive hours per day.
|
||||
- Add **20–30% buffer** for unexpected issues.
|
||||
- Testing time is included in each estimate.
|
||||
- Documentation is distributed throughout rather than batched at the end.
|
||||
- Package management (3.2) can be deferred if time-constrained.
|
||||
- Pseudo-instruction decompiler (4.2.3) can be a stretch goal.
|
||||
- CLI emulator (Phase 6) is explicitly a "nice to have" and should not block other work.
|
||||
Binary file not shown.
@@ -0,0 +1,638 @@
|
||||
# DSA Implementation vs Documentation Discrepancies
|
||||
|
||||
## Critical Discrepancies
|
||||
|
||||
### 1. **Stack Growth Direction** ❌ CRITICAL
|
||||
|
||||
**Documentation states:** Stack grows upward (toward higher addresses)
|
||||
|
||||
**Implementation shows (expand.rs:44-51):**
|
||||
```rust
|
||||
fn expand_push(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
|
||||
// ...
|
||||
nodes.extend(vec![
|
||||
node!(label, Opcode::SubI, spr, 4, spr), // spr = spr - 4
|
||||
node!(None, Opcode::Stw, reg, spr, 0),
|
||||
]);
|
||||
```
|
||||
|
||||
**Implementation shows (expand.rs:130-137):**
|
||||
```rust
|
||||
fn expand_pop(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
|
||||
// ...
|
||||
nodes.extend(vec![
|
||||
node!(label, Opcode::Ldw, spr, reg, 0),
|
||||
node!(None, Opcode::AddI, spr, 4, spr), // spr = spr + 4
|
||||
]);
|
||||
```
|
||||
|
||||
**Reality:** Stack grows **DOWNWARD** (toward lower addresses)
|
||||
- PUSH: Decrements SPR by 4, then stores
|
||||
- POP: Loads, then increments SPR by 4
|
||||
|
||||
**Impact:** All documentation examples and calling convention diagrams are backwards!
|
||||
|
||||
---
|
||||
|
||||
### 2. **CALL Pseudo-instruction Expansion** ❌ CRITICAL
|
||||
|
||||
**Documentation states (DSA_Assembly_Reference.md):**
|
||||
```asm
|
||||
; call print::print expands to:
|
||||
lwi print::print, ret ; Load function address into ret
|
||||
jmp 0, ret ; Jump to function (saves return in pcx)
|
||||
```
|
||||
|
||||
**Implementation shows (expand.rs:109-123):**
|
||||
```rust
|
||||
fn expand_call(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
|
||||
nodes.extend(vec![
|
||||
node!(label, Opcode::SubI, spr, 4, spr), // Decrement stack pointer
|
||||
node!(None, Opcode::Stw, pcx, spr, 0), // Store PCX (return addr) on stack
|
||||
node!(None, Opcode::Jmp, addr, zero), // Jump to function
|
||||
]);
|
||||
```
|
||||
|
||||
**Reality:** CALL expansion is:
|
||||
1. Decrement SPR by 4
|
||||
2. Store PCX (return address) to stack
|
||||
3. Jump to function address
|
||||
|
||||
**Impact:** Return address is stored on the STACK, not in RET register!
|
||||
|
||||
---
|
||||
|
||||
### 3. **RETURN Pseudo-instruction Expansion** ❌ CRITICAL
|
||||
|
||||
**Documentation states:**
|
||||
```asm
|
||||
; return expands to:
|
||||
jmp 0, ret ; Jump to address in ret register
|
||||
```
|
||||
|
||||
**Implementation shows (expand.rs:125-135):**
|
||||
```rust
|
||||
fn expand_return(current: &Node, nodes: &mut Vec<Node>) {
|
||||
nodes.extend(vec![
|
||||
node!(label, Opcode::Ldw, spr, ret, 0), // Load return addr from stack
|
||||
node!(None, Opcode::AddI, spr, 4, spr), // Increment stack pointer
|
||||
node!(None, Opcode::Jmp, 4, ret), // Jump to (ret + 4)
|
||||
]);
|
||||
}
|
||||
```
|
||||
|
||||
**Reality:** RETURN expansion is:
|
||||
1. Load return address from stack into RET register
|
||||
2. Increment SPR by 4
|
||||
3. Jump to (RET + 4)
|
||||
|
||||
**Why +4?** The stored PCX points to the instruction AFTER the call's jump, so we need to add 4 to skip past the stored PCX instruction itself... or this might be a bug in the implementation.
|
||||
|
||||
**Impact:** Return mechanism is completely different from documentation!
|
||||
|
||||
---
|
||||
|
||||
### 4. **Calling Convention - Stack Frame Layout** ❌ CRITICAL
|
||||
|
||||
**Documentation states:**
|
||||
```
|
||||
Higher Addresses
|
||||
├─────────────┤
|
||||
│ Arg N │ ← spr + (8 + 4*(N-1))
|
||||
│ ... │
|
||||
│ Arg 2 │ ← spr + 16
|
||||
│ Arg 1 │ ← spr + 12
|
||||
│ Arg 0 │ ← spr + 8
|
||||
├─────────────┤
|
||||
│ Ret Addr │ ← spr + 4
|
||||
├─────────────┤
|
||||
│ Old BPR │ ← spr + 0
|
||||
├─────────────┤ ← bpr, spr
|
||||
│ Locals │
|
||||
Lower Addresses
|
||||
```
|
||||
|
||||
**Reality based on implementation:**
|
||||
Since stack grows DOWN:
|
||||
```
|
||||
Lower Addresses
|
||||
├─────────────┤ ← Current SPR/BPR
|
||||
│ Old BPR │ ← spr + 0 (immediately above SPR)
|
||||
├─────────────┤
|
||||
│ Ret Addr │ ← spr + 4 (pushed by CALL)
|
||||
├─────────────┤
|
||||
│ Arg 0 │ ← spr + 8
|
||||
│ Arg 1 │ ← spr + 12
|
||||
│ Arg 2 │ ← spr + 16
|
||||
│ ... │
|
||||
│ Arg N │ ← spr + (8 + 4*(N-1))
|
||||
├─────────────┤
|
||||
Higher Addresses
|
||||
```
|
||||
|
||||
**The diagram needs to be flipped!** The offsets are correct, but the direction is wrong.
|
||||
|
||||
---
|
||||
|
||||
### 5. **Label-Based Load/Store Scratch Register** ⚠️ IMPORTANT
|
||||
|
||||
**Documentation states:** Uses `rgf` as scratch register
|
||||
|
||||
**Implementation confirms (expand.rs:138-153):**
|
||||
```rust
|
||||
fn expand_ldx(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
|
||||
// For ldb label, reg:
|
||||
nodes.extend(vec![
|
||||
node!(current.label(), Opcode::Lli, name, reg),
|
||||
node!(None, Opcode::Lui, name, reg),
|
||||
node!(None, opcode, reg, reg, offset),
|
||||
]);
|
||||
```
|
||||
|
||||
**Wait! This is WRONG in the implementation!**
|
||||
|
||||
The load expansion uses the DESTINATION register as scratch:
|
||||
```asm
|
||||
ldb buffer, rg2 expands to:
|
||||
lli buffer, rg2 ; Uses rg2 as destination
|
||||
lui buffer, rg2 ; Uses rg2 as destination
|
||||
ldb rg2, rg2, 0 ; Uses rg2 as base
|
||||
```
|
||||
|
||||
**Documentation says it should use rgf:**
|
||||
```asm
|
||||
ldb buffer, rg2 expands to:
|
||||
lli buffer, rgf ; Uses rgf as scratch
|
||||
lui buffer, rgf ; Uses rgf as scratch
|
||||
ldb rgf, rg2, 0 ; Load from rgf into rg2
|
||||
```
|
||||
|
||||
**For stores (expand.rs:155-176):**
|
||||
```rust
|
||||
fn expand_stx(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
|
||||
// For stb reg, label:
|
||||
let temp = Token::Register(Register::Acc); // Uses ACC, not RGF!
|
||||
|
||||
nodes.extend(vec![
|
||||
node!(current.label(), Opcode::Lli, dest, temp),
|
||||
node!(None, Opcode::Lui, dest, temp),
|
||||
node!(None, opcode, base, temp, offset),
|
||||
]);
|
||||
```
|
||||
|
||||
**Reality:**
|
||||
- Load pseudo-instructions use the DESTINATION register as scratch
|
||||
- Store pseudo-instructions use the ACC register as scratch, NOT rgf
|
||||
|
||||
**Impact:** Documentation is incorrect about which registers are used!
|
||||
|
||||
---
|
||||
|
||||
### 6. **LWI Pseudo-instruction** ✅ CORRECT
|
||||
|
||||
**Documentation and implementation agree:**
|
||||
```rust
|
||||
fn expand_lwi(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
|
||||
nodes.extend(vec![
|
||||
node!(current.label(), Opcode::Lli, val, reg),
|
||||
node!(None, Opcode::Lui, val, reg),
|
||||
]);
|
||||
```
|
||||
|
||||
This matches the documented expansion.
|
||||
|
||||
---
|
||||
|
||||
### 7. **PUSHA/POPA Pseudo-instructions** 📝 UNDOCUMENTED
|
||||
|
||||
**These exist in implementation but are NOT in documentation!**
|
||||
|
||||
**expand.rs:53-76:**
|
||||
```rust
|
||||
fn expand_pusha(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
|
||||
let count = expect_token!(arg0, Immediate)?;
|
||||
let spr = Token::Register(Register::Spr);
|
||||
let registers: Vec<Register> = Register::general();
|
||||
|
||||
nodes.push(node!(label, Opcode::SubI, spr, Token::Immediate(count * 4), spr));
|
||||
|
||||
nodes.extend((0..count).rev().map(|i| {
|
||||
node!(None, Opcode::Stw,
|
||||
Token::Register(registers[i as usize]),
|
||||
spr,
|
||||
Token::Immediate(i * 4)
|
||||
)
|
||||
}));
|
||||
```
|
||||
|
||||
**expand.rs:78-101:**
|
||||
```rust
|
||||
fn expand_popa(current: &Node, nodes: &mut Vec<Node>) -> Result<(), AssembleError> {
|
||||
let count = expect_token!(arg0, Immediate)?;
|
||||
|
||||
nodes.extend((0..count).rev().map(|i| {
|
||||
node!(
|
||||
{ if i == 0 { label.clone() } else { None } },
|
||||
Opcode::Ldw,
|
||||
spr,
|
||||
Token::Register(registers[i as usize]),
|
||||
Token::Immediate(i * 4)
|
||||
)
|
||||
}));
|
||||
|
||||
nodes.push(node!(None, Opcode::AddI, spr, Token::Immediate(count * 4), spr));
|
||||
```
|
||||
|
||||
**What they do:**
|
||||
- `pusha N` - Push first N general-purpose registers (rg0-rgN) to stack
|
||||
- `popa N` - Pop first N general-purpose registers from stack
|
||||
|
||||
**Missing from documentation entirely!**
|
||||
|
||||
---
|
||||
|
||||
### 8. **Register Index Encoding** ⚠️ IMPORTANT
|
||||
|
||||
**Documentation states:** System registers like MAR, MDR, STS, CIR, PCX are "internal" and not accessible
|
||||
|
||||
**Implementation shows (instructions.rs:148-153):**
|
||||
```rust
|
||||
0x18 => Self::Mar,
|
||||
0x19 => Self::Mdr,
|
||||
0x1A => Self::Sts,
|
||||
0x1B => Self::Cir,
|
||||
0x1C => Self::Pcx,
|
||||
```
|
||||
|
||||
**Reality:** These registers ARE encoded in the instruction format at indices 0x18-0x1C!
|
||||
|
||||
**However, instructions.rs:186 shows:**
|
||||
```rust
|
||||
"null" => Ok(Self::NoReg), // Can parse "null" as NoReg
|
||||
```
|
||||
|
||||
**Documentation never mentions "null" as an alternative name for noreg!**
|
||||
|
||||
---
|
||||
|
||||
### 9. **LUI Immediate Value Handling** ⚠️ IMPORTANT
|
||||
|
||||
**Documentation states:**
|
||||
```
|
||||
lui immediate, dest_reg ; Load immediate into upper 16 bits
|
||||
```
|
||||
|
||||
**Implementation shows (codegen.rs:248-254):**
|
||||
```rust
|
||||
fn build_load_immediate_instruction(...) -> Result<Instruction, AssembleError> {
|
||||
// ...
|
||||
match opcode {
|
||||
Opcode::Lli => {
|
||||
let instruction_args = args!(I, immediate: value as u16, r1: dest);
|
||||
Ok(Instruction::LoadLowerImmediate(instruction_args))
|
||||
}
|
||||
Opcode::Lui => {
|
||||
let upper_value = value >> 16; // Shifts right by 16!
|
||||
let instruction_args = args!(I, immediate: upper_value as u16, r1: dest);
|
||||
Ok(Instruction::LoadUpperImmediate(instruction_args))
|
||||
}
|
||||
```
|
||||
|
||||
**Reality:** When assembling `lui immediate, reg`, the assembler:
|
||||
1. Takes the immediate value
|
||||
2. Shifts it RIGHT by 16 bits
|
||||
3. Stores the result in the instruction
|
||||
|
||||
**This means:**
|
||||
```asm
|
||||
lli 0x1234, rg0 ; Stores 0x1234 in lower 16 bits
|
||||
lui 0xABCD0000, rg0 ; Right-shifts to 0xABCD, stores in upper 16 bits
|
||||
```
|
||||
|
||||
**Or more likely, the assembler expects:**
|
||||
```asm
|
||||
lli 0x1234, rg0 ; Stores 0x1234 in lower 16 bits
|
||||
lui 0xABCD, rg0 ; Stores 0xABCD in upper 16 bits (no shift needed)
|
||||
```
|
||||
|
||||
**Documentation needs clarification on what immediate value format LUI expects!**
|
||||
|
||||
---
|
||||
|
||||
### 10. **Data Definition Encoding** ⚠️ IMPORTANT
|
||||
|
||||
**Implementation (expand.rs:217-267):**
|
||||
```rust
|
||||
fn process_dx_data(args: Vec<Token>, size: usize) -> Result<Vec<u32>, AssembleError> {
|
||||
for token in args {
|
||||
match token {
|
||||
Token::StringLit(mut s) => {
|
||||
s.push('\0'); // Automatically adds null terminator!
|
||||
for ch in s.chars() {
|
||||
let mut char_buf = [0u8; 4];
|
||||
let char_bytes = ch.encode_utf8(&mut char_buf);
|
||||
buffer.extend_from_slice(char_bytes.as_bytes());
|
||||
}
|
||||
}
|
||||
Token::Immediate(value) => {
|
||||
buffer.extend_from_slice(&value.to_be_bytes()); // BIG ENDIAN!
|
||||
}
|
||||
```
|
||||
|
||||
**Key findings:**
|
||||
1. String literals automatically get null terminator appended
|
||||
2. Numeric values are stored in **BIG ENDIAN** format (to_be_bytes)
|
||||
3. Documentation says "little-endian byte order" globally
|
||||
|
||||
**Contradiction:** Data definition uses BIG ENDIAN, but doc says LITTLE ENDIAN!
|
||||
|
||||
---
|
||||
|
||||
### 11. **Segment Instruction** 📝 UNDOCUMENTED
|
||||
|
||||
**Implementation has a SEGMENT instruction (0x27/0x3F):**
|
||||
```rust
|
||||
Segment(u32) = 0x3F,
|
||||
```
|
||||
|
||||
**This is completely undocumented!**
|
||||
|
||||
From model.rs:
|
||||
```rust
|
||||
Self::Segment => write!(f, "[SEGMENT]"),
|
||||
```
|
||||
|
||||
From codegen.rs:
|
||||
```rust
|
||||
Opcode::Segment => build_segment_instruction(&args),
|
||||
```
|
||||
|
||||
**Purpose unclear, needs documentation!**
|
||||
|
||||
---
|
||||
|
||||
### 12. **Data Instruction** 📝 UNDOCUMENTED
|
||||
|
||||
**Implementation has a DATA instruction (0x3E):**
|
||||
```rust
|
||||
Data(u32) = 0x3E,
|
||||
```
|
||||
|
||||
**This appears to be a meta-instruction for embedding raw data, but it's undocumented in the assembly reference!**
|
||||
|
||||
---
|
||||
|
||||
### 13. **INC/DEC Instruction Encoding** ⚠️ MINOR
|
||||
|
||||
**Implementation (codegen.rs:293-299):**
|
||||
```rust
|
||||
fn build_inc_dec_instruction(opcode: Opcode, args: &[Token]) -> Result<Instruction, AssembleError> {
|
||||
let reg = expect_token!(reg_token, Register)?;
|
||||
match opcode {
|
||||
Opcode::Inc => Ok(Instruction::Increment(args!(R, sr1: reg))),
|
||||
Opcode::Dec => Ok(Instruction::Decrement(args!(R, sr1: reg))),
|
||||
```
|
||||
|
||||
**Reality:** INC/DEC only set SR1 field, not DR field.
|
||||
|
||||
**But args.rs shows:**
|
||||
```rust
|
||||
impl RTypeArgs {
|
||||
pub fn new(...) -> Self {
|
||||
let sr1 = sr1.unwrap_or_default(); // Defaults to NoReg
|
||||
let dr = dr.unwrap_or_default(); // Defaults to NoReg
|
||||
```
|
||||
|
||||
**So the DR field gets set to NoReg, which is correct per documentation.**
|
||||
|
||||
**However, the Display impl (instructions.rs:449) shows:**
|
||||
```rust
|
||||
Self::Increment(a) | Self::Decrement(a) => write!(f, " {}", a.sr1),
|
||||
```
|
||||
|
||||
**This is correct - only shows SR1 in disassembly.**
|
||||
|
||||
---
|
||||
|
||||
### 14. **Shift Instruction Operand Order** ⚠️ MINOR
|
||||
|
||||
**Implementation (codegen.rs:301-312):**
|
||||
```rust
|
||||
fn build_shift_instruction(opcode: Opcode, args: &[Token]) -> Result<Instruction, AssembleError> {
|
||||
let reg = expect_token!(reg_token, Register)?;
|
||||
let amount = expect_token!(amount_token, Immediate)? as u8;
|
||||
|
||||
match opcode {
|
||||
Opcode::Shl => Ok(Instruction::ShiftLeft(args!(R, sr1: reg, shamt: amount))),
|
||||
```
|
||||
|
||||
**This only handles LITERAL shift amounts, not REGISTER shift amounts!**
|
||||
|
||||
**Documentation states both are supported:**
|
||||
```asm
|
||||
shl rg0, 2 ; Literal shift
|
||||
shl rg0, rg1 ; Register shift
|
||||
```
|
||||
|
||||
**The current codegen only handles the literal case!**
|
||||
|
||||
**This is a BUG in the implementation - register shifts aren't properly assembled!**
|
||||
|
||||
---
|
||||
|
||||
### 15. **Jump Instruction Operand Order** ⚠️ CONFUSION
|
||||
|
||||
**Documentation shows assembly syntax:**
|
||||
```asm
|
||||
jmp addr [, offset_reg]
|
||||
```
|
||||
|
||||
**But implementation (codegen.rs:256-270):**
|
||||
```rust
|
||||
fn build_jump_instruction(opcode: Opcode, args: &[Token]) -> Result<Instruction, AssembleError> {
|
||||
let address = expect_token!(address_token, Immediate)?;
|
||||
let offset = expect_token!(offset_token, Register)?;
|
||||
let instruction_args = args!(I, immediate: address as u16, r1: offset);
|
||||
```
|
||||
|
||||
**This expects:**
|
||||
1. First arg: immediate (address)
|
||||
2. Second arg: register (offset)
|
||||
|
||||
**So assembly syntax should be:**
|
||||
```asm
|
||||
jmp immediate, offset_register
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```asm
|
||||
jmp 0x1000, zero ; Jump to 0x1000
|
||||
jmp 4, ret ; Jump to (ret + 4)
|
||||
```
|
||||
|
||||
**Documentation syntax is correct, but parameter names are confusing!**
|
||||
|
||||
The "address" is actually an OFFSET, and the register is the BASE!
|
||||
|
||||
**Better naming:**
|
||||
```asm
|
||||
jmp offset, base_register
|
||||
; Target = base_register + offset
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 16. **NOT Instruction Operand Count** ✅ MINOR ISSUE
|
||||
|
||||
**Documentation shows:**
|
||||
```asm
|
||||
not src, dest ; Two operands
|
||||
```
|
||||
|
||||
**Implementation (instructions.rs:428-429):**
|
||||
```rust
|
||||
Self::Compare(args) | Self::Not(args) => {
|
||||
write!(f, " {}, {}", args.sr1, args.sr2)
|
||||
}
|
||||
```
|
||||
|
||||
**This displays BOTH sr1 and sr2 for NOT!**
|
||||
|
||||
**But codegen.rs:354-362:**
|
||||
```rust
|
||||
fn build_not_instruction(args: &[Token]) -> Result<Instruction, AssembleError> {
|
||||
let reg = expect_token!(reg_token, Register)?;
|
||||
let dest = expect_token!(dest_token, Register)?;
|
||||
Ok(Instruction::Not(args!(R, sr1: reg, dr: dest)))
|
||||
```
|
||||
|
||||
**Sets sr1 and dr, NOT sr1 and sr2!**
|
||||
|
||||
**The Display impl is WRONG - should show sr1 and dr:**
|
||||
```rust
|
||||
Self::Not(args) => write!(f, " {}, {}", args.sr1, args.dr)
|
||||
```
|
||||
|
||||
**This is a display bug in the implementation!**
|
||||
|
||||
---
|
||||
|
||||
### 17. **Register File Indexing** ✅ CORRECT
|
||||
|
||||
**Documentation and implementation both agree:**
|
||||
- 0x00-0x0F: rg0-rgf (general purpose)
|
||||
- 0x10: acc
|
||||
- 0x11: spr
|
||||
- 0x12: bpr
|
||||
- 0x13: ret
|
||||
- 0x14: idr
|
||||
- 0x15: mmr
|
||||
- 0x16: zero
|
||||
- 0x17: noreg
|
||||
|
||||
**This matches perfectly.**
|
||||
|
||||
---
|
||||
|
||||
### 18. **Immediate Arithmetic Destination** ⚠️ MINOR
|
||||
|
||||
**Implementation (codegen.rs:314-330):**
|
||||
```rust
|
||||
fn build_arithmetic_immediate_instruction(...) -> Result<Instruction, AssembleError> {
|
||||
let reg = expect_token!(reg_token, Register)?;
|
||||
let immediate = expect_token!(immediate_token, Immediate)? as u16;
|
||||
let dest = expect_token!(dest_token, Register)?;
|
||||
let instruction_args = args!(I, immediate: immediate, r1: reg, r2: dest);
|
||||
```
|
||||
|
||||
**This REQUIRES three arguments:**
|
||||
1. Source register
|
||||
2. Immediate value
|
||||
3. Destination register
|
||||
|
||||
**But documentation says destination is optional:**
|
||||
```
|
||||
iadd src_reg, imm [, dest_reg] ; dest optional
|
||||
```
|
||||
|
||||
**Reality:** The assembler REQUIRES the destination register!
|
||||
|
||||
**If you want in-place operation:**
|
||||
```asm
|
||||
iadd rg0, 10, rg0 ; Required to specify rg0 twice
|
||||
```
|
||||
|
||||
**Not:**
|
||||
```asm
|
||||
iadd rg0, 10 ; This won't work!
|
||||
```
|
||||
|
||||
**Documentation is misleading - destination is NOT optional!**
|
||||
|
||||
---
|
||||
|
||||
### 19. **Memory Instruction Offsets** ✅ CORRECT
|
||||
|
||||
**Implementation correctly handles signed 16-bit offsets:**
|
||||
```rust
|
||||
let offset = expect_token!(offset_token, Immediate)? as u16;
|
||||
```
|
||||
|
||||
**These are stored as u16 but interpreted as signed i16 at runtime.**
|
||||
|
||||
**Documentation is correct about this.**
|
||||
|
||||
---
|
||||
|
||||
### 20. **Instruction Opcode Values** ✅ VERIFIED
|
||||
|
||||
Comparing model.rs opcodes with instructions.rs:
|
||||
|
||||
| Instruction | model.rs | instructions.rs | Match |
|
||||
|-------------|----------|-----------------|-------|
|
||||
| Nop | 0x00 | 0x0 | ✅ |
|
||||
| Mov | 0x01 | 0x1 | ✅ |
|
||||
| MovSigned | 0x02 | 0x2 | ✅ |
|
||||
| LoadByte | 0x03 | 0x3 | ✅ |
|
||||
| ... | ... | ... | ✅ |
|
||||
| AddImmediate | 0x25 | 0x25 | ✅ |
|
||||
| SubImmediate | 0x26 | 0x26 | ✅ |
|
||||
| Segment | 0x27 | 0x3F | ❌ MISMATCH! |
|
||||
|
||||
**CRITICAL:** Segment instruction has opcode **0x27** in model.rs but **0x3F** in instructions.rs!
|
||||
|
||||
---
|
||||
|
||||
## Summary of Critical Issues
|
||||
|
||||
### Must Fix in Documentation:
|
||||
|
||||
1. ✅ **Stack grows DOWNWARD** - flip all diagrams
|
||||
2. ✅ **CALL expansion** - uses stack, not ret register directly
|
||||
3. ✅ **RETURN expansion** - loads from stack, jumps to ret+4
|
||||
4. ✅ **Stack frame layout** - flip diagram vertically
|
||||
5. ✅ **Load pseudo scratch register** - uses DEST reg, not rgf
|
||||
6. ✅ **Store pseudo scratch register** - uses ACC, not rgf
|
||||
7. ✅ **Add PUSHA/POPA documentation**
|
||||
8. ✅ **Add SEGMENT instruction documentation**
|
||||
9. ✅ **Add DATA instruction documentation**
|
||||
10. ✅ **Clarify LUI immediate value handling**
|
||||
11. ✅ **Fix endianness** - data definition uses BIG endian
|
||||
12. ✅ **IADD/ISUB destination NOT optional**
|
||||
13. ✅ **Add "null" as alias for noreg**
|
||||
14. ✅ **Fix Segment opcode** - 0x27 or 0x3F?
|
||||
|
||||
### Potential Implementation Bugs:
|
||||
|
||||
1. ⚠️ **Shift instruction** - doesn't handle register shifts
|
||||
2. ⚠️ **NOT display** - shows sr2 instead of dr
|
||||
3. ⚠️ **RETURN +4 offset** - why is this needed?
|
||||
4. ⚠️ **Segment opcode mismatch** - 0x27 vs 0x3F
|
||||
|
||||
### Minor Documentation Improvements:
|
||||
|
||||
1. Add explicit examples of stack growth direction
|
||||
2. Show complete memory layout diagrams
|
||||
3. Document which registers are volatile/preserved
|
||||
4. Add troubleshooting section for common mistakes
|
||||
5. Clarify jump instruction parameter semantics
|
||||
Binary file not shown.
@@ -0,0 +1,149 @@
|
||||
# DSA Documentation Inconsistencies Analysis
|
||||
|
||||
## 1. Register Descriptions
|
||||
|
||||
### Issue: System Registers vs Assembly-Accessible Registers
|
||||
- `registers.md` lists MAR, STS, CIR, MDR as "System" registers
|
||||
- These are NOT mentioned in `dsa_assembly_reference.md` or `instruction_set.md`
|
||||
- **Resolution**: System registers are internal CPU registers not directly accessible in assembly. They should be documented separately from programmer-accessible registers.
|
||||
|
||||
### Issue: Register Naming Inconsistencies
|
||||
- `registers.md` uses `RG0-RGF` (uppercase)
|
||||
- `dsa_assembly_reference.md` uses `rg0-rgf` (lowercase)
|
||||
- **Resolution**: Assembly syntax should be lowercase (standard convention)
|
||||
|
||||
### Issue: NOREG Register
|
||||
- `registers.md`: "Loads/using as dest register must cause an illegal instruction trap"
|
||||
- `dsa_assembly_reference.md`: "on-read/write: illegal instruction fault"
|
||||
- **Resolution**: Consistent terminology needed - use "illegal instruction fault"
|
||||
|
||||
## 2. Instruction Operand Order Inconsistencies
|
||||
|
||||
### Issue: Load Instructions
|
||||
- `instruction_set.md`: `LDB BaseReg, Offset, DestReg`
|
||||
- `dsa_assembly_reference.md`: `LDB base_reg, dest_reg [, offset]`
|
||||
- **Resolution**: Assembly reference shows standard syntax (base, dest, offset optional), instruction set shows encoding order
|
||||
|
||||
### Issue: Store Instructions
|
||||
- `instruction_set.md`: `STB SrcReg, BaseReg, Offset`
|
||||
- `dsa_assembly_reference.md`: `STB src_reg, base_reg [, offset]`
|
||||
- **Resolution**: Consistent - offset is optional
|
||||
|
||||
### Issue: Immediate Load Instructions
|
||||
- `instruction_set.md`: `LLI DstReg, Value` (destination first)
|
||||
- `dsa_assembly_reference.md`: `LLI imm, dest_reg` (immediate first)
|
||||
- **Resolution**: Assembly reference shows gas-style syntax (source, dest), instruction set shows encoding order
|
||||
|
||||
### Issue: Jump Instructions
|
||||
- `instruction_set.md`: `JMP DestReg, Offset | Address`
|
||||
- `dsa_assembly_reference.md`: `JMP addr [, offset_reg]` or `JMP imm, offset_reg`
|
||||
- **Resolution**: Different perspectives - instruction set shows encoding, assembly shows usage
|
||||
|
||||
## 3. Instruction Behavior Differences
|
||||
|
||||
### Issue: IADD/ISUB Operands
|
||||
- `instruction_set.md`: `IADD Src1, Literal, Dest` (3 operands)
|
||||
- `dsa_assembly_reference.md`: `IADD src_reg, imm [, dest_reg]` (dest optional)
|
||||
- **Resolution**: Assembly allows dest to default to src_reg
|
||||
|
||||
### Issue: SHL/SHR Operands
|
||||
- `instruction_set.md`: `SHL Reg, Literal | ValReg`
|
||||
- `dsa_assembly_reference.md`: `SHL reg, shift_amount`
|
||||
- **Resolution**: Both literal and register shifts supported
|
||||
|
||||
## 4. Pseudo-Instruction Inconsistencies
|
||||
|
||||
### Issue: PUSH/POP Expansion
|
||||
- `pseudoinstructions.md`:
|
||||
- PUSH = `INC SPR` then `STW register, SPR`
|
||||
- POP = `LDW SPR, register` then `DEC SPR`
|
||||
- Standard stack conventions suggest PUSH should decrement (grow down)
|
||||
- **Resolution**: Clarify stack growth direction
|
||||
|
||||
### Issue: LDB/LDH/LDW Pseudo vs Hardware
|
||||
- `pseudoinstructions.md` lists LDB, LDH, LDW as pseudo-instructions with label addressing
|
||||
- `instruction_set.md` lists them as hardware instructions
|
||||
- **Resolution**: Both exist - hardware instructions use registers, pseudo-instructions add label support
|
||||
|
||||
### Issue: LWI Naming
|
||||
- `dsa_assembly_reference.md`: LWI = Load Word Immediate (load address)
|
||||
- Could be confused with "Load Word Immediate" (load literal value)
|
||||
- **Resolution**: LWI specifically means "Load Word address Into register"
|
||||
|
||||
## 5. Calling Convention Details
|
||||
|
||||
### Issue: Argument Offsets
|
||||
- Calling convention says "first 3 args at offsets 8, 12, 16"
|
||||
- This assumes 32-bit words (4 bytes each)
|
||||
- Offset 8 is position of first argument (after return address at offset 4, and old BPR at offset 0)
|
||||
- **Resolution**: Clarify that SPR+0 = old BPR, SPR+4 = return address, SPR+8 = first arg
|
||||
|
||||
### Issue: Return Value Location
|
||||
- Says "Store return value (if any) to `spr+8`"
|
||||
- This overwrites the first argument
|
||||
- **Resolution**: This is intentional - return value replaces first argument position after cleanup
|
||||
|
||||
## 6. Missing Information
|
||||
|
||||
### From instruction_set.md not in assembly reference:
|
||||
- Instruction encoding details (R-type, I-type, J-type)
|
||||
- Hex opcodes for each instruction
|
||||
- Alignment requirements for memory operations
|
||||
- Sign extension behavior details
|
||||
|
||||
### From assembly reference not in instruction_set:
|
||||
- Complete pseudo-instruction expansions showing what they compile to
|
||||
- Library examples (multiply, print)
|
||||
- Detailed calling convention walkthrough
|
||||
- Module system (INCLUDE directive)
|
||||
|
||||
### From registers.md not elsewhere:
|
||||
- STS (Status Register) bit layout
|
||||
- Boot values for status flags
|
||||
- System registers (MAR, STS, CIR, MDR)
|
||||
|
||||
## 7. Terminology Inconsistencies
|
||||
|
||||
- "halfword" vs "half-word" vs "16-bit value"
|
||||
- "word" assumed to be 32-bit (should be explicit)
|
||||
- "register" vs "reg" in syntax
|
||||
- "immediate" vs "literal" vs "constant"
|
||||
|
||||
## 8. Critical Missing Details
|
||||
|
||||
### CALL and RETURN Pseudo-instructions
|
||||
- Assembly reference shows them but doesn't show their expansion
|
||||
- Need to document what they expand to
|
||||
|
||||
### Label Addressing Mode
|
||||
- Shows expansions for loads/stores with labels
|
||||
- Uses RGF as scratch register - should this be documented as reserved for this purpose?
|
||||
|
||||
### Stack Direction
|
||||
- Not explicitly stated whether stack grows up or down
|
||||
- PUSH uses INC SPR (suggests growing up) - unusual!
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. **Separate Documentation into Logical Layers**:
|
||||
- ISA Specification (hardware-level, for CPU implementers)
|
||||
- Assembly Language Reference (for programmers)
|
||||
- ABI/Calling Convention (for compiler/linker writers)
|
||||
|
||||
2. **Standardize Terminology**:
|
||||
- Use consistent casing (lowercase for assembly mnemonics)
|
||||
- Define terms clearly (word = 32-bit, halfword = 16-bit, byte = 8-bit)
|
||||
- Distinguish "literal" (immediate value in code) from "address" (memory location)
|
||||
|
||||
3. **Document Stack Convention Clearly**:
|
||||
- Explicitly state stack grows upward (unusual but valid)
|
||||
- Show memory layout diagrams
|
||||
|
||||
4. **Show Complete Pseudo-instruction Expansions**:
|
||||
- CALL, RETURN need full expansion documentation
|
||||
- Document which register(s) are used as temporaries
|
||||
|
||||
5. **Clarify Register Usage Conventions**:
|
||||
- ACC: used by pseudo-instructions, volatile
|
||||
- RGF: used by label addressing, volatile
|
||||
- RG0-RGE: general purpose, callee may use per calling convention
|
||||
Reference in New Issue
Block a user