Newsgroups: comp.sys.apple2.programmer Path: news.uiowa.edu!uunet!news.sprintlink.net!howland.reston.ans.net!news.starnet.net!wupost!waikato!comp.vuw.ac.nz!actrix.gen.nz!dempson From: dempson@atlantis.actrix.gen.nz (David Empson) Subject: Re: Merlin 16 Message-ID: Sender: news@actrix.gen.nz (News Administrator) Organization: Actrix Information Exchange Date: Fri, 14 Apr 1995 07:37:34 GMT References: X-Nntp-Posting-Host: atlantis.actrix.gen.nz Lines: 442 Here is a summary of Merlin source file rules and assembler directives. One detail I haven't covered below is the actual formatting of the source files. All characters in the source file are high ASCII (bit 7 set), except for some spaces. "Tabbing" spaces (separating the label, mnemonic, operand and comment columns) are in high ASCII, text spaces (in comments or quoted strings) are in low ASCII. Tabbing spaces may appear after the first three, but should be treated as normal spaces. Merlin Assembler Notes by David Empson (dempson@actrix.gen.nz) Here are some notes on Merlin/Big Mac source file syntax, for those who do not have the program and are trying to understand or convert a source file. I would not suggest relying on this information if you are WRITING a Merlin source file - use the manual. This is only a brief summary and I have skipped many details that are only relevant when writing programs with Merlin. If you find any errors in this information, please let me know. Comments Any line starting with * or ; is a comment. Labels Merlin supports three types of labels. Global labels are most common - any label starting with a character other than ] or : is a global label (e.g. START) A local label begins with a colon (e.g. :LOOP). A local label may be redefined multiple times within a source file, but may only be defined once between any pair of global labels. Local labels are commonly used for loops and branch destinations where the name is not particularly important. A variable begins with a left square-bracket (e.g. ]LOOP). A variable may be redefined as often as desired. Any reference to a variable will be to the most recent definition (you cannot have a forward reference to a variable). Numbers Merlin supports decimal, hexidecimal ($ prefix) and binary (% prefix). ASCII characters An ASCII character may be used in an operand (e.g. LDA #'A') by enclosing it in single or double quotes. Single quotes specify low ASCII ($00-$7F), double quotes specify high ASCII ($80-$FF). Expressions Merlin evaluates expressions left-to-right. The operators are +, -, / (integer divide), *, ! (exclusive OR), . (OR), & (AND). The * symbol represents the current location counter. Parentheses may not be used, except to indicate indirect addressing. Immediate Data As usual, the # symbol forces immediate addressing (constant instead of memory lookup). Immediate data might be 8-bit or 16-bit when writing 65802/65816 programs. Different components of the expression value may be accessed as follows: Reference 8-bit 16-bit #expression low byte low word (bytes 0 and 1) #expression high byte high word (bytes 1 and 2) #^expression bank byte bank word (bytes 2 and 3) e.g. LDA #$123456 LDA #$56 LDA #$3456 LDA #<$123456 LDA #$56 LDA #$3456 LDA #>$123456 LDA #$34 LDA #$1234 LDA #^$123456 LDA #$12 LDA #$0012 Forced Addressing Modes When writing 65816 code, it is sometimes necessary to force absolute or absolute long addressing mode for an instruction. expression Absolute or direct, depending on value >expression Absolute Long |expression Absolute e.g LDA $123456 absolute (LDA $3456) LDA >$123456 absolute long (LDA $123456) LDA $04 direct LDA |$04 absolute (LDA $0004) There are also special mnemonics for forced long and forced absolute mode instructions, using an L or : suffix, e.g. LDAL expr LDA forced long LDA: expr LDA forced absolute Assembler Directives I think I have all of the directives. There may be some obscure ones that are missing. label EQU expression label = expression Assign an expression to a label. label EXT EXT label,label,... Define an external label (or labels) to be resolved at link time (used in relocatable source files). label ENT ENT label,label,... Define an entry point (global label or labels) that can be referred to in other files linked to this one. The first form defines the label at the current location counter. The second form specifies that the listed labels are entry points, but they must be defined elsewhere. ENT ON ENT OFF All labels defined between these directives will be entry points. ORG addr Used to specify the absolute address of the following code/data. This directive is not used in relocatable source files (more common with Merlin 16/16+). REL Specifies that a relocatable object file will be created, instead of an absolute binary image. The relocatable file must be linked using the Merlin linker to produce a loadable file. OBJ addr Specifies the address of the object code buffer while assembling. Not used in Merlin 16+. VAR expr;expr;... Set several variables (]1 to ]8). PUT filename Include another source file at this point. Macros may not be defined in a file included with PUT. You may use PUT multiple times to include several files, but a PUT file may not include a second PUT file (i.e. only one level of nesting). USE filename Include another source file at this point. The big difference between USE and PUT is that a USEd file will remain in memory for the rest of the assembly, so it may include macros. You can only have one USE file. SAV filename Usually placed at the end of the file to save the object file. Cannot be used with REL files (you must use DSK), except for Merlin 16+. DSK filename Specify assembly-to-disk, with the specified object file. This directive must be placed at the start of the file. DSK and SAV are not supposed to be used together. TYP expr Set the filetype for the next DSK or SAV. END Optional end of file indicator. Further lines are ignored. DUM expr Start a dummy section at the specified address. Anything between the DUM and DEND will assign values to labels but will not generate object code. This is often used to define a local stack frame or set of direct page variables without having to use explicit EQU statements for each label, allowing easy insertion/deletion. DEND End a dummy section. AST expr CYC special DAT EXP ON/OFF/ONLY LST ON/OFF/RTN LSTDO PAG TTL SKP expr TR ON/OFF/ADR Various listing control directives. (Asterisks, cycle count, date, expand macros, listing, listing false condtional, page break, title, skip lines, truncate multi-byte object code.) ASC 'string' Insert ASCII string into output. As with expressions, single quotes force low ASCII, double quotes force high ASCII. Optional hex bytes may be added after the string, e.g. ASC 'string'00 or ASC 'string',8D00. This also applies to the following string directives, but the hex bytes are not affected by any special functions. DCI 'string' Dextral Character Inverted (I just love that name!), i.e. the same as ASC but the last character has its high bit inverted. INV "string" Inverse string (all characters forced to the range $00-$3F). FLS "string" Flashing string (all characters forced to the range $40-$7F, I think). REV 'string' Reversed string (last character first). STR 'string' String with initial length byte. DA expr,... DW expr,... Insert word(s) into memory. Equivalent to ORCA/M's DC I2'expr,...'. DDB expr,... Insert double bytes (high byte first) into memory. DFB expr,... DB expr,... Insert byte(s) into memory. Equivalent to ORCA/M's DC I1'expr,...'. ADR expr,... Insert three-byte address(es) into memory. Equivalent to DC I3 in ORCA. ADRL expr,... Insert four-byte address(es) into memory. Equivlaent to DC I4 in ORCA. HEX bytestring Insert a string of hex bytes in the output file. DS expr DS expr,value "Define Space" - skip the specified number of bytes, filling with zero or with the specified value. DS \ DS \,value Used in an absolute file to skip to the start of the next page, filling with zero or the specified value. In a REL file, this directive forces the linker to load the next file at the next page boundary. DO expr ELSE FIN Conditional assembly directives. If the expression is nonzero, the code from the DO to the matching ELSE will be assembled (or to the matching FIN if there is no ELSE). If the expression is zero and there is a matching ELSE, the code from the ELSE to the FIN will be assembled. Conditional assembly directives may be nested. IF char,]var ELSE FIN Another form of conditional assembly: if the first character of the variable matches char, then assemble the following code. This is often used in macros. IF MX ELSE FIN Used with Merlin 16/16+ to test the current M and/or X size. An expression may be used on MX. CHK Insert a checksum byte (exclusive-or of all previous bytes). ERR expr Force an error if expression is not zero. ERR \expr Force an error at link time if this file goes past the specified address. label KBD label KBD "prompt" Input a label from the keyboard at assembly time. LUP expression --^ Repeat a sequence of instructions (between the LUP and --^) for the number of times given by the expression. MX expression Set M (accumulator/memory) and X (index) size for following immediate instructions. Merlin automatically tracks REP and SEP instructions, so these directives do not have to be used very often. Expression values are: 0 (16 bit M, 16 bit X), 1 (16 bit M, 8 bit X), 2 or %10 or 10 (8 bit M, 16 bit X), 3 or %11 or 11 (8 bit M, 8 bit X). PAU Pause assembly until a key is pressed. SW Enable Sweet-16 opcodes (Merlin 8 only). XC Set processor type (6502, 65C02 or 65802/65816). The default can be configured, and varies from assembler to assembler. A single XC is used to enable 65C02 mode. Two in a row enable 65802/65816 mode. XC OFF can be used with Merlin 16+ to force 6502 mode. name MAC EOM or <<< Define a macro. Macro arguments end up as variables ]1, ]2, etc. To call up a macro, use any of: PMC name >>> name name PMC name,arg1;arg2;... >>> name,arg1;arg2;... name arg1;arg2;... Merlin 16 also supports ]0, which is the number of arguments provided to the macro. Merlin 16+ has a few new features: ASC, etc. will accept hex data interspersed with ASCII data. INV works differently to handle the alternate character set. ASC accepts an argument of the form #expr, in which case the ASCII representation of the expression is inserted, e.g. ASC #123+4 is the same as ASC '127'. You can also use ASC #'expr or ASC #"expr to force low/high ASCII, and ASC #>expr to force right justification of the number in a five character field with leading spaces. Merlin is case sensitive by default. Merlin 16+ has a CAS SE or CAS IN directive to set this (it can also be configured in the parameter file). STRL 'string' As STR, but uses a length word (i.e. a GS/OS class 1 input string). Expressions support <, =, >, # (not equal). Braces { } may be used in expressions to force evaluation order. The expression within the braces is evaluated in "standard" order for expressions, not left-to-right. FLO 'fp_number' Insert a SANE extended precision floating point number. label EXD EXD label,label,... Defines an external label which is to be accessed using direct mode (not absolute). Note: Merlin 16 and 16+ have a scriptable linker that uses source files which are similar in appearance to assembly source files. I have not covered these files. Merlin 8 uses a specially formatted binary file to specify which relocatable files to link together, and doesn't provide as many options. Merlin 8 can only produce absolute output files (e.g. for running under ProDOS-8), or relocatable files that can be linked to produce an absolute file. Merlin 16 and 16+ can assemble directly to an absolute file, or to a relocatable file. Relocatable files can then be linked using any of several linkers: the absolute linker, which produces absolute files; the GS linker, which produces IIgs Object Module Format files; a large version of the GS linker; or the OMF linker (Merlin 16+ only) which produces an OMF object file (which can linked using the ORCA/Linker). -- David Empson dempson@actrix.gen.nz Snail mail: P.O. Box 27-103, Wellington, New Zealand