qasm/doc/SYNTAX.md

Syntaxes and pcode

Merlin 16+ is the language the encoder understands. Every other dialect is lowered to one 65816 pcode stream, and that stream is what gets assembled. The object is an absolute binary. Merlin line format, expressions, and the 16+ manual contract are in doc/DIALECT.md. This file is how a source file gets there, how each dialect's pseudo-ops are rewritten, and where the implementation stops.

Pipeline

source file
    │
    ├─ Options.syntax, or identify_syntax()
    │
    ├─ dialect front end  →  PCode
    │
    └─ assemble_pcode()   →  two passes, symbols, MX/CPU, bytes, listing

assemble_file reads one file and calls assemble_string. That identifies the dialect (unless --syntax overrides it) and compiles to pcode. assemble_lines skips identification and always uses the Merlin front end. That is the path for a caller that already parsed Merlin lines.

One command-line --syntax applies to every file. Each file is still assembled on its own, including under -j. A file that is PUT or USEd by another file on the same command line is not also assembled as a top-level job.

Startup, before any source directive:

State	Value
CPU	65816 (XC level 2)
MX	%11 (M and X both 8-bit)
PC and default ORG	$8000
Case	insensitive, until a directive says otherwise
File type	$06 BIN

MX bits: bit 1 (value 2) is M, bit 0 (value 1) is X. A set bit means 8-bit. After .a16 or longa on, M is clear, so LDA #1 is A9 01 00.

Assembly is two passes over the same pcode. Pass 1 assigns addresses and defines symbols. Pass 2 emits object bytes and the listing. On pass 2 a normal label is left at the value from pass 1. A Merlin variable (]N or ]NAME) is updated on both passes. An unknown label is an error on pass 2. Under REL, an unknown label is 0.

The listing header records the dialect (syntax=merlin, and so on). --dump-pcode asks the library to fill Result::pcode. The qasm command writes that text to <file>.pcode. The library does not write the file itself.

Identification

Order:

1. --syntax NAME, when it is not empty and not auto. An unknown name is an error and nothing is assembled.
2. A marker in the first 40 lines, after high bits are stripped: syntax: ca65, syntax ca65, !syntax ca65, or Assembler: Merlin 32, Assembler: APW, or Assembler: MPW. Merlin 32 and Merlin32 are checked before the single word Merlin. MPW selects APW. The listing name is apw.
3. A native Merlin file: a $A0 column tab or a $8D line ending, and more than four bytes with bit 7 set.
4. Otherwise, score distinctive tokens on comment-stripped, uppercased text. One occurrence is enough. Shared words such as ORG, EQU, JSR, END, and START add nothing. A leading dot matters: .ORG is not Merlin ORG.

Dialect	Tokens that score
Merlin	MX XC DFB DDB STRL ADRL DEND DSK LUP DCI FLS PMC EOM DUM PUT USE --^ MAC
Merlin 32	GEQU or GEQ (also counts as Merlin)
ORCA/M	LONGA LONGI ANOP MCOPY MEND PRIVDATA ENDC, or a DC lead-in I1' I2' I4' I1" I2" C' H'
APW/MPW	No separate score. ABSADDR, MSB, CODECHK, CODECHECK, or INSTIME selects APW when the winner would otherwise be ORCA/M or Merlin.
LISA	.OR .HS .BS .EQ .DA .EN .EP .AS .FI .EL .DB .BY
ca65	.ORG .BYTE .WORD .DWORD .FARADDR .RES .MACRO .ENDMACRO .P816 .A8 .A16 .I8 .I16 .PROC .IMPORT .EXPORT .SEGMENT .SETCPU .PC02 .P02 .FEATURE .INCLUDE .ALIGN .REPEAT .ENDPROC

The highest score wins. A tie stays Merlin. A score of zero stays Merlin, so a file that is only ORG / EQU / JSR / RTS is Merlin. If the Merlin 32 flag is set and Merlin wins, the dialect is Merlin 32. Merlin 32 uses the same front end and the same encoder as Merlin 16+.

ABSADDR, MSB, CODECHK, CODECHECK, or INSTIME then selects APW when that winner is ORCA/M or Merlin, including a Merlin 32 win. LISA and ca65 keep a higher score. A pure ORCA/M file stays ORCA/M. Assembler: MPW and --syntax mpw select APW, and the reported name is apw.

Accepted names: merlin, merlin16, merlin16+, merlin-16, merlin32, merlin-32, m32, orca, orca/m, orcam, orca-m, apw, mpw, apw/mpw, apw-mpw, lisa, lisa816, lisa-816, ca65, cc65, auto.

What pcode is

Each PInstr is one operation. Line-like operations carry a Merlin opcode and operand, because that is what the encoder evaluates. Control operations are executed by the pcode walker. Instruction lines also store a canonical view (cname, addressing form, force, byte select, expression) for the pcode dump. Encoding uses the opcode and operand text, not that canonical view.

Op	What the assembler does
P_NOP	Lists the line. A real label is defined at the PC. A MAC / EOM / <<< name is not a symbol. A comment label that starts with * or ; is not a symbol. The opcode is not executed.
P_LABEL	Defines the label at the PC. No bytes.
P_END	Defines a label if the line has one, then stops the assembly.
P_ORG	Merlin ORG. See below.
P_EQU	Merlin EQU, =, GEQU, or GEQ.
P_MX	Merlin MX.
P_XC	Merlin XC.
P_MXPART	Changes part of MX. i0 is the bit mask, i1 is the new bits. Applied even inside a false conditional.
P_CPU	Sets the CPU: 0 = 6502, 1 = 65C02, 2 = 65816. Applied even inside a false conditional.
P_INST	A machine instruction.
P_DATA	DFB / DB / DA / DW / DDB / ADR / ADRL.
P_DS	Merlin DS.
P_ASM	Any other Merlin pseudo-op (HEX, ASC, EXT, CAS, …).
P_BYTES	Raw bytes. The label is defined, then each byte is emitted.
P_ALIGN	Pad the PC up to a multiple of the count. Optional fill byte. Count and fill are expressions. A count of 0 or 1 does nothing. The count is capped at $10000.
P_IF / P_ELSE / P_ENDIF	Conditional. Labels on these lines are not defined.
P_LUP / P_ENDLUP	Loop. Labels on these lines are not defined.

For every op except the ones called out above, a label is defined at the current PC before the opcode runs. EQU / = / GEQU / GEQ are the exception: the label gets the expression value, not the PC.

P_IF / P_ELSE / P_ENDIF / P_LUP do not define a label. P_END does, then assembly stops. Lines after END are ignored.

Conditionals

DO and IF push a conditional level (maximum 15). The parent level must already be emitting, and the test must be true, before the body emits.

Merlin character IF is special. It applies only when the opcode text is IF and the second character of the operand is , or =. The first character of the operand is compared with the first character of the rest. No expression is evaluated. IF "=]1" and IF #,]1 are this form. IF 1+1 is an expression, because the second character is +.

ORCA/M, LISA, and ca65 expression tests are emitted with opcode DO, so the character form does not apply to them. A Merlin source IF stays IF.

ELSE emits when the parent is emitting and the matching test was false. FIN pops one level. A false branch still defines labels. The PC does not move, and instructions and data do not emit. ORG, EQU, MX, XC, CAS, DUM, DEND, REL, EXT, ENT, LNK, TYP, DSK, and SAV still take effect inside a false branch. VAR, FLO, DATE, HEX, CHK, data, strings, DS, ERR, and USR do not.

Loops

LUP n evaluates n once. A negative count runs zero times. The count is capped at $8000. The loop runs even when the surrounding conditional is false. Instructions inside still obey the conditional.

@ in a label, opcode, operand, or stored expression becomes a letter for that iteration: Z, Y, X, … down to A, then A again after 26. The file name is left alone. An outer LUP replaces @ in the inner body, including the inner loop's own @, before the inner loop runs. That is Merlin's text substitution.

ca65 .repeat is the same loop. A @ in a .repeat body is still replaced.

Macros

Macros are expanded while the source is lowered, not while pcode runs. The assembler's own macro table stays empty. A name that was not expanded is assembled as an instruction and fails if it is not a mnemonic.

An expansion is refused when it is already nested more than 16 deep. Merlin and ca65 put the call-site label on its own P_LABEL (or a P_NOP when there is no label). That label is not attached to the first instruction of the body. ORCA/M does that only when the prototype has no &lab parameter. When &lab is declared, the call-site label is substituted for &lab in the body and is not also defined on its own. Body lines are listed from the substituted fields.

Merlin parameters are ]1–]9, split on ;. A ] variable that is not a parameter stays text and is looked up when the line assembles, so VAR and a later PUT still work. Labels in the body are renamed to ozunid_N once, at expansion time, so both passes see the same names. ] locals, : locals, and EQU / = labels are not renamed. * in an operand stays an expression and is the PC at the moment that line assembles.

A macro whose name is also an instruction (inc calling inc) expands until the depth limit, then errors with "macro nest too deep".

CAS is recorded when the front end sees it, so later macro lookup in that file follows the same case rule the assembler will use. The CAS line is also in the pcode and runs again during assembly.

Expressions

Merlin operands are copied through unchanged. Evaluation is left to right with no precedence: 1+2*3 is 9. {1+2*3} is 7. --algebraic turns on precedence for every Merlin expression. Parentheses are addressing, not grouping.

ca65 and ORCA/M expressions are rewritten into fully parenthesized Merlin before they are assembled. 1+2*3 becomes {1+{2*3}} and is 7. (1+2)*3 becomes {{1+2}*3} and is 9. A number or a bare name is left unwrapped. On a parse failure the original text is kept.

Source	Merlin text
a|b, a || b, .or, .bitor	{a.b} (OR)
a^b, .xor, .bitxor, .eor	{a!b} (XOR)
a&b, a&&b, .and, .bitand	{a&b} (AND)
a<>b	{a#b} (not equal)
a<=b	{{a<b}.{a=b}}
a>=b	{{a>b}.{a=b}}
~x	{x!-1} when ~ is not an ORCA/M local label
<x, .lobyte(x)	low byte
>x, .hibyte(x)	high byte
^x, .bankbyte(x)	bank byte
*	program counter

The rewrite is applied to the expression inside an operand, not to the addressing punctuation. (dp),y stays indirect indexed. z:, a:, f:, zeropage:, direct:, absolute:, near:, and far: become Merlin force prefixes <, |, and >.

LISA expressions stay left to right. They are not rewritten.

<< and >> are not rewritten. The original text is handed to the Merlin evaluator, which has no shift operator. -> is left as source text for the same reason.

Includes

Search order: the directory of the file that contains the directive, then each -I directory, then .. For each name the assembler also tries .s, .S, .Macs, and .Macs.s. A Merlin prefix 4/Mem.Macs is tried again without the 4/. Quotes around the name are stripped. An include cycle is an error. Nesting stops at 16.

PUT, USE, ORCA/M COPY / APPEND / MCOPY, and ca65 .include are pulled in while the file is lowered. That happens before conditionals run, so the included file is assembled even when the directive sits in a false DO / IF. USE only collects macros. The other forms assemble the included code at the point of the directive.

Merlin and Merlin 32 pseudo-ops

These are the operations the assembler executes. Merlin 32 is the same set. GEQU and GEQ are equates, and they also mark the file as Merlin 32 during identification. The line format is doc/DIALECT.md.

A label on END is defined. A label on DO, IF, ELSE, FIN, LUP, or --^ is not.

Directive	Treatment
ORG expr	Sets the PC. The first ORG also sets the object origin. A later ORG saves the PC, and a bare ORG restores that saved PC once. ORG inside DUM moves the PC and leaves the saved PC alone. Object bytes stay one stream; ORG does not insert a gap in the file.
EQU = GEQU GEQ	Define the label as the expression. A label that starts with ] is a variable and may be redefined.
MX expr	Sets MX to the value anded with 3. An empty operand is %11.
XC	XC OFF selects the 6502. Any other XC steps 6502 → 65C02 → 65816 and then stays there.
CAS SE / CAS IN	Case-sensitive or case-insensitive symbols. The first two letters decide.
DUM expr / DEND	DUM saves the PC, sets dummy, and moves the PC to the expression. Bytes are not stored. DEND restores the PC.
REL	Marks the assembly relocatable for symbol lookup. If there has been no ORG, the PC and origin become 0. Unknown labels are 0. No relocatable records are written.
EXT a,b,c	Defines each name as 0. A label on the line is also 0.
ENT / LNK	A label on the line is defined at the PC. No relocation record.
LEN / POS	Defines the operand (or the line label) as 0.
CHK	Emits one byte, the XOR of object bytes since the last ORG.
USR	Emits two zero bytes. The operand is ignored. In a false conditional this emits nothing.
HEX	Hex digit pairs. Spaces and commas are skipped. An odd digit count is an error.
DFB DB	One byte per expression.
DA DW	Little-endian word per expression.
DDB	Big-endian word per expression.
ADR	Three-byte address.
ADRL	Four-byte address.
DS n / DS n,fill	n bytes of fill (default 0). DS \ aligns to the next page boundary (256 bytes when already aligned). n is capped at $10000.
ASC STR DCI INV FLS REV STRL	String data. Single quotes are plain ASCII. Double quotes set bit 7. See doc/DIALECT.md for hex mixed into the string and for STRL.
FLO	Ten-byte SANE extended.
DATE	Nine-byte date. Modes 1–8. See doc/DIALECT.md.
ERR expr	Error on pass 2 when the expression is non-zero.
PUT	Assemble the included file at this point. This happens while the file is lowered, so a PUT in a false conditional is still included.
USE	Load macros from the file. Its code is not assembled. Collected the same way as PUT, including inside a false conditional.
VAR e1;e2;…	Set variables ]1…]9. Empty arguments stop the list. Skipped in a false conditional.
DSK / SAV	Output file name. Surrounding quotes are removed.
TYP	File type. $B3 or a name: BIN $06, SYS $FF, S16/SYS16 $B3, CDA $B9, NDA $B8, EXE $B5, TXT $04, SRC $B0, LNK $2E.
MAC … EOM or <<<	Macro definition. The body is not assembled at the definition.
PMC name args / >>>	Call that macro. The name is the first word of the operand.
DO / IF / ELSE / FIN	Conditionals, as above.
LUP n … --^	Loop, as above. A stray --^ is ignored.
END	Stop assembly.
LST EXP TR PAU PAG AST SKP KBD OBJ DAT OVR ASM SYM CYC	No object bytes. A label is still defined at the PC.

ASL A (and the other accumulator ALU mnemonics with a lone A) is the accumulator form. A bare mnemonic is the same form.

ORCA/M

The Merlin line parser is used, then a column fix. A trailing : on a label is removed. A directive written in the label column is shifted into the opcode column, so longa off at column 0 works. start anop stays a label plus ANOP, because both words are directives and the line is not shifted. The line is also left alone when the second field is an instruction mnemonic, so a label may be spelled like a directive (APPEND PHP, PRINT STA).

Expressions in operands are algebraic, as above. A ~ followed by a name is a local label (~loop) and is scoped between global labels, the same way as a Merlin :label. A ~ before a number or parenthesis is bitwise NOT.

Directive	Treatment
ORG	Merlin ORG with an algebraic expression.
EQU GEQU	Merlin equate. The operand is algebraic.
DS	Merlin DS. Each comma-separated expression is algebraic.
DC	One or more typed constants. See the next table. The label goes on the first item.
LONGA / LONGI	ON, YES, or 1 selects 16-bit (that MX bit clears). Any other operand, including OFF and an empty operand, selects 8-bit.
IF / ELSE / ENDC / FIN / ENDIF	Merlin DO / ELSE / FIN. The test is algebraic.
EXTERN	Merlin EXT. Each name is 0.
ENTRY	Label only.
ALIGN n / ALIGN n,fill	P_ALIGN. An empty count is 2.
CASE ON	CAS SE. Any other operand is CAS IN.
MACHINE	6502 or 65C02 selects that CPU. Anything else, including 65816, selects the 65816. 65C02 is recognized as the 65C02.
START DATA PRIVATE PRIVDATA ANOP	Label only. They do not open a segment or change the PC.
MACRO / MEND / ENDM	Macro. The next non-blank line is the prototype: the opcode is the name, a label &lab receives the call-site label, and the operand is the parameter list. Names in the body that start with & are replaced, longest first.
COPY APPEND MCOPY	Include and assemble as ORCA/M. Macros in the file are collected.
USING EJECT OBJ OBJEND KEEP MERR MEM	No bytes. A label is kept.
END	Stop assembly.
AIF AGO AELSE AEND AWHILE SETA SETB SETC LCLA LCLB LCLC GBLA GBLB GBLC MNOTE MEXIT ACTR DIRECT KIND RENAME SETCOM	Error: unsupported ORCA directive. A label on the line is kept.

DC types, written type'value' or type"value":

Type	Bytes
C	Characters. A value with no embedded quote becomes Merlin ASC in single quotes. Any other value is raw bytes.
H	Hex digits. Spaces and commas inside the quotes are removed, then Merlin HEX.
I1 B	One byte per comma-separated expression (DFB).
I I2 A R	One little-endian word per expression (DA). R is not a relocation; it is a word.
I3	Three-byte address (ADR).
I4	Four-byte address (ADRL).

An unknown DC type, or a type that is not followed by a quote, is an error. Several specs may share one DC line, separated by commas outside the quotes: dc i1'1,2',i2'$10',c'A',h'0d' is 01 02 10 00 41 0D.

Instruction operands are algebraic in the expression only. jsr bell stays JSR bell.

APW/MPW

APW is Apple's 65816 assembler. It is the ORCA/M language Apple shipped, so this dialect uses the ORCA/M front end. --syntax apw and --syntax mpw both select it. Assembler: APW and Assembler: MPW do too. The listing and the pcode dump say syntax=apw.

The MPW IIgs assembler is the other Apple 65816 assembler. The forms below that change bytes are accepted on this same dialect. Its RECORD templates and STRING PASCAL or STRING C prefixes are not applied: those directives are kept and emit no bytes.

Everything in the ORCA/M tables above works. These are the additions. ABSADDR and MSB are applied while the file is lowered, including inside a false IF, the same way CASE is.

Directive	Treatment
ABSADDR ON	ON, YES, or 1 forces later instruction operands to absolute when they have no <, |, or > and are not immediate or implied. Any other operand, including OFF, clears it. The default is off, which matches ORCA/M.
MSB ON	ON, YES, or 1 sets bit 7 on each later DC C character and on each character of a quoted DC.B string. The bytes are raw. Any other operand clears it. The default is off, so DC C stays ORCA/M ASCII.
65816 65C02 6502	Selects that CPU, as MACHINE does. OFF, NO, or 0 leaves the CPU alone. An empty operand selects the CPU.
MACHINE M65816	The ORCA/M MACHINE check. M65816, M65C02, and M6502 select that CPU.
PROC FUNC MAIN	Label only, like START. They do not open a segment. An operand temporg expr or org expr (with an optional leading ENTRY) is Merlin ORG before the label is defined. ENTRY itself emits no bytes.
RECORD CODE	Label only. They do not open a segment.
ENDP ENDPROC ENDF ENDFUNC ENDMAIN ENDR ENDS ENDWITH	No bytes. They do not stop the file. END still does.
IMPORT	Merlin EXT. Each name is 0.
EXPORT	No bytes. A label on the line is kept. There is no export record yet.
SET	Merlin EQU.
DC.B DCB	One byte per comma-separated expression (DFB). An item that is only a single- or double-quoted string emits one byte per character. MSB ON sets bit 7 on those bytes. A one-character quote used inside a larger expression stays an expression.
DC.W	One word per expression (DA).
DC.L	Four-byte values (ADRL).
DS.B	Merlin DS. The count is a number of bytes. A second comma-separated value is the fill.
DS.W	Merlin DS of twice the count (words).
DS.L	Merlin DS of four times the count (longs).
INCLUDE	Include and assemble, the same as COPY.
CODECHK CODECHECK DATACHECK DATACHK DYNCHK EXPAND GEN IEEE INSTIME LIST NUMSEX OBJCASE PRINTER SYMBOL TITLE STRING BLANKS PRINT SEG SEGATTR PAGESIZE SPACE	No bytes. A label is kept.
KIND RENAME SETCOM DIRECT	No bytes. A label is kept. The same lines are errors under ORCA/M.

A directive written in the label column is shifted when it is one of these, the same way an ORCA/M directive is. A second field that is an instruction mnemonic keeps the first word as the label.

An immediate #name is that symbol, including a name that starts with A. Merlin's #Aexpr bank prefix is not applied. The bank byte is ^.

LISA

The Merlin line parser is used. A trailing : on a label is removed. A label that starts with . is a directive that was written in column 0; it is shifted into the opcode column. One leading dot is stripped and the opcode is uppercased, so .OR, .EQ, and OR are the same directive. Instruction mnemonics keep their original spelling. The encoder is case-insensitive.

Expressions stay left to right. There is no macro language.

Directive	Treatment
.OR .ORG	Merlin ORG.
.EQ .EQU	Merlin EQU.
.EP .EPZ	Merlin EQU, and the label is remembered. A later instruction whose entire address expression is that name is forced to direct page, even when the value is greater than 255. EPZ $1234 then LDA ZP is A5 34.
.DA	Split on commas. A quoted item is ASC. #expr is DFB (one byte). /expr is DFB >expr (high byte). Anything else is a word (DA). The label goes on the first item.
.DB .BY .BYT .BYTE .DFB	DFB. An item that starts with / becomes >item.
.HS .HEX	Merlin HEX.
.AS .ASC .AT	Merlin ASC.
.BS .BLK .DFS .DS	Merlin DS.
.IF / .EL or .ELSE / .FI or .FIN	Merlin DO / ELSE / FIN. The test is left to right.
.EN .END	Stop assembly.
MX XC	Merlin MX and XC. LISA has no register-width directive; these set the immediate size so a 65816 immediate matches the other syntaxes.
.STR .DCI .INV	The same Merlin string directives.
anything else with an opcode	Instruction. A leading / on the operand becomes #>, the high-byte immediate.

ca65

ca65 has its own line parser. ; starts a comment outside quotes. name: is a label. name = expr and name := expr are equates. A directive starts with .. The first pcode operation of every ca65 file is CAS SE, so symbols and macro names are case-sensitive before the first user line. --case-sensitive is then redundant for ca65.

Expressions are algebraic. .repeat is LUP and has no ca65-style counter variable. @ in the body is still the Merlin loop letter.

Directive	Treatment
.ORG	Merlin ORG, algebraic.
= .EQU	Merlin =, algebraic.
.SET name, expr	The same equate. On pass 1 a later .SET of the same name replaces the value. Pass 2 keeps that last value for the whole file, so a .SET does not take effect in the middle of pass 2.
.BYTE .BYT	DFB for numbers and expressions. "..." is raw ASCII bytes, with \\ \" \' \n \r \t. A one-character 'A' stays an expression. A longer single-quoted string is raw bytes. The label goes on the first item.
.WORD .ADDR	Little-endian words (DA).
.FARADDR	Three-byte addresses (ADR).
.DWORD .LONG	Four-byte values (ADRL).
.RES .DS	Merlin DS. Each part is algebraic.
.ALIGN n / .ALIGN n,fill	P_ALIGN. An empty count is 2.
.A8 .A16 .I8 .I16	Set the M bit (.A*) or the X bit (.I*). 8 sets the bit. 16 clears it.
.P816	CPU 65816.
.P02	CPU 6502.
.PC02	CPU 65C02.
.SETCPU	65C02 or 65SC02 selects the 65C02. 6502 selects the 6502. Anything else selects the 65816.
.IF .IFNE	Merlin DO. Non-zero is true. Algebraic. An empty test is 1.
.IFEQ	True when the expression is 0.
.ELSE / .ENDIF .FI	Merlin ELSE / FIN.
.ELSEIF	Error. The line emits nothing.
.END	Stop assembly.
.PROC .SCOPE	Label only, from the label or from the operand. No scope is pushed. .ENDPROC and .ENDSCOPE are ignored.
.IMPORT .IMPORTZP	Merlin EXT. A :size suffix on a name is removed. The name is 0. .IMPORTZP does not force direct page.
.INCLUDE	Include and assemble as ca65.
.MACRO … .ENDMACRO or .ENDMAC	Macro. Parameters are whole identifiers, case-sensitive, longest first. The call name arg,arg matches.
.REPEAT … .ENDREPEAT or .ENDREP	LUP. The count is algebraic.
.ERROR	The operand is recorded as an error.
.SMART .FEATURE .LIST .DEBUGINFO .ASSERT .LOCAL .SEGMENT .CODE .DATA .RODATA .BSS .ZEROPAGE .ENDPROC .ENDSCOPE .EXPORT .EXPORTZP .GLOBAL .CASE .WARNING .OUT	No bytes. A label is defined. Segments do not move the PC or change the origin.
any other .directive	Error: unsupported ca65 directive. A label is kept.
a line that is only a label	Defines the label at the PC.

Size prefixes on an instruction operand (lda z:label, lda f:addr) become Merlin < / | / >.

Object and listing

The object is the bytes emitted on pass 2, in order. ORG changes the PC and the recorded origin. It does not pad the file. DUM moves the PC without storing bytes. The default origin is $8000 when no ORG and no REL ran. REL with no ORG records origin 0.

DSK or SAV names the output file when -o is absent. Otherwise the output is <source>.bin. A listing file is written only with -l FILE. FILE may be - or stdout to write the listing to standard output. --no-lst turns that listing off. TYP changes the type printed in the status line and stored on Result. It does not wrap the bytes in an OMF record.

The pcode dump is one line per operation: file, line, op name, label, opcode, operand, and for instructions the addressing form and expression. P_MXPART, P_CPU, and P_BYTES add their mask, CPU, or hex bytes.

Limitations

These are properties of this assembler, not of the original dialects.

• The object is absolute BIN. REL, ENT, EXT, .IMPORT, and DC R do not produce OMF or Linker.GS records. External and unknown relocatable names are 0.
• ORCA/M segments (START, DATA, PRIVATE, PRIVDATA) and ca65 segments (.SEGMENT, .CODE, .DATA, .RODATA, .BSS, .ZEROPAGE) are one flat PC. They do not change the origin.
• ORCA/M conditional macro language is rejected: AIF, AGO, SETA, LCLA, and the related directives listed above.
• APW/MPW ABSADDR and MSB take effect while the file is lowered, so a false IF does not hide them. KIND, RENAME, SETCOM, and DIRECT are ignored for APW/MPW and are errors for ORCA/M.
• MPW RECORD templates are not expanded, and STRING PASCAL or STRING C does not add a length byte or a terminator. DC.W and DC.L take comma-separated expressions, not a quoted character string. A quoted DC.B item is raw bytes. Use ORCA/M DC C for a typed character constant on the same line as other DC types.
• ca65 anonymous labels (:, :+, :-), .ELSEIF, and scoped .PROC / .LOCAL symbols are not implemented. .LOCAL is ignored.
• ca65 .SMART, .FEATURE, and listing controls do not change encoding or the listing.
• ca65 .IMPORTZP defines the symbol as 0 and leaves addressing to the value and to any z: prefix. It does not remember the name the way LISA .EPZ does.
• Shift operators and -> are not rewritten into Merlin expressions.
• There is no separate ca65 or ORCA/M operator for true logical AND/OR that yields only 0 or 1 beyond the bitwise operators above. && and || are bitwise AND and OR.
• PUT, USE, COPY, MCOPY, APPEND, and .include are expanded while lowering, including inside a false conditional.
• A macro that calls its own name recurses until the depth limit, then errors.
• ca65 .SET updates the symbol on pass 1. Pass 2 uses the final pass-1 value everywhere, including at lines that appear before the later .SET.
• @ inside ca65 .repeat is the Merlin loop letter.
• Nested LUP bodies share one @. The outer loop substitutes first.
• Loop count maximum is $8000. Conditional nesting maximum is 15. An include or macro expansion is refused when it is already nested more than 16 deep. DS and ALIGN counts are capped at $10000.
• Only the first 26 LUP iterations get a distinct @ letter.
• Identification is a heuristic. A file with no distinctive token is Merlin. --syntax or a syntax: marker is the reliable override. START alone does not select ORCA/M.
• Native high-bit Merlin text is Merlin even if later lines look like another dialect, unless a marker in the first 40 lines already matched.
• Empty LONGA / LONGI selects 8-bit. Only ON, YES, and 1 select 16-bit.
• LISA has no macros and no algebraic expressions.
• Merlin 32 is not a second encoder. It is Merlin 16+ with a different syntax name, plus GEQU / GEQ as equates.