qasm/doc/DIALECT.md

Merlin 16+ dialect

QuickAsm implements Merlin 16+ (Glen Bredon, Roger Wagner Publishing, 1988–89). The language contract is:

• doc/manuals/Merlin_816_Macro_Assembler_Manual.pdf — base syntax
• doc/manuals/Merlin_16_Supplementary_Manual.pdf — 16+ additions

Merlin 16+ is the native language and the form the encoder consumes. ORCA/M, LISA, Merlin 32, and ca65 sources are lowered to that form. Identification, pcode, per-dialect pseudo-ops, and limitations are in doc/SYNTAX.md.

Line format

LABEL    OPCODE    OPERAND    ; comment

• A label, if present, starts in column 0 (no leading whitespace).
• Fields are separated by spaces or tabs.
• * or ; as the first non-blank character makes a comment line.
• Opcode mnemonics are case-insensitive. Labels, macros, and equates follow CAS SE / CAS IN (default: insensitive, typical FARMS).

Native 16+ source files (disk / IIgs editor)

On disk, Merlin 16+ source is not plain ASCII:

• Letters, digits, and punctuation normally have bit 7 set.
• Column tabs (label / opcode / operand / comment) are a single $A0 (space with the high bit set). $09 and $89 (TAB) are accepted too.
• Literal spaces in quoted operands and comments are $20 (high bit clear), so columns can be split without tracking quotes.
• Lines end with $8D (high-bit CR), sometimes $0D / $0A.
• Extra $A0 after the third separator is an ordinary space.

Host-side .s files (spaces, TABs, LF/CRLF, high bit clear) are also accepted.

Processors

XC	CPU
XC OFF	6502 only
XC once	65C02
XC twice (16+ default at startup)	65802 / 65816

Startup: 65816 opcodes on, MX %11 (emulation). Put explicit MX / XC at the top of each source so it matches a real 16+ machine regardless of FARMS.

SEP / REP update assembler MX from a constant immediate. MX %00–%11 (or 0–3) sets it without emitting code. M=0 / X=0 is 16-bit; 1 is 8-bit.

Addressing

Merlin does not write ASL A. Accumulator/implied is a bare mnemonic.

Immediate data starts with #. Addresses do not.

Syntax	Mode
LDA #$00	immediate (8 or 16 from M)
LDA $10	direct page if value < $100 and not forced
LDA $C000	absolute
LDAL $E12000 / LDA >$E12000	long
LDA: $10	force absolute (any 4th opcode character except L or D)
LDA <$1234	force direct page (low byte)
LDA |$04	force absolute
LDA ($10),Y	DP indirect indexed
LDA [$10],Y	DP indirect long indexed
LDA $10,S	stack relative
LDA ($10,S),Y	stack relative indirect indexed
BEQ LABEL	relative
MVN src,dst	block move (object: dest bank, src bank)

Immediate byte/word selects (8-bit vs 16-bit from MX):

	8-bit	16-bit
#expr / #<expr	low byte	low word (bytes 0–1)
#>expr	high byte	high word (bytes 1–2)
#^expr / #Aexpr	bank byte	bank word (bytes 2–3)

Address-mode force prefixes (16+):

Prefix	Mode
<expr	force direct page (low byte)
|expr	force absolute (16-bit)
>expr	force absolute long (24-bit)
^expr	absolute using the high word
LDAL / lda:	long / forced absolute

; inside an operand with no preceding space is data (macro parameters arg1;arg2). A ; after whitespace starts a comment.

Alternate mnemonics: BLT=BCC, BGE=BCS, TAS=TCS, TSA=TSC, TAD=TCD, TDA=TDC, SWA=XBA. Long ALU forms LDAL, STAL, …

Undefined labels are 16-bit (absolute) until equated. Zero-page labels must be defined before use.

Expressions

Numbers: decimal, $hex, %binary. ASCII 'A' / "A". * is the program counter at term position, multiply at operator position.

Default evaluation is left-to-right, no precedence (1+2*3 = 9). Enclose in { } for algebraic precedence. --algebraic does that for all expressions (FARMS bit; can break LAB1-LAB2/2 sources).

Operators, lowest to highest inside braces:

<  =  >  #          comparison (true=1, false=0); # is not-equal
+  -
*  /
&  .  !             AND, OR, XOR
-                   unary minus

( ) are addressing, not grouping. Use { }.

Labels

• Global: start with a letter or extra-alphabetic (not a digit). Max 26 characters on a real 16+.
• ]NAME as a label is a backward-only local (nearest previous).
• :NAME is a local whose scope is the enclosing global labels.
• ]NAME = expr is a variable (redefinable). No forward refs.
• Locals cannot be ENT/EXT and cannot be the first label in a file.

Directives

ORG, OBJ, EQU/=, PUT, USE, VAR, SAV, DSK, END, DUM, DEND, TYP, REL, LNK, ENT, EXT, MX, XC, CAS, ERR, CHK, DATE, FLO (10-byte SANE), STRL, LST, EXP, TR, PAU, PAG, AST, SKP.

PUT file inserts and assembles another source (search: directory of the current file, -I dirs, then .; .s is optional). USE file loads macros from that file without assembling its code. VAR e1;e2;… assigns ]1…]9 for a following PUT.

Data: HEX, DFB/DB, DA/DW, DDB, ADR, ADRL, DS, ASC, DCI, INV, FLS, REV, STR, STRL.

ASC accepts hex bytes mixed into the string, empty strings, and ASC #expr / #' / #" / #>.

Conditionals: DO / ELSE / FIN, IF / ELSE / FIN. IF MX/2 tests M; IF "=]1" / IF #,]1 tests the first character of a variable (macros). Nest ≤ 8 on real 16+.

Macros: MAC … EOM / <<<. Call by name, or PMC / >>>. Parameters ]1–]9 separated by ;. Nest ≤ 15 on real 16+. Labels in a macro body (except EQU/=) are uniquified per expansion.

Loops: LUP n … --^. @ in a label becomes Z,Y,X,… per iteration (max 26).

Output

Absolute object (BIN) from ORG + DSK/SAV/-o. REL / Linker.GS / OMF v2.1 is not implemented yet.

TYP accepts hex ($B3) or ASCII names (SYS, S16, CDA, EXE, BIN).

16+ additions (vs Merlin 16) that are first-class here

• XC OFF
• CAS SE / CAS IN
• {algebraic} expressions and < = > # comparisons
• STRL
• mixed hex in ASC/STR/… and ASC #
• TYP ASCII filetypes
• SAV with REL
• LST FILE,name
• DATE operands 1–8
• FLO (SANE extended)