150 lines
6.1 KiB
Markdown
150 lines
6.1 KiB
Markdown
# 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
|