SSPARCSS Assembly Extension for VS Code

A VS Code extension for writing and running SSPARCSS assembly code (.a files) with syntax highlighting, code analysis, and an integrated cheatsheet for RISC-V and ARM architectures.

✨ Features

Syntax Highlighting - Full syntax highlighting for RISC-V and ARM assembly
Architecture Detection - Automatically detects RISC-V vs ARM based on your code
One-Click Build & Run - Press F5 to assemble and simulate
Status Bar Toggle - Click to switch between architectures
Integrated Output - Professional build output in VS Code
Built-in Cheatsheet - Comprehensive reference for instructions and peripherals
Code Analysis - Real-time error detection (immediate ranges, register validation)
First-Run Setup Wizard - Easy configuration on first launch

🆕 New in v1.1.0

📖 Built-in Cheatsheet

Open a comprehensive reference guide right inside VS Code with tabs for:

RISC-V - All RV32I instructions with examples
ARM - ARM7 instructions and condition codes
Peripherals - GPIO, LCD, Temperature sensor, RTC, DMAC
Examples - Working code snippets with English explanations
Shortcuts - All keyboard shortcuts and commands

Access it via: Command Palette → "SSPARCSS: Open Cheatsheet" or right-click menu

🔍 Code Analysis / Linting

Real-time error detection for common mistakes:

ADDI immediate range - Must be -2048 to 2047 (12-bit signed)
LUI immediate range - Must be 0 to 0xFFFFF (20-bit)
Shift amounts - Must be 0-31
Register validation - Checks for invalid register numbers
x0 write warning - Writing to RISC-V zero register has no effect
ARM offset range - Load/store offsets must be -4095 to 4095

🛠️ Setup Wizard

On first launch, the extension will:

Check if SSPARCSS is installed
Prompt you to select the SSPARCSS folder
Or direct you to download SSPARCSS if not installed

🚀 Quick Start

1. Open a `.a` file

The extension activates automatically when you open any .a assembly file.

2. Write your code

# RISC-V Example
lui x1, 0x12345
addi x1, x1, 0x678
sb x1, 0(x0)

; ARM Example
mov r0, #0x10
add r1, r0, #5
str r1, [r0]

3. Run it!

F5 - Assemble and run simulator
Ctrl+Shift+B - Assemble only (no simulator)

⌨️ Keyboard Shortcuts

Shortcut	Action
`F5`	Build & Run Simulator
`Ctrl+Shift+B`	Assemble Only
Click status bar	Toggle RISC-V / ARM

📋 Commands

Press Ctrl+Shift+P and type "SSPARCSS" to see all commands:

Command	Description
SSPARCSS: Run Simulator	Assemble and launch simulator
SSPARCSS: Assemble Only	Assemble without running
SSPARCSS: Open Cheatsheet	Open reference panel
SSPARCSS: Configure Paths	Set simulator/assembler location
SSPARCSS: Download SSPARCSS	Open download page
SSPARCSS: Set Architecture to RISC-V	Switch to RISC-V mode
SSPARCSS: Set Architecture to ARM	Switch to ARM mode

⚙️ Configuration

Open Settings → search for "SSPARCSS"

Setting	Default	Description
`ssparcss.simulatorPath`	`C:\Program Files\SSPARCSS\simulator.exe`	Path to simulator
`ssparcss.assemblerPath`	`C:\Program Files\SSPARCSS\assembler.exe`	Path to assembler
`ssparcss.defaultArchitecture`	`RISCV`	Default architecture

📁 Project Structure

When you build, the extension automatically creates these files in your source folder:

your-project/
├── program.a           # Your assembly source
├── program.e           # Compiled executable (generated)
├── RISC-V.system       # System config (auto-generated)
├── RISC-V.assembler    # Assembler config (auto-generated)
└── simulator.ini       # Simulator settings (auto-generated)

🔧 Using the Extension (Development Mode)

Run Without Installing

Open this folder in VS Code
Press F5 to launch Extension Development Host
In the new window, open any .a file
The extension is now active!

Install Locally (VSIX)

Package the extension:

npm install -g @vscode/vsce
vsce package

Install the generated .vsix file:
- In VS Code: Ctrl+Shift+P → "Extensions: Install from VSIX..."
- Select the .vsix file

Or via command line:

code --install-extension ssparcss-1.0.0.vsix

📦 Publishing to VS Code Marketplace

First-Time Setup

Create a publisher account:
- Go to Azure DevOps
- Create an organization (if needed)
- Go to Visual Studio Marketplace Publisher
- Create a publisher (e.g., "your-name")
Create a Personal Access Token (PAT):
- In Azure DevOps → User Settings → Personal Access Tokens
- Create new token with "Marketplace (Manage)" scope
- Copy and save the token!
Update package.json:
```
"publisher": "your-publisher-name"
```

Publish

# Login (first time only)
vsce login your-publisher-name

# Publish
vsce publish

Your extension will be available at:
https://marketplace.visualstudio.com/items?itemName=your-publisher.ssparcss

🔄 Updating the Extension

Update Version

# Patch version (1.0.0 → 1.0.1)
vsce publish patch

# Minor version (1.0.0 → 1.1.0)
vsce publish minor

# Major version (1.0.0 → 2.0.0)
vsce publish major

# Specific version
vsce publish 1.2.3

Manual Update Workflow

Make your code changes
Update version in package.json:
```
"version": "1.0.1"
```
Update CHANGELOG.md (create if needed)
Package and publish:
```
vsce publish
```

For Local VSIX Distribution

# Update version in package.json, then:
vsce package

# Share the new .vsix file with users
# They can update via:
code --install-extension ssparcss-1.0.1.vsix --force

📋 Changelog

1.0.0 (Initial Release)

Syntax highlighting for RISC-V and ARM
Architecture auto-detection
Build & Run with F5
Assemble-only with Ctrl+Shift+B
Status bar architecture toggle

🐛 Troubleshooting

Simulator/Assembler not found

Check Settings → SSPARCSS paths
Ensure SSPARCSS is installed at C:\Program Files\SSPARCSS\

Assembly fails but no error shown

Errors appear in the assembler GUI window
Check the assembler window before closing it

Wrong architecture detected

Click the status bar (RISC-V / ARM) to toggle
Or use Command Palette: "SSPARCSS: Set Architecture"

📄 License

MIT License - Free for educational and personal use.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Made with ❤️ for assembly programming students

SSPARCSS Assembly

Marin Hrvaćanin