* Initial

2026-06-15 19:20:24 +02:00
commit 331f96efe4
22 changed files with 3840 additions and 0 deletions
@@ -0,0 +1,105 @@
+# Getting Started with ReviveSparc
+
+This guide will walk you through building ReviveSparc from source and running your first SPARC program.
+
+## Prerequisites
+
+- **Linux** (x86_64 or aarch64) or **macOS** (Intel or Apple Silicon)
+- **GCC** or **Clang** (C11 support required)
+- **Make** (3.81 or later)
+- **CMake** (3.20 or later)
+- **Git**
+
+Optional but recommended:
+- `gcc-sparc-linux-gnu` for cross-compiling SPARC Linux programs
+- `qemu-system-sparc64` for comparison testing
+
+## Building from Source
+
+Clone the repository:
+
+```bash
+git clone https://github.com/revivesparc/revivesparc.git
+cd revivesparc
+```
+
+Build the emulator:
+
+```bash
+make
+```
+
+The resulting binary is `sparc-emu` in the project root directory.
+
+### Build Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `DEBUG=1` | Enable debug symbols and verbose logging | off |
+| `OPT=0` | Disable optimizations | off |
+| `TRACE=1` | Enable instruction tracing | off |
+| `CC=clang` | Use Clang instead of GCC | gcc |
+
+Example with debug enabled:
+
+```bash
+make DEBUG=1
+```
+
+## Running the Test Suite
+
+```bash
+make test
+```
+
+This runs the ISA verification suite, which tests every implemented instruction against known-good results.
+
+## Your First SPARC Program
+
+Create a file `hello.S` with the following SPARC assembly:
+
+```asm
+.section ".text"
+.global _start
+
+_start:
+    save    %sp, -96, %sp
+    mov     1, %g1        ! SYS_write
+    mov     1, %o0        ! fd = stdout
+    sethi   %hi(msg), %o1
+    or      %o1, %lo(msg), %o1
+    mov     13, %o2       ! length
+    ta      0x6d          ! trap to kernel
+    clr     %o0           ! status = 0
+    mov     1, %g1        ! SYS_exit
+    ta      0x6d
+
+.section ".data"
+msg:
+    .asciz "Hello, SPARC!\n"
+```
+
+Assemble and link using the SPARC cross-toolchain:
+
+```bash
+sparc-linux-as hello.S -o hello.o
+sparc-linux-ld hello.o -o hello
+```
+
+Run it under ReviveSparc:
+
+```bash
+./sparc-emu hello
+```
+
+You should see:
+
+```
+Hello, SPARC!
+```
+
+## Next Steps
+
+- Read the [Build Guide](build-guide.md) for advanced build configurations
+- Explore the [ISA Reference](isa-reference.md) for instruction set details
+- Check the [FAQ](faq.md) for common questions