LinxISA: Block-Structured Instruction Set Architecture

---

What is LinxISA?

LinxISA is a block-structured instruction set architecture (ISA) designed for high-performance computing. Unlike traditional scalar ISAs, LinxISA organizes instructions into blocks that execute as atomic units, enabling:

• Explicit block boundaries with mandatory control-flow integrity
• Two-layer state model (global + block-local state)
• Vector/tile extensions for SIMD-style parallelism
• Template blocks for function prologues/epilogues and accelerator operations

This repository serves as the superproject that pins together all ecosystem components: compiler (LLVM), emulator (QEMU), Linux kernel, RTL (LinxCore), and standard libraries (glibc, musl).

---

Quick Start

Clone with Submodules

git clone --recurse-submodules git@github.com:LinxISA/linx-isa.git
cd linx-isa
git submodule sync --recursive
git submodule update --init --recursive

Run Validation Gates

# Canonical ISA + AVS contract validation
python3 tools/isa/build_golden.py --profile v0.4 --check
python3 tools/isa/validate_spec.py --profile v0.4
python3 tools/bringup/check_avs_contract.py --matrix avs/linx_avs_v1_test_matrix.yaml
python3 tools/bringup/check_avs_profile_closure.py --matrix avs/linx_avs_v1_test_matrix.yaml --status avs/linx_avs_v1_test_matrix_status.json --tier pr

# Full regression suite
bash tools/regression/run.sh

---

Repository Structure

linx-isa/
├── avs/                    # Architecture Validation Suite
│   ├── qemu/              # Runtime AVS tests (QEMU)
│   ├── compiler/          # Compile-only AVS tests (LLVM)
│   └── runtime/           # Freestanding libc support
│
├── compiler/              # LLVM submodule (linx-isa target)
├── emulator/              # QEMU submodule (linx-isa emulation)
├── kernel/                # Linux kernel submodule
├── rtl/                   # LinxCore RTL submodule
├── lib/                   # Standard libraries (glibc, musl)
│   ├── glibc/
│   └── musl/
│
├── tools/                 # Build scripts, generators, regression
│   ├── bringup/          # Bring-up orchestration
│   ├── regression/       # Test runners
│   └── pyCircuit/        # ISA model (submodule)
│
├── workloads/             # Benchmarks and kernels
│   └── pto_kernels/     # PTO accelerator kernels (submodule)
│
├── isa/                   # ISA specification sources
│   ├── v0.4/            # live canonical ISA definition
│   ├── v0.3/            # archived v0.3 ISA definition
│   └── generated/        # Generated encodings/decoders
│
└── docs/                  # Architecture & bring-up documentation
    ├── architecture/      # ISA manual and references
    ├── bringup/          # Bring-up status and gates
    ├── reference/        # Examples and guides
    └── project/          # Navigation and policies

---

Submodules

Submodule	Repository	Purpose
compiler/llvm	LinxISA/llvm-project	LLVM-based compiler for Linx
emulator/qemu	LinxISA/qemu	QEMU-based emulator
kernel/linux	LinxISA/linux	Linux kernel port
rtl/LinxCore	LinxISA/LinxCore	RTL implementation
tools/pyCircuit	LinxISA/pyCircuit	ISA reference model
lib/glibc	LinxISA/glibc	GNU C Library port
lib/musl	LinxISA/musl	musl libc port
workloads/pto_kernels	LinxISA/PTO-Kernel	PTO accelerator kernels

Updating Submodules

# Sync and update all submodules
git submodule sync --recursive
git submodule update --init --recursive

# Pull latest from upstream
git submodule update --remote compiler/llvm emulator/qemu kernel/linux rtl/LinxCore tools/pyCircuit lib/glibc lib/musl workloads/pto_kernels

# Verify layout
bash tools/ci/check_repo_layout.sh

---

Validation & Testing

Core Gates

Gate	Command	Description
AVS Contract	python3 tools/bringup/check_avs_contract.py --matrix avs/linx_avs_v1_test_matrix.yaml	Public v0.4 bring-up contract schema + reference validation
AVS Closure	python3 tools/bringup/check_avs_profile_closure.py --matrix avs/linx_avs_v1_test_matrix.yaml --status avs/linx_avs_v1_test_matrix_status.json --tier pr	Tier-scoped AVS closure status
Sail Model	python3 tools/bringup/check_sail_model.py	Sail wording, status, and parser/typecheck gate
Compiler AVS	cd avs/compiler/linx-llvm/tests && ./run.sh	LLVM code generation tests
QEMU Runtime	cd avs/qemu && ./run_tests.sh --all	Emulator execution tests
Linux Boot	python3 kernel/linux/tools/linxisa/initramfs/smoke.py	Kernel boot validation

Regression Suites

# Main regression (fast)
bash tools/regression/run.sh

# Full stack (includes Linux boot)
bash tools/regression/full_stack.sh

# Strict cross-repo (release gates)
bash tools/regression/strict_cross_repo.sh

---

Documentation

• Website: https://linxisa.github.io/
• Getting Started - Onboarding guide
• Architecture Contract - ISA v0.4 specification
• Bring-up Progress - Current status tracking
• Navigation Guide - Repository layout policy
• ISA Manual - Complete ISA documentation

---

Versioning

• ISA Version: v0.4 (current)
• Repository: This superproject pins specific commits of all ecosystem repos
• Release Notes: See docs/releases/ for version history

---

Contributing

1. Follow the navigation policy
2. Implement changes in the relevant submodule first
3. Run validation gates locally before submitting
4. Update submodule SHAs in this workspace
5. Ensure tools/ci/check_repo_layout.sh passes

---

License

See LICENSE file for details.