isa-dsl 0.1.2

Domain Specific Language for Instruction Set Architecture descriptions

ISA DSL - Instruction Set Architecture Domain Specific Language

A powerful Domain Specific Language (DSL) for describing Instruction Set Architectures (ISA) using textX. This DSL enables you to specify instruction formats, registers, instruction encodings, and behavior in RTL (Register Transfer Level) notation, with automatic code generation for simulators, assemblers, disassemblers, and documentation.

Features

• Complete ISA Specification: Define instruction formats, registers (GPRs, SFRs, and vector registers), and instruction encodings
• RTL Behavior: Specify instruction behavior using Register Transfer Level notation with support for:
  • Arithmetic and logical operations
  • Conditional statements
  • Memory access operations
  • Vector/SIMD operations
• Automatic Code Generation: Generate production-ready tools:
  • Python-based instruction simulators
  • Assemblers for your ISA
  • Disassemblers for binary code
  • Markdown documentation
• SIMD Support: Built-in support for vector registers and SIMD instructions
• Validation: Comprehensive semantic validation of ISA specifications
• Language Server Protocol (LSP) Support: Full IDE integration with VS Code extension providing:
  • Real-time syntax highlighting
  • Code completion
  • Hover documentation
  • Error diagnostics

Installation

Prerequisites

• Python 3.8 or higher
• UV (recommended) or pip

Using UV (Recommended)

UV is a fast Python package manager. Install it first:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or on Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Then install the project:

# Clone the repository
git clone <repository-url>
cd isa-dsl

# Install the project and dependencies
uv sync

# Or install in development mode with test dependencies
uv sync --dev

Using pip (Alternative)

# Clone the repository
git clone <repository-url>
cd isa-dsl

# Install dependencies
pip install -r requirements.txt

# Or install in editable mode
pip install -e .

Quick Start

1. Define your ISA in a .isa file (see examples/arm_cortex_a9.isa for a multi-file example)

2. Generate tools:

# Using UV
uv run isa-dsl generate examples/arm_cortex_a9.isa --output output/

# Or using Python directly
python -m isa_dsl.cli generate examples/arm_cortex_a9.isa --output output/

3. Use the generated tools:

# Validate your ISA
uv run isa-dsl validate examples/arm_cortex_a9.isa

# Get ISA information
uv run isa-dsl info examples/arm_cortex_a9.isa

# Run the generated simulator
python output/simulator.py program.bin

Documentation

All technical documentation is available in the docs/ folder:

• INDEX.md: Documentation index and navigation guide - Start here to find what you need
• DSL_Specification.md: Complete DSL specification covering all features including syntax, registers, formats, instructions, RTL behavior, variable-length instructions, bundling, SIMD, and more
• EXAMPLES.md: Detailed documentation of example ISA specifications with learning paths and common patterns
• TESTING.md: Complete testing documentation including test suite overview, how to run tests, and how to add new tests
• LANGUAGE_SERVER.md: Language Server Protocol (LSP) setup and usage guide for VS Code extension

Examples

The examples/ directory contains reference ISA specifications demonstrating best practices:

• arm_cortex_a9.isa: Main ARM Cortex-A9 ISA specification (multi-file reference)
  • arm_cortex_a9_registers.isa - Register definitions
  • arm_cortex_a9_formats.isa - Instruction format definitions
  • arm_cortex_a9_instructions.isa - Instruction definitions

This demonstrates the multi-file approach using #include directives and cross-file format reference resolution.

Note: Test-specific ISA examples are located in tests/*/test_data/ directories.

To generate tools from the reference example:

uv run isa-dsl generate examples/arm_cortex_a9.isa --output output/

Command-Line Interface

The isa-dsl command provides several subcommands:

Generate Tools

uv run isa-dsl generate <isa_file> --output <output_dir>

Options:

• --simulator / --no-simulator: Generate simulator (default: enabled)
• --assembler / --no-assembler: Generate assembler (default: enabled)
• --disassembler / --no-disassembler: Generate disassembler (default: enabled)
• --docs / --no-docs: Generate documentation (default: enabled)

Validate ISA

uv run isa-dsl validate <isa_file>

Display ISA Information

uv run isa-dsl info <isa_file>

Testing

The project includes a comprehensive test suite with 111 automated tests covering:

• Core functionality: ISA parsing, validation, RTL interpretation
• Code generation: Assembler, simulator, disassembler, documentation generators
• Advanced features: Variable-length instructions, instruction bundling, distributed operands
• Integration tests: End-to-end workflows, QEMU verification, ARM toolchain integration
• Multi-file support: Include processing, inheritance, merge modes
• Assembly syntax: Formatting, literal braces, backward compatibility
• VS Code Extension: Language server tests (18 tests) for LSP functionality

Running Tests

# Run all Python tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run with coverage
uv run pytest --cov

# Run specific test suite
uv run pytest tests/arm/

# Run VS Code extension tests
cd vscode_extension/isa/packages/language && npm test

Test Status:

• ✅ All 111 Python tests passing, 0 skipped, 0 failed
• ✅ All 18 VS Code extension tests passing
• ✅ Continuous Integration (CI) runs all tests automatically on push/PR

Development

Setup Development Environment

# Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies (including dev dependencies)
uv sync --dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov

Code Quality

• All test functions are limited to 50 lines or less
• All test files are limited to 500 lines or less
• Helper functions are organized as class methods in separate files
• Comprehensive test coverage across all major features

Requirements

• Python 3.8+
• textX >= 3.0.0
• Jinja2 >= 3.1.0
• Click >= 8.1.0

For development:

• pytest >= 7.4.0
• pytest-cov >= 4.1.0

Deployment

Production Readiness

✅ Ready for deployment - The project is production-ready with:

• Comprehensive test suite (111 tests, all passing)
• Well-documented API and CLI interface
• Modular, maintainable codebase
• Complete documentation
• Example ISA specifications
• Validation and error handling

Installation for Production

# Using UV (recommended)
uv sync

# Or using pip
pip install -r requirements.txt
pip install -e .

Building Distribution Packages

# Build wheel and source distribution
python -m build

# Or using UV
uv build

License

MIT License

Contributing

Contributions are welcome! Please ensure that:

• All tests pass (uv run pytest)
• Code follows existing style conventions
• Documentation is updated for new features
• Test functions are kept under 50 lines
• Test files are kept under 500 lines