ISA DSL Language Server

A comprehensive VS Code extension providing language support for the ISA DSL (Instruction Set Architecture Domain Specific Language). This extension offers syntax highlighting, code completion, validation, and seamless integration with the ISA-DSL Python toolchain.

Features

🎨 Language Support

• Syntax Highlighting: Full syntax highlighting for .isa files
• Code Completion: Intelligent autocomplete for ISA DSL keywords, instruction formats, registers, and more
• Hover Documentation: Get instant information about ISA elements by hovering over them
• Error Diagnostics: Real-time validation with detailed error messages

🔧 Integrated Toolchain

• Install Python Package: Install the isa-dsl Python package directly from VS Code using uv
• Generate Tools: Generate simulators, assemblers, disassemblers, and documentation
• Validate ISA Files: Validate your ISA specification files
• View ISA Info: Get detailed information about your ISA specification

📝 ISA DSL Capabilities

• Define instruction formats with field specifications
• Specify registers (GPRs, SFRs, vector registers)
• Define virtual registers (concatenated registers)
• Create register aliases
• Define register fields with bit ranges (C union-like access)
• Define instruction encodings (hex and decimal values)
• Specify instruction behavior using RTL (Register Transfer Level) notation
• Support for temporary variables in RTL behavior
• Support for hexadecimal values in behavior expressions
• Bitwise shift operations (<<, >>)
• Ternary conditional expressions (condition ? then : else)
• Bitfield access syntax (value[msb:lsb])
• Built-in functions (sign_extend, zero_extend, extract_bits, to_signed, to_unsigned and aliases)
• External behavior functions for complex instructions
• Bundle instruction formats for VLIW architectures
• Instruction aliases for alternative mnemonics

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "ISA DSL Language Server"
4. Click Install

From VSIX File

1. Download the .vsix file
2. Open VS Code
3. Go to Extensions → ... (More Actions) → Install from VSIX...
4. Select the downloaded .vsix file

Requirements

• VS Code: Version 1.67.0 or higher
• Python: Python 3.8 or higher (for ISA-DSL Python package)
• UV (Optional but recommended): For managing the Python package installation

Quick Start

1. Install the Python Package

After installing the extension, you need to install the ISA-DSL Python package:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run: ISA-DSL: Install Python Package
3. The extension will use uv to install isa-dsl in your workspace

Alternatively, install manually:

pip install isa-dsl
# Or using uv:
uv tool install isa-dsl

2. Create an ISA File

Create a new file with the .isa extension:

architecture SimpleRISC {
    word_size: 32
    endianness: little
    
    registers {
        gpr R 32 [8]
        sfr PC 32
    }
    
    formats {
        format R_TYPE 32 {
            opcode: [0:5]
            rd: [6:8]
            rs1: [9:11]
            rs2: [12:14]
        }
    }
    
    instructions {
        instruction ADD {
            format: R_TYPE
            encoding: {
                opcode=0x01
            }
            operands: rd, rs1, rs2
            behavior: {
                R[rd] = R[rs1] + R[rs2];
            }
        }
    }
}

3. Use Extension Commands

Right-click on an .isa file or use the Command Palette to access:

• ISA-DSL: Generate - Generate simulators, assemblers, disassemblers, and documentation
• ISA-DSL: Validate - Validate your ISA specification
• ISA-DSL: Info - View detailed information about your ISA

Commands

Features in Detail

Syntax Highlighting

The extension provides comprehensive syntax highlighting for:

• Keywords (instruction, format, register, etc.)
• Register names and field accesses
• Hex values (0x0B) and binary values (0b1010)
• RTL expressions and operators
• Comments (single-line // and multi-line /* */)

Code Completion

Intelligent autocomplete suggestions for:

• ISA DSL keywords
• Register names and field names
• Instruction format names
• Operand specifications
• RTL operators and functions

Validation

Real-time validation checks for:

• Format field definitions and overlaps
• Register specifications
• Instruction encoding validity
• Operand references
• Virtual register component validation
• Register alias references
• RTL expression syntax

Integrated Python Toolchain

The extension seamlessly integrates with the ISA-DSL Python package:

• Cross-platform: Works on Linux, Windows, and macOS
• Automatic Detection: Automatically finds uv or isa-dsl in your PATH
• Output Channels: All command outputs are displayed in dedicated VS Code output channels
• Error Handling: Clear error messages with actionable suggestions

Example ISA Specifications

Virtual Registers

registers {
    gpr D 32 [16]
    virtual register E 64 = {D[0]|D[1]}
}

Register Aliases

registers {
    gpr R 32 [16]
    alias SP = R[13]
    alias LR = R[14]
}

Instruction with Hex Encoding

instruction ABS {
    format: R_TYPE
    encoding: {
        op1=0x0B,
        op2=28
    }
    operands: s2, d
    behavior: {
        D[d] = (D[s2] >= 0) ? D[s2] : (0 - D[s2]);
    }
}

External Behavior Functions

instruction COMPLEX_OP {
    format: R_TYPE
    encoding: {
        opcode=0x10
    }
    operands: rd, rs1, rs2
    external_behavior: True
}

Configuration

The extension uses the default VS Code settings. No additional configuration is required. The extension will automatically:

• Associate .isa files with the ISA DSL language
• Provide language features for all .isa files in your workspace
• Detect and use the ISA-DSL Python package from your environment

Troubleshooting

Python Package Not Found

If you see errors about the Python package not being found:

1. Install the package using the extension command: ISA-DSL: Install Python Package
2. Or install manually: pip install isa-dsl or uv tool install isa-dsl
3. Ensure Python is in your PATH

Validation Errors

If you see validation errors:

1. Check that your ISA file syntax is correct
2. Verify that all referenced formats and registers are defined
3. Ensure encoding values fit within field widths
4. Check that virtual register component widths sum correctly

Command Not Working

If commands fail:

1. Check the Output panel for detailed error messages
2. Verify that uv or isa-dsl is installed and in your PATH
3. Try running the command from the terminal to see the actual error

Contributing

Contributions are welcome! Please see the main repository for contribution guidelines:

Repository: https://github.com/ajithpadman/isadsl

License

This extension is licensed under the MIT License. See the LICENSE file for details.

Links

• Repository: https://github.com/ajithpadman/isadsl
• Python Package: PyPI - isa-dsl
• Issues: GitHub Issues

Release Notes

See RELEASE_NOTES.md for detailed release notes and changelog.

Support

For issues, questions, or feature requests, please open an issue on GitHub:

https://github.com/ajithpadman/isadsl/issues

Enjoy using ISA DSL! 🚀