Index

CASM - General usage

Z80 - Z80 processor support.

6502 - 6502 processor support.

Gameboy Z80 - The Gameboy Z80 derivative processor.

CASM

Usage

Assembles file, and places the resulting code in a file called output by default.

Note that switches aren't used by casm. Instead options are controlled by commands in the source file.

If you type the command without an argument, usage, version and license info is displayed.

Memory Layout

There is 64K of RAM that the assembler will generate output into. Extra 64K banks of RAM can be added by using the bank or org directives. Banks are numbered from zero upwards.

Source Code Layout

    ; Comments
    ;
    label1: equ     0xffff

            org     $4000;
            
            db      "Hello, World\n",0

    main    jp      local_label     ; Comments

    .local_label
            inc     a

    another:
            inc     b
            jp      local_label     ; Actually jumps to the following
                                    ; local_label.

    .local_label
            ret

The source files follow the following rules:

• Any text past a semicolon (;) is discarded as a comment (except when part of a string constant).
• Labels must start in column zero (the left hand most column).
• If the label ends with a colon (:) then the colon is removed.
• If the label doesn't start with a period (.) then it is assumed a global label.
• If the label starts with a period (.) then it is assumed to be a local label. Local labels are associated with the preceding global label. If a global label and related local label have the same name, the local label will be used on expansion.
• Any label can be followed by an equ directive, in which case the label is set to that value rather than the current program counter.
• Labels are case-insensitive.
• Directives and opcodes must appear further along the line (anywhere else other than the left hand column where labels live basically).
• Strings can either be quoted with single or double quotes; this allows you to put the other quote type inside the string.

Recognised directives

The following directives are also recognised with an optional period (.) in front of them, and are case insensitive. Directives can also be used to control the output of a program listing, and the output of the assembly itself. These are documented in subsequent sections.

    alias setaddr,org
    alias ldreg,ld

    cpu         z80

    setaddr     $8000   ; These two are
    org         $8000   ; equivalent.

    ld          a,(hl)  ; These two are
    ldreg       a,(hl)  ; equivalent.

Built-in Aliases

Expressions

In any of the directives above, where a value is defined, an expression can be entered.

Assembly instructions will also permit these expressions to be used where applicable. As many opcodes use parenthesis to indicate addressing modes, remember that {} brackets can be used to alter expression precedence.

    ld  a,{8+2}*2               ; On the Z80 loads A with the value 20
    ld  a,({8+2}*2)             ; On the Z80 loads A with the value stored at
                                ; address 20

Note that the expression is evaluated using a standard C int, and then cast to the appropriate size.

The following formats for constant numbers are supported:

Character Sets

The assembler has built-in support for a few different character sets. These can be set by using the options `charset` or `codepage`, i.e.

    option codepage, format
    option charset, format

The following values can be used for format.

e.g.

    option  +list
    option  +list-hex

    option  charset,ascii
    db      "Hello",'A'
    ; $48 $65 $6C $6C $6F $41

    option  charset,zx81
    db      "Hello",'A'
    ; $AD $2A $31 $31 $34 $A6

    option  codepage,cbm
    db      "Hello",'A'
    ; $48 $45 $4C $4C $4F $41

    option  codepage,spectrum
    db      "Hello",'A'
    ; $48 $65 $6C $6C $6F $41

Macros

Macros can be defined in one of two ways; either parameterless or with named parameters. Macro names are case-insensitive. In the parameterless mode the special identifier '*' can be used to expand all arguments, which will be separated with commas.

When expanded the macro will have an internally generated top-level label assigned to it, so local variables will work inside the macro.

e.g.

macro1: macro

        ld a,\1
        ld b,\2
        ld hl,data
        call \3
        jr dataend
.data
        defb \*
.dataend

        endm

macro2: macro char,junk,interface

        ld a,@char
        ld b,@junk
        call @interface

        endm

Note that trying to expand and unknown/missing argument will be replaced with an empty string. Also the two argument reference styles can be mixed, though obviously the @ form only makes sense in a parameterised macro, e.g.

mac:    macro char,junk,interface

        ld a,@char
        ld b,\2
        call @interface

        endm

The at symbol (@) used for parameter expansion in named argument macros can be replaced by using the following option, e.g.

        option  macro-arg-char,&

Note that this is enforced when the macro is used not when it is defined. Also the character must not be quoted, as that will be parsed as a string holding the character code of the character.

Output Format

RAW Output Format

Spectrum TAP Output Format

Generates a Spectrum TAP file for an emulator. A TAP file is a simple binary file holding the bytes that the real Spectrum would have written to a tape.

The TAP file will be given the same name as the output filename, and the internal code block will also be given the same name, unless memory banks have been used, in which case each code file in the TAP file will use the output-bank setting to generate the filename for each block.

Remember that TAP files can be concatenated, so the output could be appended to another TAP file containing a BASIC loader, for example.

ZX81 .P Output Format

Generates a P-file for an emulator. A ZX81 .P file is simply a dump of memory from the system variables onwards.

This format does not support memory blocks (the .P file is not a container format) and so will only output anything in the first bank used, and using the output-file for the filename.

The output file will be created as a BASIC program, containing a REM statement holding the machine code, and a command to execute the code. As such the output will fail if the code in Bank 0 does not start at address 16514. Your code must also support being executed from this address.

Another important thing to note is about the display file. In the ZX81 memory map the DFILE can move around depending on the size of the program. The output driver will create a display file for you. The easiest way to reference this is to read the DFILE system variable when your program starts.

Alternatively you can just as easily set up your own display file once your program starts if you have special requirements, e.g. a display file for pseudo hi-res.

ZX81 .P Output Format options

The ZX81 output driver supports the following settings that can be set via an option command.

C64 T64 Tape Output Format

Generates a T64 tape file for an emulator.

The tape file will be given the same name as the output filename, and the internal code block will also be given the same name, unless memory banks have been used, in which case then each entry in the tape file will use the output-bank setting to generate the filename for each entry.

The first (or only) bank will have a small BASIC program inserted as part of the generated file. For this reason the first bank should start near the BASIC area (0x820 should be a safe place to start) unless you have a great desire for a tape full of zero bytes. This BASIC will simply hold a SYS command to start the machine code, e.g.

10 SYS 2080

Any remaining blocks will be stored as-is without any basic loader.

Nintendo Gameboy ROM File Output Format

Generates a ROM file for a Gameboy emulator or hardware. Note that large ROM sizes have not been extensively checked and verified.

If a single bank was used during the assembly then a simple 32K ROM is assumed, and an error will be shown if the addresses used fall outside the range 0x150 to 0x7fff.

Similarly if multiple banks are used then it is assumed that the first bank is only used in the range 0x150 to 0x3fff, and subsequent banks in the range 0x4000 to 0x7fff. This is to fit in with the method the Gameboy uses to page memory banks into the upper 16K portion of the normal 32K ROM address space.

By default the output driver will try and fill in the ROM size and type in the header properly, but these can be overridden using settings.

Gameboy ROM Output Format options

The Gameboy output driver supports the following settings that can be set via an option command.

Listing

By default no output listing is generated. This can be controlled by the following options.

Z80 CPU

Opcodes

The Z80 assembler uses the standard Zilog opcodes, and supports undocumented instructions.

For instructions were the Accumulator can be assumed it can be omitted, and EOR can be used the same as XOR:

        xor     a,a         ; These are equivalent
        xor     a
        eor     a,a

        and     a,b         ; These are equivalent
        and     b

For exchange opcodes with parameters the parameters can be reversed from their official form:

        ; The official forms
        ;
        ex      de,hl
        ex      af,af'
        ex      (sp),hl
        ex      (sp),ix
        ex      (sp),iy

        ; Also supported
        ;
        ex      hl,de
        ex      af',af
        ex      hl,(sp)
        ex      ix,(sp)
        ex      iy,(sp)

Where the high/low register parts of the IX and IY registers are to be used, simply use ixl, iyl, ixh and iyh. Note that the assembler will accept illegal pairings involving H and L, but these will be warned about:

        ld  ixh,$e5
        ld  iyl,iyl

        ld  ixh,l           ; This will be turned into "ld ixh,ixl" and a
                            ; warning will be issued.

        ld  iyh,ixl         ; This will generate an error as the index registers
                            ; have been mixed.

For the hidden bit manipulations that also can copied to a register, these can be represented by adding the destination register as an extra parameter, e.g.

        srl (iy-1),d
        set 3,(iy-1),a
        res 4,(iy-1),b

For the hidden IN instruction using the flag register the following are all equivalent:

        in  (c)
        in  f,(c)

For the hidden OUT instruction using the flag register, $00 or $ff depending on where you're reading, the following are all equivalent, where value can be any value at all:

        out (c)
        out (c),f
        out (c),value

Options

6502 CPU

Opcodes

Options

        cpu     6502
        org     $8000

        lda     $0000,x     ; Produces $bd $00 $00
        option  +zero-page
        lda     $0000,x     ; Produces $b5 $00
        lda     $1234,x     ; Produces an error

        option  zero-page,auto
        lda     $00,x       ; Produces $b5 $00
        lda     $8000,x     ; Produces $bd $00 $80

Gameboy Z80 derivative CPU

Opcodes

The Gameboy assembler uses the standard Z80 opcodes where applicable. Note that the Gameboy processor has a reduced number of opcodes, flags and no index registers, though it has some additional instructions and addressing modes.

For instructions were the Accumulator can be assumed it can be omitted, and EOR can be used the same as XOR:

        xor     a,a         ; These are equivalent
        xor     a
        eor     a,a

        and     a,b         ; These are equivalent
        and     b

The Gameboy CPU has a special addressing mode used for one opcode, where the referenced address is stored as a single byte, and used as an offset into the top page (0xff00). This can be either triggered by using the special opcode, or will automatically used whenever an address is accessed in the range 0xff00 to 0xffff:

        ; These all will use the special addressing mode opcode, accessing
        ; memory location $ff34
        ;
label   equ     $ff34

        ldh     a,($34)
        ldh     a,($ff34)
        ld      a,($ff34)
        ld      a,(label)

        ld      (label),a
        ld      ($ff34),a
        ldh     ($34),a
        ldh     ($ff34),a

The Gameboy CPU also supports incrementing or decrementing the HL register when it is used as an address:

        ; All these decrement HL after the value has been used.
        ;
        ld      a,(hl-)
        ld      a,(hld)
        ldd     a,(hl)
        ld      (hl-),a
        ld      (hld),a
        ldd     (hl),a

        ; All these increment HL after the value has been used.
        ;
        ld      a,(hl+)
        ld      a,(hli)
        ldi     a,(hl)
        ld      (hl+),a
        ld      (hli),a
        ldi     (hl),a

In addition the Gameboy CPU supports these extra instructions over the Z80:

        ; Actually loads using the address $ff00 + C
        ;
        ld      a,(c)
        ld      (c),a

        ; Put the Gameboy into a low-power mode till a control is pressed.
        ; Note it is accepted practice to put a NOP afterwards.  This may be
        ; due to the stop replacing DJNZ, which may still be wired to expect
        ; an argument.  That is just a wild guess though.
        ;
        stop
        nop

        ; Swaps the low/high nibbles of the register
        ;
        swap    a
        swap    b
        swap    c
        swap    d
        swap    e
        swap    h
        swap    l
        swap    (hl)

Options