Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Haskell compiler/asm/dasm toolkit for DCPU16 architecture.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
Main.hs Only optimize when assembling.
soyuz.cabal Woops, wrong github link. Name's changed.


Advanced utility library for the DCPU-16 architecture.

Core goals:

  • All outputs will be compatible with official tools, and follow any official specs.
  • Within that, go crazy with optimizations and features.
  • Provide both command line tools, and developer libraries.

Semi-recent library docs are at

Command Line Tool

There are three main modes. Currently, the most interesting one is for assembly.

$ ./soyuz --help
Сойуз 0.0.0, amtal <>

soyuz [OPTIONS] <FILE>

Mode of operation:
  -p --prettyprint      Assembly -> consistently formatted assembly
  -a --assemble         Assembly -> machine code
  -d --disassemble      Machine code -> assembly
     --no-optimize      Disable short literal/label optimization
  -o --output=<FILE>    Write to file instead of stdout
  -h --hexdump          Encode binary data in a 16-bit hexdump
     --smooth-brackets  Parse (a) instead of [a] for indirect mode
  -? --help             Display help message
  -V --version          Print version information

Documentation and source at or on Hackage.
$ ./soyuz asm/notchspec.asm -a -h
0000: 7c01 0030 7de1 1000 0020 7803 1000 c00d
0008: ddc1 a861 7c01 2000 2161 2000 8463 806d
0010: b1c1 9031 d410 ddc1 9037 61c1 ddc1
$ ./soyuz asm/notchspec.asm -a -h --no-optimize
0000: 7c01 0030 7de1 1000 0020 7803 1000 7c0d
0008: 0010 7dc1 0021 7c61 000a 7c01 2000 2161
0010: 2000 7c63 0001 7c6d 0000 7dc1 000f 7c31
0018: 0004 7c10 001e 7dc1 0021 7c37 0004 61c1
0020: 7dc1 0021

The disassembler mode is straightforward. No heuristics to avoid mixed in dat instructions and other pitfalls - but it does add obvious labels.

$ ./soyuz asm/notchspec.asm -a -o notch.bin
$ ./soyuz notch.bin -d
                set a, 0x30
                set [0x1000], 0x20
                sub a, [0x1000]
                ifn a, 0x10
                set pc, 0x17
                set i, 0xa
                set a, 0x2000
:jump.000c      set [i], [0x2000+a]
                sub i, 1
                ifn i, 0
                set pc, 0xc
                set x, 4
                jsr 0x15
                set pc, 0x17
:func.0015      shl x, 4
                set pc, pop
:jump.0017      set pc, 0x17

Finally, pretty-print mode consistently re-formats the input.

$ ./soyuz asm/notchspec.asm -p
; Try some basic stuff
                set a, 0x30             ; 7c01 0030
                set [0x1000], 0x20      ; 7de1 1000 0020
                sub a, [0x1000]         ; 7803 1000
                ifn a, 0x10             ; c00d 
                set pc, crash           ; 7dc1 001a [*]
; Do a loopy thing
                set i, 0xa              ; a861
                set a, 0x2000           ; 7c01 2000
:loop           set [0x2000+i], [a]     ; 2161 2000
                sub i, 1                ; 8463
                ifn i, 0                ; 806d
                set pc, loop            ; 7dc1 000d [*]
; Call a subroutine
                set x, 4                ; 9031
                jsr testsub             ; 7c10 0018 [*]
                set pc, crash           ; 7dc1 001a [*]
:testsub        shl x, 4                ; 9037
                set pc, pop             ; 61c1
; Hang forever. X should now be 0x40 if everything went right.
:crash          set pc, crash           ; 7dc1 001a [*]
; [*]: Note that these can be one word shorter and one cycle faster by using the short form (0x00-0x1f) of literals,
;      but my assembler doesn't support short form labels yet.     

Installing Soyuz

For the command line tool, either:

  • Get a binary for Ubuntu.
  • Build from source. Get the Haskell Platform and either:
    • cabal install soyuz for 0.0.0 from Hackage
    • git clone git://; cd soyuz; cabal install for HEAD

Parser Error Messages

No really, they're quite nice. They're even coloured!*

Here, valid label characters are explained:

tasm/opt.asm:2:3: error: label definition "a" clashes with register name, expected: ".",
    "_", letter or digit

Again, pretty specific about what's expected:

test.masm:2:19: error: expected: "0", "[",
    "a", "b", "c", "i", "j", "o", "pc", "peek",
    "pop", "push", "sp", "x", "y", "z", digit,
    letter or digit
              set #a, 0x30              ; 7c01 0030 

No stupid mistakes allowed:

lower.masm:14:29: error: label "lop" not defined
                 set pc, lop          ; 7dc1 000d [*] 
  • No colour visible in copy-pastes.
Something went wrong with that request. Please try again.