SN/X Simulator

A Python toolchain (assembler, static analyzer, and simulator) for the SN/X architecture, a 16-bit educational RISC processor described in Naohiko Shimizu (清水尚彦)'s book コンピュータ設計の基礎知識.

Features

• Complete SN/X instruction set — ADD, AND, SUB, SLT, NOT, SR, HLT, LD, ST, LDA, IN, OUT, BZ, BAL
• Data Initialization — DW directive for preloading Data Memory (DMEM)
• Integrated static analysis — CFG, dataflow analysis, memory bounds checking, domain-sensitive label rules
• CLI + Python API — Use from command line or as a library
• snxasm compatible — Produces identical binary output to the original assembler

Table of Contents

• Requirements
• Quick Start
• Installation
• CLI Usage
• Python API
• Documentation
• License

Requirements

• Python 3.11 or higher
• uv (recommended)
• pipx (optional)

Quick Start

Option 1 — One-off execution (no install):

# via uv (recommended)
uvx --from snx-simulator snx sample.s

# via pipx
pipx run --spec snx-simulator snx sample.s

Option 2 — Global install (recommended for CLI usage):

# via uv (recommended)
uv tool install snx-simulator

snx sample.s

# via pipx
pipx install snx-simulator

snx sample.s

Option 3 — Install via pip (for an existing Python environment / venv):

pip install snx-simulator
snx sample.s

Installation

Install uv (Recommended)

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Global Installation (uv)

Install snx as a system-wide command:

uv tool install snx-simulator

Or from a local clone (for development):

git clone https://github.com/snowykr/snx-simulator.git
cd snx-simulator
uv tool install .

If snx is not found after installation:

uv tool update-shell

To uninstall:

uv tool uninstall snx-simulator

Global Installation (pipx)

Install snx as a system-wide command:

pipx install snx-simulator

If snx is not found after installation:

pipx ensurepath

To uninstall:

pipx uninstall snx-simulator

Install via pip

pip install snx-simulator

Project-local / Development Setup

For IDE integration or contributing:

git clone https://github.com/snowykr/snx-simulator.git
cd snx-simulator
uv sync

Then run with:

uv run snx sample.s

Or activate the virtual environment:

source .venv/bin/activate  # Windows: .venv\Scripts\activate
snx sample.s

CLI Usage

snx [-h] [-V] PATH

Option	Description
PATH	Path to an SN/X assembly source file (.s)
-h, --help	Show help message
-V, --version	Show version number

Examples:

snx sample.s
snx path/to/program.s
uv run snx sample.s

The CLI will:

1. Parse and compile the assembly source
2. Run static analysis (errors, warnings, and domain-sensitive label checks)
3. If no errors, execute the program with preloaded DW data and display a trace table

Python API

from snx import compile_program, SNXSimulator

source = """
main:
    LD $1, my_data
    OUT $1
    HLT
my_data:
    DW 42
"""

result = compile_program(source)
if result.has_errors():
    print(result.format_diagnostics())
    raise SystemExit(1)

sim = SNXSimulator.from_compile_result(result)
sim.run()
print(f"Final registers: {sim.regs}")

See Python API documentation for full reference.

Documentation

Document	Description
Architecture	SN/X processor specifications, instruction formats, ISA reference
Assembly Language	Syntax, grammar, operand types
Python API	Library usage, compile_program, SNXSimulator
Static Analysis	Diagnostic codes, CFG, dataflow analysis

License

This project is open source. See the LICENSE file for details.