diff options
| author | Ian C <ianc@noddybox.co.uk> | 2016-03-07 15:00:21 +0000 |
|---|---|---|
| committer | Ian C <ianc@noddybox.co.uk> | 2016-03-07 15:00:21 +0000 |
| commit | 77e8708934c5c792b1435fa11dfe3c0a6f636a8c (patch) | |
| tree | 8c68ecddaf2c2c0730ba310b8d1b9e0f1bd16132 /doc | |
| parent | 6e9c9c9205d6eec1ff1cfb3fa407c6714854145a (diff) | |
Updated README and copied latest version in.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 32 | ||||
| -rw-r--r-- | doc/README | 22 | ||||
| -rw-r--r-- | doc/manual.asciidoc | 546 | ||||
| -rw-r--r-- | doc/manual.html | 1577 | ||||
| -rw-r--r-- | doc/manual.pdf | bin | 0 -> 145493 bytes |
5 files changed, 2177 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..0791d55 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,32 @@ +# casm - Simple, portable assembler +# +# Copyright (C) 2003-2015 Ian Cowburn (ianc@noddybox.demon.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/>. +# +# ------------------------------------------------------------------------- +# +# Makefile for documentation +# + +all: manual.html manual.pdf + +manual.html: manual.asciidoc + asciidoc manual.asciidoc + +manual.pdf: manual.asciidoc + a2x -fpdf -dbook manual.asciidoc + +clean: + rm -f manual.html manual.pdf diff --git a/doc/README b/doc/README new file mode 100644 index 0000000..66dbb8c --- /dev/null +++ b/doc/README @@ -0,0 +1,22 @@ + casm - A portable cross assembler + ================================= + + Copyright 2003-2015 Ian Cowburn + + + 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/>. + + See manual.pdf or manual.html for instructions on use. + + See LICENSE for full license text. 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 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 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
+<meta name="generator" content="AsciiDoc 8.6.6" />
+<title>CASM</title>
+<style type="text/css">
+/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
+
+/* Default font. */
+body {
+ font-family: Georgia,serif;
+}
+
+/* Title font. */
+h1, h2, h3, h4, h5, h6,
+div.title, caption.title,
+thead, p.table.header,
+#toctitle,
+#author, #revnumber, #revdate, #revremark,
+#footer {
+ font-family: Arial,Helvetica,sans-serif;
+}
+
+body {
+ margin: 1em 5% 1em 5%;
+}
+
+a {
+ color: blue;
+ text-decoration: underline;
+}
+a:visited {
+ color: fuchsia;
+}
+
+em {
+ font-style: italic;
+ color: navy;
+}
+
+strong {
+ font-weight: bold;
+ color: #083194;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: #527bbd;
+ margin-top: 1.2em;
+ margin-bottom: 0.5em;
+ line-height: 1.3;
+}
+
+h1, h2, h3 {
+ border-bottom: 2px solid silver;
+}
+h2 {
+ padding-top: 0.5em;
+}
+h3 {
+ float: left;
+}
+h3 + * {
+ clear: left;
+}
+h5 {
+ font-size: 1.0em;
+}
+
+div.sectionbody {
+ margin-left: 0;
+}
+
+hr {
+ border: 1px solid silver;
+}
+
+p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+ul, ol, li > p {
+ margin-top: 0;
+}
+ul > li { color: #aaa; }
+ul > li > * { color: black; }
+
+pre {
+ padding: 0;
+ margin: 0;
+}
+
+#author {
+ color: #527bbd;
+ font-weight: bold;
+ font-size: 1.1em;
+}
+#email {
+}
+#revnumber, #revdate, #revremark {
+}
+
+#footer {
+ font-size: small;
+ border-top: 2px solid silver;
+ padding-top: 0.5em;
+ margin-top: 4.0em;
+}
+#footer-text {
+ float: left;
+ padding-bottom: 0.5em;
+}
+#footer-badges {
+ float: right;
+ padding-bottom: 0.5em;
+}
+
+#preamble {
+ margin-top: 1.5em;
+ margin-bottom: 1.5em;
+}
+div.imageblock, div.exampleblock, div.verseblock,
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
+div.admonitionblock {
+ margin-top: 1.0em;
+ margin-bottom: 1.5em;
+}
+div.admonitionblock {
+ margin-top: 2.0em;
+ margin-bottom: 2.0em;
+ margin-right: 10%;
+ color: #606060;
+}
+
+div.content { /* Block element content. */
+ padding: 0;
+}
+
+/* Block element titles. */
+div.title, caption.title {
+ color: #527bbd;
+ font-weight: bold;
+ text-align: left;
+ margin-top: 1.0em;
+ margin-bottom: 0.5em;
+}
+div.title + * {
+ margin-top: 0;
+}
+
+td div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content + div.title {
+ margin-top: 0.0em;
+}
+
+div.sidebarblock > div.content {
+ background: #ffffee;
+ border: 1px solid #dddddd;
+ border-left: 4px solid #f0f0f0;
+ padding: 0.5em;
+}
+
+div.listingblock > div.content {
+ border: 1px solid #dddddd;
+ border-left: 5px solid #f0f0f0;
+ background: #f8f8f8;
+ padding: 0.5em;
+}
+
+div.quoteblock, div.verseblock {
+ padding-left: 1.0em;
+ margin-left: 1.0em;
+ margin-right: 10%;
+ border-left: 5px solid #f0f0f0;
+ color: #888;
+}
+
+div.quoteblock > div.attribution {
+ padding-top: 0.5em;
+ text-align: right;
+}
+
+div.verseblock > pre.content {
+ font-family: inherit;
+ font-size: inherit;
+}
+div.verseblock > div.attribution {
+ padding-top: 0.75em;
+ text-align: left;
+}
+/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
+div.verseblock + div.attribution {
+ text-align: left;
+}
+
+div.admonitionblock .icon {
+ vertical-align: top;
+ font-size: 1.1em;
+ font-weight: bold;
+ text-decoration: underline;
+ color: #527bbd;
+ padding-right: 0.5em;
+}
+div.admonitionblock td.content {
+ padding-left: 0.5em;
+ border-left: 3px solid #dddddd;
+}
+
+div.exampleblock > div.content {
+ border-left: 3px solid #dddddd;
+ padding-left: 0.5em;
+}
+
+div.imageblock div.content { padding-left: 0; }
+span.image img { border-style: none; }
+a.image:visited { color: white; }
+
+dl {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+dt {
+ margin-top: 0.5em;
+ margin-bottom: 0;
+ font-style: normal;
+ color: navy;
+}
+dd > *:first-child {
+ margin-top: 0.1em;
+}
+
+ul, ol {
+ list-style-position: outside;
+}
+ol.arabic {
+ list-style-type: decimal;
+}
+ol.loweralpha {
+ list-style-type: lower-alpha;
+}
+ol.upperalpha {
+ list-style-type: upper-alpha;
+}
+ol.lowerroman {
+ list-style-type: lower-roman;
+}
+ol.upperroman {
+ list-style-type: upper-roman;
+}
+
+div.compact ul, div.compact ol,
+div.compact p, div.compact p,
+div.compact div, div.compact div {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+}
+
+tfoot {
+ font-weight: bold;
+}
+td > div.verse {
+ white-space: pre;
+}
+
+div.hdlist {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+div.hdlist tr {
+ padding-bottom: 15px;
+}
+dt.hdlist1.strong, td.hdlist1.strong {
+ font-weight: bold;
+}
+td.hdlist1 {
+ vertical-align: top;
+ font-style: normal;
+ padding-right: 0.8em;
+ color: navy;
+}
+td.hdlist2 {
+ vertical-align: top;
+}
+div.hdlist.compact tr {
+ margin: 0;
+ padding-bottom: 0;
+}
+
+.comment {
+ background: yellow;
+}
+
+.footnote, .footnoteref {
+ font-size: 0.8em;
+}
+
+span.footnote, span.footnoteref {
+ vertical-align: super;
+}
+
+#footnotes {
+ margin: 20px 0 20px 0;
+ padding: 7px 0 0 0;
+}
+
+#footnotes div.footnote {
+ margin: 0 0 5px 0;
+}
+
+#footnotes hr {
+ border: none;
+ border-top: 1px solid silver;
+ height: 1px;
+ text-align: left;
+ margin-left: 0;
+ width: 20%;
+ min-width: 100px;
+}
+
+div.colist td {
+ padding-right: 0.5em;
+ padding-bottom: 0.3em;
+ vertical-align: top;
+}
+div.colist td img {
+ margin-top: 0.3em;
+}
+
+@media print {
+ #footer-badges { display: none; }
+}
+
+#toc {
+ margin-bottom: 2.5em;
+}
+
+#toctitle {
+ color: #527bbd;
+ font-size: 1.1em;
+ font-weight: bold;
+ margin-top: 1.0em;
+ margin-bottom: 0.1em;
+}
+
+div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+div.toclevel2 {
+ margin-left: 2em;
+ font-size: 0.9em;
+}
+div.toclevel3 {
+ margin-left: 4em;
+ font-size: 0.9em;
+}
+div.toclevel4 {
+ margin-left: 6em;
+ font-size: 0.9em;
+}
+
+span.aqua { color: aqua; }
+span.black { color: black; }
+span.blue { color: blue; }
+span.fuchsia { color: fuchsia; }
+span.gray { color: gray; }
+span.green { color: green; }
+span.lime { color: lime; }
+span.maroon { color: maroon; }
+span.navy { color: navy; }
+span.olive { color: olive; }
+span.purple { color: purple; }
+span.red { color: red; }
+span.silver { color: silver; }
+span.teal { color: teal; }
+span.white { color: white; }
+span.yellow { color: yellow; }
+
+span.aqua-background { background: aqua; }
+span.black-background { background: black; }
+span.blue-background { background: blue; }
+span.fuchsia-background { background: fuchsia; }
+span.gray-background { background: gray; }
+span.green-background { background: green; }
+span.lime-background { background: lime; }
+span.maroon-background { background: maroon; }
+span.navy-background { background: navy; }
+span.olive-background { background: olive; }
+span.purple-background { background: purple; }
+span.red-background { background: red; }
+span.silver-background { background: silver; }
+span.teal-background { background: teal; }
+span.white-background { background: white; }
+span.yellow-background { background: yellow; }
+
+span.big { font-size: 2em; }
+span.small { font-size: 0.6em; }
+
+span.underline { text-decoration: underline; }
+span.overline { text-decoration: overline; }
+span.line-through { text-decoration: line-through; }
+
+
+/*
+ * xhtml11 specific
+ *
+ * */
+
+tt {
+ font-family: monospace;
+ font-size: inherit;
+ color: navy;
+}
+
+div.tableblock {
+ margin-top: 1.0em;
+ margin-bottom: 1.5em;
+}
+div.tableblock > table {
+ border: 3px solid #527bbd;
+}
+thead, p.table.header {
+ font-weight: bold;
+ color: #527bbd;
+}
+p.table {
+ margin-top: 0;
+}
+/* Because the table frame attribute is overriden by CSS in most browsers. */
+div.tableblock > table[frame="void"] {
+ border-style: none;
+}
+div.tableblock > table[frame="hsides"] {
+ border-left-style: none;
+ border-right-style: none;
+}
+div.tableblock > table[frame="vsides"] {
+ border-top-style: none;
+ border-bottom-style: none;
+}
+
+
+/*
+ * html5 specific
+ *
+ * */
+
+.monospaced {
+ font-family: monospace;
+ font-size: inherit;
+ color: navy;
+}
+
+table.tableblock {
+ margin-top: 1.0em;
+ margin-bottom: 1.5em;
+}
+thead, p.tableblock.header {
+ font-weight: bold;
+ color: #527bbd;
+}
+p.tableblock {
+ margin-top: 0;
+}
+table.tableblock {
+ border-width: 3px;
+ border-spacing: 0px;
+ border-style: solid;
+ border-color: #527bbd;
+ border-collapse: collapse;
+}
+th.tableblock, td.tableblock {
+ border-width: 1px;
+ padding: 4px;
+ border-style: solid;
+ border-color: #527bbd;
+}
+
+table.tableblock.frame-topbot {
+ border-left-style: hidden;
+ border-right-style: hidden;
+}
+table.tableblock.frame-sides {
+ border-top-style: hidden;
+ border-bottom-style: hidden;
+}
+table.tableblock.frame-none {
+ border-style: hidden;
+}
+
+th.tableblock.halign-left, td.tableblock.halign-left {
+ text-align: left;
+}
+th.tableblock.halign-center, td.tableblock.halign-center {
+ text-align: center;
+}
+th.tableblock.halign-right, td.tableblock.halign-right {
+ text-align: right;
+}
+
+th.tableblock.valign-top, td.tableblock.valign-top {
+ vertical-align: top;
+}
+th.tableblock.valign-middle, td.tableblock.valign-middle {
+ vertical-align: middle;
+}
+th.tableblock.valign-bottom, td.tableblock.valign-bottom {
+ vertical-align: bottom;
+}
+
+
+/*
+ * manpage specific
+ *
+ * */
+
+body.manpage h1 {
+ padding-top: 0.5em;
+ padding-bottom: 0.5em;
+ border-top: 2px solid silver;
+ border-bottom: 2px solid silver;
+}
+body.manpage h2 {
+ border-style: none;
+}
+body.manpage div.sectionbody {
+ margin-left: 3em;
+}
+
+@media print {
+ body.manpage div#toc { display: none; }
+}
+</style>
+<script type="text/javascript">
+/*<+'])');
+ // Function that scans the DOM tree for header elements (the DOM2
+ // nodeIterator API would be a better technique but not supported by all
+ // browsers).
+ var iterate = function (el) {
+ for (var i = el.firstChild; i != null; i = i.nextSibling) {
+ if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
+ var mo = re.exec(i.tagName);
+ if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
+ result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
+ }
+ iterate(i);
+ }
+ }
+ }
+ iterate(el);
+ return result;
+ }
+
+ var toc = document.getElementById("toc");
+ if (!toc) {
+ return;
+ }
+
+ // Delete existing TOC entries in case we're reloading the TOC.
+ var tocEntriesToRemove = [];
+ var i;
+ for (i = 0; i < toc.childNodes.length; i++) {
+ var entry = toc.childNodes[i];
+ if (entry.nodeName == 'div'
+ && entry.getAttribute("class")
+ && entry.getAttribute("class").match(/^toclevel/))
+ tocEntriesToRemove.push(entry);
+ }
+ for (i = 0; i < tocEntriesToRemove.length; i++) {
+ toc.removeChild(tocEntriesToRemove[i]);
+ }
+
+ // Rebuild TOC entries.
+ var entries = tocEntries(document.getElementById("content"), toclevels);
+ for (var i = 0; i < entries.length; ++i) {
+ var entry = entries[i];
+ if (entry.element.id == "")
+ entry.element.id = "_toc_" + i;
+ var a = document.createElement("a");
+ a.href = "#" + entry.element.id;
+ a.appendChild(document.createTextNode(entry.text));
+ var div = document.createElement("div");
+ div.appendChild(a);
+ div.className = "toclevel" + entry.toclevel;
+ toc.appendChild(div);
+ }
+ if (entries.length == 0)
+ toc.parentNode.removeChild(toc);
+},
+
+
+/////////////////////////////////////////////////////////////////////
+// Footnotes generator
+/////////////////////////////////////////////////////////////////////
+
+/* Based on footnote generation code from:
+ * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
+ */
+
+footnotes: function () {
+ // Delete existing footnote entries in case we're reloading the footnodes.
+ var i;
+ var noteholder = document.getElementById("footnotes");
+ if (!noteholder) {
+ return;
+ }
+ var entriesToRemove = [];
+ for (i = 0; i < noteholder.childNodes.length; i++) {
+ var entry = noteholder.childNodes[i];
+ if (entry.nodeName == 'div' && entry.getAttribute("class") == "footnote")
+ entriesToRemove.push(entry);
+ }
+ for (i = 0; i < entriesToRemove.length; i++) {
+ noteholder.removeChild(entriesToRemove[i]);
+ }
+
+ // Rebuild footnote entries.
+ var cont = document.getElementById("content");
+ var spans = cont.getElementsByTagName("span");
+ var refs = {};
+ var n = 0;
+ for (i=0; i<spans.length; i++) {
+ if (spans[i].className == "footnote") {
+ n++;
+ var note = spans[i].getAttribute("data-note");
+ if (!note) {
+ // Use [\s\S] in place of . so multi-line matches work.
+ // Because JavaScript has no s (dotall) regex flag.
+ note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
+ spans[i].innerHTML =
+ "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
+ "' title='View footnote' class='footnote'>" + n + "</a>]";
+ spans[i].setAttribute("data-note", note);
+ }
+ noteholder.innerHTML +=
+ "<div class='footnote' id='_footnote_" + n + "'>" +
+ "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
+ n + "</a>. " + note + "</div>";
+ var id =spans[i].getAttribute("id");
+ if (id != null) refs["#"+id] = n;
+ }
+ }
+ if (n == 0)
+ noteholder.parentNode.removeChild(noteholder);
+ else {
+ // Process footnoterefs.
+ for (i=0; i<spans.length; i++) {
+ if (spans[i].className == "footnoteref") {
+ var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
+ href = href.match(/#.*/)[0]; // Because IE return full URL.
+ n = refs[href];
+ spans[i].innerHTML =
+ "[<a href='#_footnote_" + n +
+ "' title='View footnote' class='footnote'>" + n + "</a>]";
+ }
+ }
+ }
+},
+
+install: function(toclevels) {
+ var timerId;
+
+ function reinstall() {
+ asciidoc.footnotes();
+ if (toclevels) {
+ asciidoc.toc(toclevels);
+ }
+ }
+
+ function reinstallAndRemoveTimer() {
+ clearInterval(timerId);
+ reinstall();
+ }
+
+ timerId = setInterval(reinstall, 500);
+ if (document.addEventListener)
+ document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
+ else
+ window.onload = reinstallAndRemoveTimer;
+}
+
+}
+asciidoc.install();
+/*]]>*/
+</script>
+</head>
+<body class="article">
+<div id="header">
+<h1>CASM</h1>
+</div>
+<div id="content">
+<div id="preamble">
+<div class="sectionbody">
+<div class="paragraph"><p>A simple, portable multi-pass assembler</p></div>
+<div class="paragraph"><p>Copyright © 2003-2015 Ian Cowburn <<a href="mailto:ianc@noddybox.co.uk">ianc@noddybox.co.uk</a>></p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>You should have received a copy of the GNU General Public License
+along with this program. If not, see <a href="http://www.gnu.org/licenses/gpl-3.0.html">http://www.gnu.org/licenses/gpl-3.0.html</a></p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_usage">Usage</h2>
+<div class="sectionbody">
+<div class="listingblock">
+<div class="content">
+<pre><tt>casm file</tt></pre>
+</div></div>
+<div class="paragraph"><p>Assembles file, and places the output in <em>output</em> by default.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_source_format_example">Source Format Example</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The source files follow this basic format:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>; 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</tt></pre>
+</div></div>
+<div class="paragraph"><p>The source files follow the following rules:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Any text past a semicolon (;) is discarded as a comment (except when part
+ of a string constant).
+</p>
+</li>
+<li>
+<p>
+Labels must start in column zero (the left hand most column).
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+If the label ends with a colon (:) then the colon is removed.
+</p>
+</li>
+<li>
+<p>
+If the label doesn’t start with a period (.) then it is assumed a global
+ label.
+</p>
+</li>
+<li>
+<p>
+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.
+</p>
+</li>
+<li>
+<p>
+Any label can be followed by an <em>equ</em> directive, in which case the label
+ is set to that value rather than the current program counter.
+</p>
+</li>
+<li>
+<p>
+Labels are case-insensitive.
+</p>
+</li>
+</ul></div>
+</li>
+<li>
+<p>
+Directives and opcodes must appear further along the line (anywhere else
+ other than the left hand column where labels live basically).
+</p>
+</li>
+<li>
+<p>
+Strings can either be quoted with single or double quotes; this allows you to
+ put the other quote type inside the string.
+</p>
+</li>
+</ul></div>
+<div class="sect2">
+<h3 id="_recognised_directives">Recognised directives</h3>
+<div class="paragraph"><p>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.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+processor <em>CPU</em>
+</dt>
+<dd>
+<p>
+ Sets the processor type to <em>CPU</em>. If omitted then Z80 is the default.
+ Note that this can appear multiple times in the same file. Currently
+ supported <em>CPU</em> values are <tt>Z80</tt> and <tt>6502</tt>.
+</p>
+</dd>
+<dt class="hdlist1">
+option <em>setting</em>, <em>value</em>
+</dt>
+<dd>
+<p>
+ 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 <em>setting</em> can be prefixed with a plus or minus character to switch it
+ on or off respectively.
+</p>
+</dd>
+<dt class="hdlist1">
+equ <em>value</em>
+</dt>
+<dd>
+<p>
+ Sets the top level label to <em>value</em>. Note this requires a label on the
+ same line.
+</p>
+</dd>
+<dt class="hdlist1">
+org <em>value</em>
+</dt>
+<dd>
+<p>
+ Sets the program counter (PC) to <em>value</em>. The PC defaults to zero.
+</p>
+</dd>
+<dt class="hdlist1">
+ds <em>value</em>[, <em>fill</em>]
+</dt>
+<dd>
+<p>
+ Skips on the program counter <em>value</em> bytes. If the optional <em>fill</em> is
+ provided then the bytes are filled with <em>fill</em>, otherwise they are filled
+ with zero.
+</p>
+</dd>
+<dt class="hdlist1">
+db <em>value</em>[, <em>value</em>]
+</dt>
+<dd>
+<p>
+ Writes bytes to the current PC. The values can be constants, expressions,
+ labels or strings. Built-in aliases are <tt>byte</tt> and <tt>text</tt>.
+</p>
+</dd>
+<dt class="hdlist1">
+dw <value>[, <value>]
+</dt>
+<dd>
+<p>
+ Writes words (16-bit values) to the current PC. The values can be
+ constants, expressions or labels. Note that <tt>word</tt> is a built-in alias for
+ this directive.
+</p>
+</dd>
+<dt class="hdlist1">
+align <em>value</em>[, <em>fill</em>]
+</dt>
+<dd>
+<p>
+ Align the PC so that (PC modulus <em>value</em>) is zero. Will error if <em>value</em>
+ is less than 2 or greater that 32768. No values are written to the skipped
+ bytes unless the optional <em>fill</em> is supplied.
+</p>
+</dd>
+<dt class="hdlist1">
+include <em>filename</em>
+</dt>
+<dd>
+<p>
+ Includes the source file <em>filename</em> as if it was text entered at the
+ current location.
+</p>
+</dd>
+<dt class="hdlist1">
+incbin <em>filename</em>
+</dt>
+<dd>
+<p>
+ Includes the binary data in <em>filename</em> at the current PC, as if it was a
+ sequence of <tt>db</tt> directives with all the bytes from the file.
+</p>
+</dd>
+<dt class="hdlist1">
+alias <em>command</em>, <em>replacement</em>
+</dt>
+<dd>
+<p>
+ Creates an alias so that whenever the command <em>command</em> is found in the
+ source it is replaced with <em>replacement</em>. The idea of this is to make it
+ easier to import sources that use unknown directives, e.g.
+</p>
+<div class="literalblock">
+<div class="content">
+<pre><tt>alias setaddr,org
+alias ldreg,ld</tt></pre>
+</div></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>cpu z80</tt></pre>
+</div></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>setaddr $8000 ; These two are
+org $8000 ; equivalent.</tt></pre>
+</div></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>ld a,(hl) ; These two are
+ldreg a,(hl) ; equivalent.</tt></pre>
+</div></div>
+</dd>
+<dt class="hdlist1">
+nullcmd
+</dt>
+<dd>
+<p>
+ Simply does nothing. It’s only real use is as an alias if you wished to
+ strip a directive from a foreign source file.
+</p>
+</dd>
+<dt class="hdlist1">
+end
+</dt>
+<dd>
+<p>
+ Terminates the input processing. Anything past the directive will be
+ ignored.
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="_expressions">Expressions</h3>
+<div class="paragraph"><p>In any of the directives above, where a value is defined, an expression can be
+entered.</p></div>
+<div class="paragraph"><p>The following formats for constant numbers are supported (note these are
+illustrated as a regular expression):</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+"x" or <em>x</em>
+</dt>
+<dd>
+<p>
+ A single quoted character will be converted into the appropriate character
+ code.
+</p>
+</dd>
+<dt class="hdlist1">
+[1-9][0-9]*
+</dt>
+<dd>
+<p>
+ A decimal number, e.g. 42.
+</p>
+</dd>
+<dt class="hdlist1">
+0[0-7]*
+</dt>
+<dd>
+<p>
+ An octal number, e.g. 052.
+</p>
+</dd>
+<dt class="hdlist1">
+0x[0-9a-fA-f]+
+</dt>
+<dd>
+<p>
+ A hex number, e.g. 0x2a.
+</p>
+</dd>
+<dt class="hdlist1">
+[0-9a-fA-f]+h
+</dt>
+<dd>
+<p>
+ A hex number, e.g. 2ah.
+</p>
+</dd>
+<dt class="hdlist1">
+$[0-9a-fA-f]+
+</dt>
+<dd>
+<p>
+ A hex number, e.g. $2a.
+</p>
+</dd>
+<dt class="hdlist1">
+[01]+b
+</dt>
+<dd>
+<p>
+ A binary number, e.g. 00101010b
+</p>
+</dd>
+<dt class="hdlist1">
+[a-zA-Z_0-9]+
+</dt>
+<dd>
+<p>
+ A label, e.g. <tt>main_loop</tt>.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>The following operators are understood. The order here is the order of
+precedence.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+{ }
+</dt>
+<dd>
+<p>
+ Brackets used to alter the order of precedence. Note normal parenthesis
+ aren’t used as the assembly language may make use of them.
+</p>
+</dd>
+<dt class="hdlist1">
+~ + -
+</dt>
+<dd>
+<p>
+ Bitwise NOT/unary plus/unary minus.
+</p>
+</dd>
+<dt class="hdlist1">
+<< >>
+</dt>
+<dd>
+<p>
+ Shift left/shift right.
+</p>
+</dd>
+<dt class="hdlist1">
+/ * %
+</dt>
+<dd>
+<p>
+ Division/multiplication/modulus.
+</p>
+</dd>
+<dt class="hdlist1">
++ -
+</dt>
+<dd>
+<p>
+ Addition/subtraction.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>All the following have the same precedence, and so will be done left to right.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+==
+</dt>
+<dd>
+<p>
+ Equality. Returns 1 if the arguments are equal, otherwise zero.
+</p>
+</dd>
+<dt class="hdlist1">
+!=
+</dt>
+<dd>
+<p>
+ Inequality. Returns 1 if the arguments are unequal, otherwise zero.
+</p>
+</dd>
+<dt class="hdlist1">
+< <= > >=
+</dt>
+<dd>
+<p>
+ Less than/less than or equal/greater than/greater than or equal. Returns 1
+ if the arguments are equal, otherwise zero.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>All the following have the same precedence, and so will be done left to right.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+&& &
+</dt>
+<dd>
+<p>
+ Boolean/bitwise AND. For boolean operation arguments, zero is FALSE,
+ otherwise TRUE.
+</p>
+</dd>
+<dt class="hdlist1">
+|| |
+</dt>
+<dd>
+<p>
+ Boolean/bitwise OR.
+</p>
+</dd>
+<dt class="hdlist1">
+^
+</dt>
+<dd>
+<p>
+ Bitwise XOR.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt> 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</tt></pre>
+</div></div>
+<div class="paragraph"><p>Note that the expression is evaluated using a standard C int, and then cast
+to the appropriate size.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_character_sets">Character Sets</h3>
+<div class="paragraph"><p>The assembler has built-in support for a few different character sets.
+These can be set by using the options <em>charset</em> or <em>codepage</em>, i.e.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt> option codepage, <format>
+ option charset, <format></tt></pre>
+</div></div>
+<div class="paragraph"><p>The following values can be used for <em>format</em>.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+ascii
+</dt>
+<dd>
+<p>
+ 7-bit ASCII. This is the default.
+</p>
+</dd>
+<dt class="hdlist1">
+spectrum
+</dt>
+<dd>
+<p>
+ The character codes as used on the Sinclair ZX Spectrum.
+</p>
+</dd>
+<dt class="hdlist1">
+zx81
+</dt>
+<dd>
+<p>
+ 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.
+</p>
+</dd>
+<dt class="hdlist1">
+cbm
+</dt>
+<dd>
+<p>
+ PETSCII as used on the Commodore Business Machine’s range from the
+ PET to the C128. See <a href="https://en.wikipedia.org/wiki/PETSCII">https://en.wikipedia.org/wiki/PETSCII</a> for
+ more details.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>e.g.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt> 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</tt></pre>
+</div></div>
+</div>
+<div class="sect2">
+<h3 id="_macros">Macros</h3>
+<div class="paragraph"><p>Macros can be defined in one of two ways; either parameterless or with named
+parameters. Macro names are case-insensitive.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>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</tt></pre>
+</div></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>mac: macro char,junk,interface
+
+ ld a,@char
+ ld b,\2
+ call @interface
+
+ endm</tt></pre>
+</div></div>
+<div class="paragraph"><p>The at symbol (@) used for parameter expansion in named argument macros can
+be replaced by using the following option, e.g.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt> option macro-arg-char,&</tt></pre>
+</div></div>
+<div class="paragraph"><p>Note that this is enforced when the macro is <strong>used</strong>, not when it is <strong>defined</strong>.
+Also the character must not be quoted, as that will be parsed as a string
+holding the character code of the character.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_output_format">Output Format</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>By default the assembled code is written to a file called <strong>output</strong> as raw
+binary covering the block of memory that the assembly touched.</p></div>
+<div class="paragraph"><p>This can be controlled with the following options.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+option output-file, <em>file</em>
+</dt>
+<dd>
+<p>
+ Send the output to <em>file</em>.
+</p>
+</dd>
+<dt class="hdlist1">
+option output-type, <em>format</em>
+</dt>
+<dd>
+<p>
+ Controls the output format with the following settings
+</p>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+raw
+</dt>
+<dd>
+<p>
+ The default raw binary.
+</p>
+</dd>
+<dt class="hdlist1">
+spectrum
+</dt>
+<dd>
+<p>
+ 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.
+</p>
+</dd>
+</dl></div>
+</dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_listing">Listing</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>By default no output listing is generated. This can be controlled by the
+the following options.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+option list, <on|off>
+</dt>
+<dd>
+<p>
+ Enables/disables listing. The listing will go to stdout.
+</p>
+</dd>
+<dt class="hdlist1">
+option list-file, <em>file</em>
+</dt>
+<dd>
+<p>
+ Sends the listing to <em>file</em>. Note this should appear before enabling the
+ listing.
+</p>
+</dd>
+<dt class="hdlist1">
+option list-pc, <on|off>
+</dt>
+<dd>
+<p>
+ 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 <strong>off</strong>.
+</p>
+</dd>
+<dt class="hdlist1">
+option list-hex, <on|off>
+</dt>
+<dd>
+<p>
+ Control the output of the bytes generated by the source line in hex.
+ Defaults to <strong>off</strong>. If <strong>on</strong> 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.
+</p>
+</dd>
+<dt class="hdlist1">
+option list-labels, <on|off|all>
+</dt>
+<dd>
+<p>
+ Controls the listing of labels, either <strong>off</strong> (the default), <strong>on</strong> to dump
+ label values at the end of the listing and <strong>all</strong> to dump all labels,
+ including internally generated private labels for macros.
+</p>
+</dd>
+<dt class="hdlist1">
+option list-macros, <off|exec|dump|all>
+</dt>
+<dd>
+<p>
+ Controls the listing of macro invocations, either
+</p>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+off
+</dt>
+<dd>
+<p>
+ The default; don’t list anything.
+</p>
+</dd>
+<dt class="hdlist1">
+exec
+</dt>
+<dd>
+<p>
+ List invocations of macros.
+</p>
+</dd>
+<dt class="hdlist1">
+dump
+</dt>
+<dd>
+<p>
+ Produce a list of macro definitions at the end of the listing.
+</p>
+</dd>
+<dt class="hdlist1">
+all
+</dt>
+<dd>
+<p>
+ Combine "exec" and "dump"
+</p>
+</dd>
+</dl></div>
+</dd>
+<dt class="hdlist1">
+option list-rm-blanks, <on|off>
+</dt>
+<dd>
+<p>
+ Defaults to <strong>on</strong>. This option causes multiple blank lines to be collapsed
+ down to a single line.
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_z80_cpu">Z80 CPU</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_opcodes">Opcodes</h3>
+<div class="paragraph"><p>The Z80 assembler uses the standard Zilog opcodes, and supports
+undocumented instructions.</p></div>
+<div class="paragraph"><p>For instructions were the Accumulator can be assumed it can be omitted, and
+EOR can be used the same as XOR:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt> xor a,a ; These are equivalent
+ xor a
+ eor a,a
+
+ and a,b ; These are equivalent
+ and b</tt></pre>
+</div></div>
+<div class="paragraph"><p>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:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt> 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.</tt></pre>
+</div></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt> srl (iy-1),d
+ set 3,(iy-1),a
+ res 4,(iy-1),b</tt></pre>
+</div></div>
+<div class="paragraph"><p>For the hidden IN instruction using the flag register the following are all
+equivalent:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt> in (c)
+ in f,(c)</tt></pre>
+</div></div>
+<div class="paragraph"><p>For the hidden OUT instruction using the flag register, $00 or $ff depending
+on where you’re reading, the following are all equivalent, where <em>value</em> can
+be any value at all:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt> out (c)
+ out (c),f
+ out (c),<value></tt></pre>
+</div></div>
+</div>
+<div class="sect2">
+<h3 id="_options">Options</h3>
+<div class="paragraph"><p>The Z80 assembler has no options.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_6502_cpu">6502 CPU</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_opcodes_2">Opcodes</h3>
+<div class="paragraph"><p>The 6502 assembler uses the standard Motorola opcodes.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_options_2">Options</h3>
+<div class="paragraph"><p>The 6502 assembler has the following options.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+option zero-page, <on|off|auto>
+</dt>
+<dd>
+<p>
+ Use Zero-Page addressing for <em>absolute</em> and <em>absolute</em>,X address modes.
+ If mode is set to <strong>auto</strong> then tries to calculate the mode based on the
+ value in the last pass.
+ Defaults to <strong>off</strong>. e.g.
+</p>
+<div class="literalblock">
+<div class="content">
+<pre><tt>cpu 6502
+org $8000</tt></pre>
+</div></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>lda $0000,x ; Produces $bd $00 $00
+option +zero-page
+lda $0000,x ; Produces $b5 $00
+lda $1234,x ; Produces an error</tt></pre>
+</div></div>
+<div class="literalblock">
+<div class="content">
+<pre><tt>option zero-page,auto
+lda $00,x ; Produces $b5 $00
+lda $8000,x ; Produces $bd $00 $80</tt></pre>
+</div></div>
+</dd>
+</dl></div>
+</div>
+</div>
+</div>
+</div>
+<div id="footnotes"><hr /></div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2016-01-27 16:12:35 GMT
+</div>
+</div>
+</body>
+</html>
diff --git a/doc/manual.pdf b/doc/manual.pdf Binary files differnew file mode 100644 index 0000000..d39db3e --- /dev/null +++ b/doc/manual.pdf |