aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorIan C <ianc@noddybox.co.uk>2016-03-07 15:00:21 +0000
committerIan C <ianc@noddybox.co.uk>2016-03-07 15:00:21 +0000
commit77e8708934c5c792b1435fa11dfe3c0a6f636a8c (patch)
tree8c68ecddaf2c2c0730ba310b8d1b9e0f1bd16132 /doc
parent6e9c9c9205d6eec1ff1cfb3fa407c6714854145a (diff)
Updated README and copied latest version in.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile32
-rw-r--r--doc/README22
-rw-r--r--doc/manual.asciidoc546
-rw-r--r--doc/manual.html1577
-rw-r--r--doc/manual.pdfbin0 -> 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">
+/*<![CDATA[*/
+var asciidoc = { // Namespace.
+
+/////////////////////////////////////////////////////////////////////
+// Table Of Contents generator
+/////////////////////////////////////////////////////////////////////
+
+/* Author: Mihai Bazon, September 2002
+ * http://students.infoiasi.ro/~mishoo
+ *
+ * Table Of Content generator
+ * Version: 0.4
+ *
+ * Feel free to use this script under the terms of the GNU General Public
+ * License, as long as you do not remove or alter this notice.
+ */
+
+ /* modified by Troy D. Hanson, September 2006. License: GPL */
+ /* modified by Stuart Rackham, 2006, 2009. License: GPL */
+
+// toclevels = 1..4.
+toc: function (toclevels) {
+
+ function getText(el) {
+ var text = "";
+ for (var i = el.firstChild; i != null; i = i.nextSibling) {
+ if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
+ text += i.data;
+ else if (i.firstChild != null)
+ text += getText(i);
+ }
+ return text;
+ }
+
+ function TocEntry(el, text, toclevel) {
+ this.element = el;
+ this.text = text;
+ this.toclevel = toclevel;
+ }
+
+ function tocEntries(el, toclevels) {
+ var result = new Array;
+ var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
+ // 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 &#169; 2003-2015 Ian Cowburn &lt;<a href="mailto:ianc@noddybox.co.uk">ianc@noddybox.co.uk</a>&gt;</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&#8217;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 &lt;value&gt;[, &lt;value&gt;]
+</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&#8217;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&#8217;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">
+&lt;&lt; &gt;&gt;
+</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">
+&lt; &lt;= &gt; &gt;=
+</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">
+&amp;&amp; &amp;
+</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, &lt;format&gt;
+ option charset, &lt;format&gt;</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&#8217;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,&amp;</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, &lt;on|off&gt;
+</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, &lt;on|off&gt;
+</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, &lt;on|off&gt;
+</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, &lt;on|off|all&gt;
+</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, &lt;off|exec|dump|all&gt;
+</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&#8217;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, &lt;on|off&gt;
+</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&#8217;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),&lt;value&gt;</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, &lt;on|off|auto&gt;
+</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
new file mode 100644
index 0000000..d39db3e
--- /dev/null
+++ b/doc/manual.pdf
Binary files differ