verylogic Sail ISA Workspace
  • English

    • Hack with Sail

    The hack ISA family has two profiles. hack16 is the canonical 16-bit nand2tetris baseline; hack32 is a 32-bit Verylogic extension. Both keep a 15-bit PC/address space and 32768-word ROM and RAM. The module surrounds their shared Sail semantics with an assembler, runnable programs, assertions, and regression tests.

    Run it first

    Clone the repository, open its root directory, and run:

    git clone https://github.com/VIDLG/verylogic-workspace-sail.git
cd verylogic-workspace-sail
pixi run just hack list
pixi run just hack run multiply                    # defaults to hack16
pixi run just hack run multiply --profile hack32

    A successful program ends with ASSERT PASS and a dump of architectural state. The tutorial explains the output and follows the same program through every toolchain stage.

    Choose by goal

    If you want to understand…Read
    where Hack and Sail come from, and how to run a first programTutorial
    registers, memory, instruction bits, ALU operations, and jumpsISA guide
    how to add pseudoinstructions, tools, devices, or real ISA extensionsEvolve Hack
    symbols, Hack+ lowering, two-pass assembly, and .hack outputAssembler internals
    generated drivers, Sail's C backend, assertions, and testsExecution and tests
    exact commands, directives, and artifact comment levelsPackage reference

    One program, end to end

    The machine contract is split between shared model/core.sail, one self-contained model/profiles/<profile>.sail entry, and projects/<profile>.sail_project. Source translation belongs to the assembler; driver generation and native compilation belong to the executor; program discovery and command dispatch belong to workflow.

    Suggested learning sequence

    1. Complete the tutorial and inspect multiply.asm.
    2. Read the ISA guide while following one profile entry into its included model/core.sail and profile project.
    3. Use Evolve Hack to choose and specify a modification at the correct layer.
    4. Enter Toolchain internals and follow the same source through the assembler.
    5. Finish with the execution and test workflow.