CASM

From 77e8708934c5c792b1435fa11dfe3c0a6f636a8c Mon Sep 17 00:00:00 2001 From: Ian C Date: Mon, 7 Mar 2016 15:00:21 +0000 Subject: Updated README and copied latest version in. --- doc/manual.html | 1577 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1577 insertions(+) create mode 100644 doc/manual.html (limited to 'doc/manual.html') diff --git a/doc/manual.html b/doc/manual.html new file mode 100644 index 0000000..4aa250c --- /dev/null +++ b/doc/manual.html @@ -0,0 +1,1577 @@ + + + + + +CASM + + + + + +

A simple, portable multi-pass assembler

This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version.

This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details.

You should have received a copy of the GNU General Public License +along with this program. If not, see http://www.gnu.org/licenses/gpl-3.0.html

Usage

casm file

Assembles file, and places the output in output by default.

Source Format Example

The source files follow this basic format:

; 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

All 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 further sections.

+processor CPU +

+ Sets the processor type to CPU. If omitted then Z80 is the default. + Note that this can appear multiple times in the same file. Currently + supported CPU values are Z80 and 6502. +

+option setting, value +

+ Set options. Options are defined later on, and each CPU can also have its + own options. For options that support booleans (on/off/true/false), + the setting can be prefixed with a plus or minus character to switch it + on or off respectively. +

+equ value +

+ Sets the top level label to value. Note this requires a label on the + same line. +

+org value +

+ Sets the program counter (PC) to value. The PC defaults to zero. +

+ds value[, fill] +

+ Skips on the program counter value bytes. If the optional fill is + provided then the bytes are filled with fill, otherwise they are filled + with zero. +

+db value[, value] +

+ Writes bytes to the current PC. The values can be constants, expressions, + labels or strings. Built-in aliases are byte and text. +

+dw <value>[, <value>] +

+ Writes words (16-bit values) to the current PC. The values can be + constants, expressions or labels. Note that word is a built-in alias for + this directive. +

+align value[, fill] +

+ Align the PC so that (PC modulus value) is zero. Will error if value + is less than 2 or greater that 32768. No values are written to the skipped + bytes unless the optional fill is supplied. +

+include filename +

+ Includes the source file filename as if it was text entered at the + current location. +

+incbin filename +

+ Includes the binary data in filename at the current PC, as if it was a + sequence of db directives with all the bytes from the file. +

+alias command, replacement +

+ Creates an alias so that whenever the command command is found in the + source it is replaced with replacement. The idea of this is to make it + easier to import sources that use unknown directives, e.g. +

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.

+nullcmd +

+ Simply does nothing. It’s only real use is as an alias if you wished to + strip a directive from a foreign source file. +

+end +

+ Terminates the input processing. Anything past the directive will be + ignored. +

Expressions

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

The following formats for constant numbers are supported (note these are +illustrated as a regular expression):

+"x" or x +: +
+ A single quoted character will be converted into the appropriate character + code. +
+
+[1-9][0-9]* +: +
+ A decimal number, e.g. 42. +
+
+0[0-7]* +: +
+ An octal number, e.g. 052. +
+
+0x[0-9a-fA-f]+ +: +
+ A hex number, e.g. 0x2a. +
+
+[0-9a-fA-f]+h +: +
+ A hex number, e.g. 2ah. +
+
+$[0-9a-fA-f]+ +: +
+ A hex number, e.g. $2a. +
+
+[01]+b +: +
+ A binary number, e.g. 00101010b +
+
+[a-zA-Z_0-9]+ +: +
+ A label, e.g. main_loop. +
+

The following operators are understood. The order here is the order of +precedence.

+{ } +: +
+ Brackets used to alter the order of precedence. Note normal parenthesis + aren’t used as the assembly language may make use of them. +
+
+~ + - +: +
+ Bitwise NOT/unary plus/unary minus. +
+
+<< >> +: +
+ Shift left/shift right. +
+
+/ * % +: +
+ Division/multiplication/modulus. +
+
++ - +: +
+ Addition/subtraction. +
+

All the following have the same precedence, and so will be done left to right.

+== +: +
+ Equality. Returns 1 if the arguments are equal, otherwise zero. +
+
+!= +: +
+ Inequality. Returns 1 if the arguments are unequal, otherwise zero. +
+
+< <= > >= +: +
+ Less than/less than or equal/greater than/greater than or equal. Returns 1 + if the arguments are equal, otherwise zero. +
+

All the following have the same precedence, and so will be done left to right.

+&& & +: +
+ Boolean/bitwise AND. For boolean operation arguments, zero is FALSE, + otherwise TRUE. +
+
+|| | +: +
+ Boolean/bitwise OR. +
+
+^ +: +
+ Bitwise XOR. +
+

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.

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.

+ascii +: +
+ 7-bit ASCII. This is the default. +
+
+spectrum +: +
+ The character codes as used on the Sinclair ZX Spectrum. +
+
+zx81 +: +
+ The character codes as used on the Sinclair ZX-81. Lower case + letters are encoded as normal upper case letters and upper case + letter will be encoded as inverse upper case letters. +
+
+cbm +: +
+ PETSCII as used on the Commodore Business Machine’s range from the + PET to the C128. See https://en.wikipedia.org/wiki/PETSCII for + more details. +
+

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.

macro1: macro
+
+        ld a,\1
+        ld b,\2
+        call \3
+
+        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

By default the assembled code is written to a file called output as raw +binary covering the block of memory that the assembly touched.

This can be controlled with the following options.

+option output-file, file +

+ Send the output to file. +

+option output-type, format +

+ Controls the output format with the following settings +

+raw +: +
+ The default raw binary. +
+
+spectrum +: +
+ Generates a Spectrum TAP file for an emulator. The TAP file will + be given the same name as the output filename, and its load address + will be set to the start of the created memory. Remember that TAP + files can be concatenated, so the output could be appended to + another TAP file containing a BASIC loader for example. +
+

Listing

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

+option list, <on|off> +

+ Enables/disables listing. The listing will go to stdout. +

+option list-file, file +

+ Sends the listing to file. Note this should appear before enabling the + listing. +

+option list-pc, <on|off> +

+ Control the output of the current PC in the as a comment preceding the + line (so that a listing could be reassembled with no editing). Defaults + to off. +

+option list-hex, <on|off> +

+ Control the output of the bytes generated by the source line in hex. + Defaults to off. If on then the hex is output in a comment preceding + the line (possibly with the PC above), so that a listing is still valid to + be assembled. +

+option list-labels, <on|off|all> +

+ Controls the listing of labels, either off (the default), on to dump + label values at the end of the listing and all to dump all labels, + including internally generated private labels for macros. +

+option list-macros, <off|exec|dump|all> +

+ Controls the listing of macro invocations, either +

+off +: +
+ The default; don’t list anything. +
+
+exec +: +
+ List invocations of macros. +
+
+dump +: +
+ Produce a list of macro definitions at the end of the listing. +
+
+all +: +
+ Combine "exec" and "dump" +
+

+option list-rm-blanks, <on|off> +

+ Defaults to on. This option causes multiple blank lines to be collapsed + down to a single line. +

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

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 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

The Z80 assembler has no options.

6502 CPU

Opcodes

The 6502 assembler uses the standard Motorola opcodes.

Options

The 6502 assembler has the following options.

+option zero-page, <on|off|auto> +

+ Use Zero-Page addressing for absolute and absolute,X address modes. + If mode is set to auto then tries to calculate the mode based on the + value in the last pass. + Defaults to off. e.g. +

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

+ + + -- cgit v1.2.3