diff options
Diffstat (limited to 'doc/manual.asciidoc')
| -rw-r--r-- | doc/manual.asciidoc | 546 |
1 files changed, 546 insertions, 0 deletions
diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc new file mode 100644 index 0000000..888a9f0 --- /dev/null +++ b/doc/manual.asciidoc @@ -0,0 +1,546 @@ + +CASM +==== + +A simple, portable multi-pass assembler + +Copyright (C) 2003-2015 Ian Cowburn <ianc@noddybox.co.uk> + +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 + + + +// vim: ai sw=4 ts=8 expandtab spell |