damn_simple_architecture/docs/inconsistencies.md

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