Introduction

The Damn Simple Architecture

Instruction Set

Instruction Set

Overview

Below is an overview of the instruction set and the various operands. This table is non-exhaustive and may be updated as the design changes. Please note that the table spans multiple pages.

Also note that immediate (constant/literal) arguments are 16-bits long in I (immediate argument) typed instructions. For more information on this, refer to instruction encoding.

Note: J-type instructions are currently unused.

R-type Instruction Encoding

The shift amount must be 0 when the opcode does not match a shift instruction or else the CPU will assert an Illegal Instruction exception.

If any register field is not used, it should be set to the special value NOREG, defined in the Registers section of this document. Failure to do so may result in an Illegal Instruction exception as this is undefined for an instruction that does not expect this argument to be provided.

I-type Instruction Encoding

I-type instructions are used when 16-bit immediate arguments are desired. This could be for immediate arithmetic instructions (like adding 10 to the value in ACC), or loads and stores, where we may want to access the ith index of an array using an offset.

J-type Instruction Encoding

J-type instructions are used for absolute jumps.

The 26-bit address is converted to a 32-bit address by: The 26-bit address field is shifted left by 2 bits (due to word alignment we ignore the 2 least significant bits). Combined with the upper 4 bits of the PC to form a 32-bit address (bitwise OR).

The jump range: 256MB region around current PC. For longer jumps than this, see jr (Jump to word address in register).

To compute this address, the linker should find the address of the label, cut off the top 4 bits, then rightward shift twice. The CPU will then convert this to the actual 32-bit address following the steps outlined above.

Instructions

Hardware Instructions

DSA Assembly Language Instruction Reference

Overview

This document provides a comprehensive reference for the DSA (Damn Simple Architecture) assembly language, including all hardware instructions and pseudo-instructions with their syntax variations and usage examples.

Table of Contents

• Instructions
• Tooling
• Imports
• Calling Convention
• Examples

Instructions

This section is a complete overview of the assembly language and instructions. It includes both the hardware instructions that translate directly to machine code as well as pseudo instructions and directives that are translated to hardware instructions or directives by the assembler.

Instruction Types

• Hardware Instructions
• Pseudo Instructions
• Directives

Hardware Instructions

Data Movement Instructions

Examples:

mov rg0, rg1        ; Copy rg0 to rg1
movs rg0, rg1       ; Copy rg0 to rg1 with sign extension

Memory Access Instructions

Load Instructions

Examples:

; Direct register addressing
ldb rg0, rg1        ; Load byte from address in rg0
ldw rg0, rg1, 8     ; Load word from (rg0 + 8)

; Label addressing
ldb buffer, rg2     ; Load byte from label 'buffer'
ldw stack, bpr      ; Load stack address into base pointer

Label Expansions:

; ldb buffer, rg2 expands to:
lli buffer, rg2     ; Load lower 16 bits of buffer address
lui buffer, rg2     ; Load upper 16 bits of buffer address  
ldb rg2, rg2        ; Load byte from address in rg2

; ldw stack, bpr expands to:
lli stack, bpr      ; Load lower 16 bits of stack address
lui stack, bpr      ; Load upper 16 bits of stack address
ldw bpr, bpr        ; Load word from address in bpr

Store Instructions

Examples:

; Direct register addressing
stb rg0, rg1        ; Store byte from rg0 to address in rg1
stw rg0, rg1, 12    ; Store word to (rg1 + 12)

; Label addressing
stb acc, buffer     ; Store byte from accumulator to 'buffer'
stw rg1, current    ; Store word to 'current' variable

Label Expansions:

; stb acc, buffer expands to:
lli buffer, rgf     ; Load lower 16 bits of buffer address
lui buffer, rgf     ; Load upper 16 bits of buffer address
stb acc, rgf        ; Store byte from acc to 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        ; Store word from rg1 to address in rgf

Immediate Load Instructions

Usage

ensure that you always run Lli before Lui as Lli clears the upper 16 bits.

Examples:

lli 0x1234, rg0     ; Load 0x1234 into lower 16 bits of rg0
lui 0xABCD, rg0     ; Load 0xABCD into upper 16 bits of rg0

Jump Instructions

Examples:

jmp start           ; Jump to label 'start'
jmp 4, ret          ; Jump to address (4 + ret register)
jeq end             ; Jump to 'end' if equal flag set
jgt loop            ; Jump to 'loop' if greater than flag set

Arithmetic Instructions

Examples:

add rg0, rg1, rg2   ; rg2 = rg0 + rg1
sub rg0, rg1, rg2   ; rg2 = rg0 - rg1
iadd rg0, 10        ; rg0 = rg0 + 10
// or using alternate syntax
addi rg0, 1         ; rg0 = rg0 + 1
inc rg0             ; rg0 = rg0 + 1

Bitwise Operations

Examples:

and rg0, rg1, rg2   ; rg2 = rg0 & rg1
not rg0, rg1        ; rg1 = ~rg0

Shift Operations

Examples:

shl rg0, 2          ; Shift rg0 left by 2 bits
shr rg0, 3          ; Shift rg0 right by 3 bits

Comparison and Control

Examples:

cmp rg0, zero       ; Compare rg0 with zero register
cmp rg1, rg2        ; Compare rg1 with rg2

System Instructions

Examples:

hlt                 ; Stop processor execution
int 0x21            ; Trigger interrupt 0x21

Pseudo Instructions

Stack Operations

Examples:

push rg0            ; Push rg0 value onto stack
pop ret             ; Pop return address

Memory Access Shortcuts

Examples:

lwi string, rg1     ; Load address of 'string' into rg1

Data Directives

Data Definition

Examples:

db message: "Hello World", 0, 0x20, 231
dh numbers: 1000, 2000, 3000
dw stack: 0x10000

Notes:

• All string literals are automatically null-terminated

Memory Reservation

Examples:

resb buffer: 256    ; Reserve 256 bytes
resh array: 100     ; Reserve space for 100 half-words
resw heap: 1024     ; Reserve space for 1024 words

Imports

Usable Registers

Imports

Module System

Import Precedence

Notes:

• The order of imports may affect the order in which dependencies are placed into the output binary.
• Circular dependencies are allowed and fully supported.
• The module name is caller-defined and can be used to create aliases for libraries within the scope of the calling file. This makes namespacing easy.

Examples:

include print "./lib/print.dsa"
include maths "./lib/maths.dsa"

External Symbol Access Convention

External symbols are accessed using the :: operator.

Examples:

include print "./lib/print.dsa"

init:
    // ensure we have a stack setup so we can call functions properly

db string: "Hello world!"

start:
    // load the address of the string into rg1.
    lwi string, rg1
    // push the string address argument
    push rg1
    // call the print function
    call print::print
    // clean up the stack
    pop zero
    hlt

Calling Convention

Calling Convention

Notes:

• The namespace in step 2 is the name assigned in the include statement
• The call pseudo-instruction automatically handles return address management so long as the callee does not mess with the stack
• Arguments are accessed by the callee using offsets from the base pointer (bpr)

Function Control

Examples:

call-local.dsa

// ensure the stack is set up first!

caller:
    push rg0    
    push rg1

    call callee  // make call to a local function
    pop rg0     // put result in rg0
    pop zero    // void second return val

callee:
    // setup new stack frame
    push bpr
    mov spr, bpr

    // function body

    // restore the stack frame
    mov bpr, spr
    pop bpr
    return              ; Return from the current function

call-external.dsa

include external "./external.dsa"

// ensure the stack is set up first!
db string: "Hello, world!"
caller:
    // push args
    lwi string, rg0
    push rg0
    call external::callee // do something with the string
    pop zero

external.dsa

callee:
    // set up the stack
    push bpr
    mov spr, bpr

    // function body

    // restore the stack frame
    mov bpr, spr
    pop bpr
    return              ; Return from the current function

Examples

Library Examples

Multiplication Library (multiply.dsa)

// multiply.dsa
// usage:
//
// include multiply "<relative path>"
//
// usage for multiply:
// push (arg1)
// push (arg0)
// call multiply::multiply
// pop (arg0)
// pop (arg1)

multiply:
    push bpr
    mov spr, bpr

    ldw bpr, rg0, 8  // load op 1
    ldw bpr, rg1, 12 // load op 2

    lli 0, acc      // initialize accumulator

start:	
    add acc, rg0, acc
    dec rg1

    cmp rg1, zero
    jgt start

end:
    stw acc, bpr, 8  // store result for caller
    mov bpr, spr
    pop bpr
    return

Print Library (print.dsa)

// print.dsa
// usage:
//
// include print "<relative path>"
//      
// usage for print:
//      push (register containing address of string)
//      call print::print
//      pop zero
//
// usage for reset:
//      call print::reset

dw display: 0x20000
dw current: 0x20000

// prints the given text to the screen.
print:
    push bpr
    mov spr, bpr

    ldw bpr, rg0, 8    // get string address argument
    ldw current, rg1    // get current display position

print_loop:
    ldb rg0, acc
    stb acc, rg1

    iadd rg0, 1
    iadd rg1, 1

    cmp acc, zero
    jne print_loop
    jmp end

// return
end:
    stw rg1, current

    mov bpr, spr
    pop bpr
    return

// resets the cursor position on the screen
reset:
    push bpr
    mov spr, bpr
    ldw display, rg1
    stw rg1, current
    mov bpr, spr
    pop bpr
    return

Example Program (main.dsa)

include print "./print.dsa"

dw stack: 0x10000
db string: "'To confuse your enemy, you must first confuse yourself' - Probably Sun Tzu."

init:
    // set up a stack.
    ldw stack, bpr
    mov bpr, spr

start:
    lwi string, rg1

    // push string address argument
    push rg1
    // call print function
    call print::print
    // clean up stack
    pop rg1

    hlt

Tooling

Tooling Options

Assembler

• The assembler is the program that translates assembly code into machine code.
• It is the only tool required to build DSA assembly language programs.
• The assembler also works as a library that can be called from applications such as the emulator

Our Tooling:

• Assembler
• Syntax Tooling

Assembler

Building the Assembler

Clone the repository

git clone https://git.zxq5.dev/LowLevelDevs/damn_simple_architecture.git
cd damn_simple_architecture

Build the assembler

cd assembler
cargo build --release

Usage

<binary> -i <input_file.dsa> -o <output_file.dsb>

Syntax tooling

Syntax Highlighting

Emulator

• our custom Emulator has built-in syntax highlighting for the DSA assembly language. all files with the .dsa extension have the syntax applies

VSCode

• install our custom VSCode extension from the marketplace dsa-tooling.dsa-language-support

DSA Emulator

DSA Emulator

The DSA Emulator is a visual emulator that allows you to debug and test your programs in a controlled environment. It is composed of a control panel, memory inspector, and a built in editor.

The control panel lets you view all of the registers, step through the instructions, and view the current instruction counter.

The memory inspector lets you view any region of memory in the emulator.

The editor contains a built in assembler instance, so you can edit and assemble your code from the comfort of the emulator.

The loader is responsible for loading your code into memory so that the emulator can run it.

Building the Emulator

Features

Control Panel

Memory Inspector

Stack Inspector

Editor

Loader

Display

Instruction History

DSC - Damn Simple Code

This document is a work in progress!

Nothing is final!

Syntax

• we aim to make the syntax simple and easy to understand, this has the following benefits
  • easy to write
  • easy to parse
  • little variation in syntax means we have to handle less cases in semantic analysis, meaning we will be able to create a working compiler quicker.

Types

• we should support the following types
  • unsigned integer types (U8, U16, U32)
  • signed integer types (I8, I16, I32)
  • boolean type (Bool)
  • struct types (Struct)
  • dynamic types *(Dyn)

Functions

Other Language Support

Brainf*

Language overview

• Brainf* instructions are as follows:

Implementations

we currently have two implementations of the brainf* esoteric programming language:

Compiler

• this is the most efficient way to run brainf* programs on the DSA architecture, but of course, still terribly inefficient due to the nature of the language.
• compiling allows us to calculate the jump addresses at compile time, therefore making each brainf* instruction take at maximum three DSA instructions to execute

Interpreter

• this method is much slower, with even jumping to the start of a loop having an O(n) time complexity, which depending on the complexity of the program can up to double the running time.
• additionally, interpreting the language means much more logic is required at runtime relative to compiling.
• from our testing on a few example programs such as a fibonacci sequence generator, the interpreter is several orders of magnitude slower, with the fibonacci generator beingabout 10 times slower than it's compiled equivalent, at around 3.8 million instructions to generate and pretty-print the first 16 fibonacci numbers, compared to around 350,000 for the compiled version, which we estimate is about as efficient as brainf* can be on our architecture without writing an optimiser.

Usage

Compiling

• currently The DSA Assembler supports compiling brainf* programs, with the following command:

<assembler binary name> -brainf