Introduction

DASM is a DCPU-16 assembler, disassembler and emulator kit. The DCPU-16 instruction set v1.1 is implemented, with a few extensions. This is not a macro assembler, yet. The assembler supports the syntax given as examples as part of the specification, with a few extensions.

Usage

To assemble a file, use:

./dasm.pl -o <output>.dump <input>.dasm

The dump format produced is a linked textual dump, in the same format as that given in the DCPU-16 specification.

To disassemble a file, use:

./dasm.pl -o <output>.dasm <input>.dump

The output disassembly file should be able to be reassembled. The argument to -o may by an extension, prefixed by a '.' character, to display the output.

For example, to display a disassembly of a file, use:

./dasm.pl -o .dasm <input>.dump

The internal structures used by the file can be displayed by omitting any output:

./dasm.pl <input>.dasm

To execute the input files, add the '-run' option to the command line, for example:

./dasm.pl -run <input>.dasm

Execution of the code begins at address 0.

There may be multiple input files on the command line which will be assembled in order.

Source assembly file format

The source assembly format is given as an example in the DCPU-16 specification. Operands (called 'values' in the specification) take the form specified in the specification, with the exception that the [SP] type specification is not supported (PUSH, PEEK and POP are far clearer).

The following format is expected:

• ; <comment>
  ... comment lines, which will be ignored.
  Comments may also be appended to all lines

• .<directive> <parameters>
  ... directives to the assembler, outside of the specification of the CPU. See below.

• :<label>
  ... address labels may appear at the start of any line, or on their own line and will refer to the current assembly location.
  Labels may be prefixed by a '$' character to make them 'local'. This prepends the last, non-$-prefixed label to the symbol name.

• <basic-opcode> <operand a>, <operand b>
<extended-opcode> <operand>
  ... the basic opcodes support two operands in line with the specification.
  Extended opcodes ('non-basic' in the specification) at present only support a single operand, although the bulk of the instruction space is free so may vary.

• <special-opcode> <operands>
  ... special opcodes are supported by this assembler, which allow literal values to be written to the code. These are not defined by the DCPU specification, see below.

Directives

Directives indicate to the assembler how the code should be processed. The following directives are supported at present:

• .ORIGIN <address>
  ... change the assembly location to the address given.

• .INCLUDE "file"
  ... include a file at the current location.
  The file's format is determined by its extension, so it is possible to mix source file formats (eg include an address dump within the source file being assembled, or a second assembler file).

Special opcodes

Special 'opcodes' provide shortcuts or necessary additions to the assembly format. The 'opcodes' supported at present are:

• DAT <operand>[,<operand>]*
  ... Writes explicit values to the core at the current assembly location.
  This 'opcode' is required such that disassembled code which contains undefined code without valid opcode translations can still be reassembled.
  The <operand> here may also be a quoted string to embed 8-bit values into the content. No provision is made for 16-bit values in strings. The disassembler will not produce the strings form of DAT yet.

• RES <value>
  ... Reserves space for data to be written, of length <value> words.
  This special opcode will increment the compilation address, but write no data to the intervening locations. When written out as an assembly source, this may result in a .ORIGIN directive being issued. In Address dumps this will generate a discontinuity. In a binary dump, the space will be filled with zeroes.

• CONST <value>
  ... Together with a label, defines a constant symbol value which can be used in code later.

• ADDRESS <value>
  ... Together with a label, defines an address symbol value which can be used in code later.

• RN <register>
  ... Together with a label, defines an register binding which can be used in place of the usual register name. This can make it easier to read the code by having more meaningful names.

Expressions

Anywhere that a value is required, an expression may be used. Expressions can include brackets, but do not obey precedence other than the use of brackets themselves. (Poor code on my part - maybe I should have thought more carefully about it). Expressions may use symbols as parts of addition. For example, the following code fragment is valid:

    SET pc, label+1
:label
    DAT 0
    SET pc, pc        ; continues from here, skipping the 0

Expressions can use the following arithmetic operators:

Address file format

Address file format is a simple memory dump format which can be used for input or output. It is based on the format used in the DCPU-16 specification. The start of any line can be specified as:

<address> :

This indicates the address that assigned values start at. Where no address is supplied, the values to be stored will continue from the previous address, or 0 if no address is given at the start of the dump.

Following any address, a whitespace separated list of hex values may be given, to be stored in ascending order from the address specified.

When output, values will be written in maximum of 8 word blocks, terminating at an 8-word address multiple.

This format is used as part of the regression test to check that values are assembled correctly.

Hardware profiles

Hardware profiles define the hardware devices which are attached to the CPU.

The hardware profile source file is a text file with lines in the following format:

<address> <device> [ ( <argument> [ , <argument> ]* ) ]

• assign a device <device> (module DExecHW::<device>.pm) at address <address>. The arguments supplied may be either constant values or quoted strings, and will be passed to the module's constructor.

# <comment>

• a comment line, which is ignored.

Hardware devices

Hardware devices are implemented in the DExecHW directory as modules. Device modules are never aware of the addresses they have been mapped to by the hardware profile. They only deal in offsets from their base. This allows them to be relocated by the hardware profile as necessary. Each module provides an object interface with the following methods:

window()

• returns the number of words the device requires in memory

read($offset, $dexec)

• read a word from the device at a specified offset from the base.

write($offset, $dexec, $value)

• write a word to the device at the specified offset from the base.

symbol($offset)

• return the name of the offset, suitable to be used as a symbol suffix.

start($dexec)

• called at the start of execution on a CPU, if present.

stop($dexec)

• called at the end of execution on a CPU, if present.

poll($dexec)

• called at the end of every instruction execution, if present.

When loaded, each device is assigned a symbol which may be used by code later. Symbols take the form:

<device name>_<symbol name>

Each offset within the window is iterated over for the device and symbols generated for the offsets.

Emulator

The emulator is invoked when the -run switch is added to the command line. Execution (at present) begins at address 0. All registers are initialised to 0. Execution terminates when the PC remains constant from one instruction to the next (eg a :here SET PC, here).

At the end of execution the number of cycles, instructions and timings are printed.

Register dump

The register dump includes the CPU number; which in the present implementation will always be 0. For example:

#0  A: b520  B: 0000  C: 0000  X: 0000  Y: 0000  Z: 0000  I: 6ff1  J: b520
#0  O: 0000 SP: ffff PC: 0015 [01e1]
#0 STK> [0011]

Shows the registers for CPU 0. Immediately after the PC is printed, the value of the next instruction is shown. This is followed by NX if the instruction will not be executed.

The final lines show the values on the stack, from lowest location upwards, up to the top of memory (0xffff).

Structure

The assembler (and disassembler) are an IO handler provided in the DASMIO directory. These modules are able to manipulate the core in the DASM objects in order to provide details. There's a lot of collusion in the code and I've not tidied it up as much as I'd like. Ideally the DASM module should provide methods to access its innards, rather than the IO modules poking them directly.

Additional file formats can be created by adding new modules in the same directory. In order to read or write different file formats the module should store values (or read from) the core and update the symbol table and relocations hashrefs to contain relevant data. I've only supported very simple additive relocation, which should be sufficient for partial linking of relocatable code segments (however this hasn't been started yet - it might need more thought).

Although the intention is that symbols be able to be relocated (for address symbols) or fixed (for constant symbols), the relocation has not been implemented, and the definition of constant symbols is not directly usable.

The nesting of include files are tracked so that errors are reported by the files that caused them and those that included the files.

The internal implementation of the emulator allows for multiple CPUs to be executed, however this is not yet exposed completely to the command line interface.

Example code

Some example code is provided in the 'test-*' directories, which provide a regression test for the assembler, disassebler, dumper, binary file loader and emulator. Negative tests are (generally) held in directories ending in -fail. The negative tests are used to ensure that errors are detected correctly. In order to test the code, use:

   make tests

The individual tests can be executed with:

   make tests-<type>

See the Makefile for more details on these tests.

The test harness for the regression suite can be found in run-tests.pl. This script will load the Tests.pm file from directories known to it. Tests can be run with coverage calculations present by specifying a -coverage option to the tool. The coverage is generated into the coverage directory.

'Comparison' tests

In particular, some of the 'comparison' tests from:

http://0x10cwiki.com/wiki/Comparison_of_Developer_Tools

have been included in the test-comparison directory. These are not covered by the license of this assembler. The test module test-comparison/Tests.pm provides the harness to invoke these. It includes, as part of its file prologue comment, a description of the initial failures which were found due to those tests, and the changes made as a result.

In particular, I disagree strongly that the division by zero is a fault, and have consequently removed the test. See the talk page for details:

http://0x10cwiki.com/wiki/Talk:Comparison_of_Developer_Tools

Future developments

A future version of the assembler may provide the following features:

• Multiple device mappings (currently the symbol assignment prevents these).
• Register aliasing (eg replacing Z with SB or similar).
• Implicit workspace references (eg memlimit meaning [24 + Z], as might be used to implement a static base or workspace register).
• Macro support (eg making MOV a,b mean SET a,b, or RTS mean SET PC, POP)
• Conditional assembly directives (eg .IF, .ELSE, etc) (although we could just use the C pre-processor or m4).
• Constant definitions properly implemented, with ephemeral symbols for hardware.
• Partially link content support (including libraries).
• Other IO formats, depending on what other assemblers and tools use.

I have only looked sparingly at other implementations, intentionally so that I can concentrate on what I feel might be interesting or useful.

License

The DASM assembler kit is released under the simplified BSD license because it provides the greatest degree of freedom in using the source, unlike more restrictive licenses such as the GPL. Hopefully others will feel the same way and keep the code free.

Copyright (c) 2012, Justin Fletcher
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met: 

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer. 
2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.