Overview

Kevin's Development Environment for DCPU

Assembler

Example:

$ python3 kasm.py notch.s

Additional Syntax Supported:

  • .equ Assign a literal value to a label. For example .equ answer 42 will replace all occurrences of answer (after its declaration) with the value 42.

  • .org Set the program counter to the specified value. Can be used multiple times in a program.

  • .list, .nolist Enable and disable actual code generation. Equates and macros are processed regardless.

  • .include Takes a double quote enclosed string of a filename to include.

  • .macro Preprocessor macros. Terminated with .end. Example: .macro SUM(x,y) x+y .end, then dat SUM(1,1) will produce 0x0002. Macros can span multiple lines.

  • Character literals Single quotes around one character (e.g. 'a') will be translated to numerical literals. If the quotes are prefixed with character p, two character will be packed together.

  • Repeated data .rep 2 dat 0xbeef .end will produces 0xbeef 0xbeef. The repeated block can be any instructions over multiple lines.

  • Current address variable $ gives the address of the current statement.

  • Packed Strings Prefixing a string with the character p will pack the data. p"1234" will produce 0x3132 0x3334.

  • Local Labels Labels that start with '.' will be rewritten as global.local where local is the name after the '.' and global is the last declared label which does not start with '.'.

  • Directives can be prefixed with '.' or '#'.

Optimizations:

  • Short labels: When labels resolve to a value less than 0x20, the will be encoded as short literals in the instruction.

  • Relative moves: When doing set PC, label, if label is within 0x20 bytes of the set instruction it will be replaced with an add PC, [...] (or sub).

  • NOP removal Instructions which can be determined to assign to a literal value, and will not modify the O register, will be removed.

Features:

  • Relocatable Binaries: Binaries can be produced with a builtin loader that will correct label based addresses to account for the program starting at an arbitrary origin. Use of the origin directive is disabled when creating relocatable binaries. The cost is 14+n words of memory and 12+10n cycles where n is the number of label references.

Important flags:

  • -l warn Enables logger warnings; Currently notifies of divide by zero, and org w/ relocatable

  • --disable-optimizations Disable all of the previously mentioned optimizations.

  • --strict Do not allow relaxed syntax. This includes colon on the right labels and repeated data.

  • --relocatable Make the produced binary relocatable

Disassembler

Example:

$ python3 kdis.py a.out

Simulator/Debugger

Example:

$ python3 ksim.py a.out

Important Flags:

  • -d Start an interactive debugging session. Information on the available commands is available by typing help at the command prompt. The default behavior without this flag is equivalent to calling:

    continue
    info
    memory
    render
    

Flags for all programs

  • --little-8-bit Treat binary code as byte-wise 8 bit little endian for compatibility with some other programs.

  • --output [file] or -o [file] Where to send output. The assembler defaults to a.out, the disassembler and simulator default to stdout.