# ivss (Project)

**[ivss](https://github.com/yanevskiv/ivss)** is a project I built to assemble, link, and execute programs for a hypothetical 32-bit CPU. It's written in C and includes an assembler, a linker, and an emulator. Assembly source becomes an object file, the linker combines objects and places sections in memory, and the emulator executes the resulting program.

The machine has sixteen general-purpose registers, including the stack pointer and program counter, and three control registers: status, handler, and cause. Its instructions cover arithmetic, memory access, branches, calls, and interrupts. The assembler handles labels, directives, and symbol references, while the linker combines sections and resolves symbols. The emulator applies relocation records when loading the linked program. The object representation uses ELF64 structures even though the simulated machine is 32-bit.

For example, this program loads two values, adds them, and halts:

```asm
.section my_code
    ld $5, %r1
    ld $7, %r2
    add %r2, %r1
    halt
.end
```

Save it as `main.s`. After building the tools with `make`, assemble it, place its code at the emulator's initial program-counter address, and run it:

```bash
$ ./asembler -hex -o main.o main.s
$ ./linker -hex \
    -place=my_code@0x40000000 \
    -o program.hex \
    main.o
$ ./emulator program.hex
```

The assembler's `-hex` option writes the serialized object format expected by the linker. The emulator prints the register state after execution; `r1` contains `0x0000000c`, or twelve. The executable name `asembler` follows the current Makefile. Programs can also use memory-mapped terminal and timer devices, with interrupt handlers responding to input or timer events. The repository's assembly examples demonstrate these interactions, and `-debug` enables instruction tracing in the emulator.

## Concepts

- [[ivss-machine-architecture|Machine architecture]]
  - [[ivss-general-purpose-registers|General-purpose registers]]
  - [[ivss-control-registers|Control registers]]
  - [[ivss-instruction-format|Instruction format]]
  - [[ivss-addressing-modes|Addressing modes]]
  - [[ivss-stack|Stack]]
- [[ivss-assembler|Assembler]]
  - [[ivss-instruction-parsing|Instruction parsing]]
  - [[ivss-instruction-encoding|Instruction encoding]]
  - [[ivss-labels|Labels]]
  - [[ivss-assembler-directives|Assembler directives]]
    - [[ivss-sections|Sections]]
    - [[ivss-symbol-visibility|Symbol visibility]]
    - [[ivss-data-allocation|Data allocation]]
    - [[ivss-constant-expressions|Constant expressions]]
  - [[ivss-pseudoinstructions|Pseudoinstructions]]
- [[ivss-object-files|Object files]]
  - [[ivss-elf-representation|ELF representation]]
  - [[ivss-symbol-table|Symbol table]]
  - [[ivss-string-table|String table]]
  - [[ivss-relocation-entries|Relocation entries]]
  - [[ivss-hex-serialization|Hex serialization]]
- [[ivss-linker|Linker]]
  - [[ivss-section-merging|Section merging]]
  - [[ivss-symbol-resolution|Symbol resolution]]
  - [[ivss-relocation-processing|Relocation processing]]
  - [[ivss-section-placement|Section placement]]
  - [[ivss-relocatable-linking|Relocatable linking]]
- [[ivss-emulator|Emulator]]
  - [[ivss-program-loading|Program loading]]
  - [[ivss-instruction-decoding|Instruction decoding]]
  - [[ivss-instruction-execution|Instruction execution]]
  - [[ivss-memory-access|Memory access]]
  - [[ivss-debug-tracing|Debug tracing]]
- [[ivss-interrupts|Interrupts]]
  - [[ivss-software-interrupts|Software interrupts]]
  - [[ivss-timer-interrupts|Timer interrupts]]
  - [[ivss-terminal-interrupts|Terminal interrupts]]
  - [[ivss-interrupt-masking|Interrupt masking]]
  - [[ivss-interrupt-handlers|Interrupt handlers]]
  - [[ivss-interrupt-return|Interrupt return]]
- [[ivss-memory-mapped-io|Memory-mapped I/O]]
  - [[ivss-terminal-output|Terminal output]]
  - [[ivss-terminal-input|Terminal input]]
  - [[ivss-timer-configuration|Timer configuration]]