ASM8 - Copyright (c) 2001-2022 by Tony Papadimitriou (email: tonyp@acm.org)

Latest Manual Update: February 13, 2022 for ASM8 v12.30

ASM8 is a two-pass absolute macro cross-assembler for the 68HC08 or HCS08 or 9S08 MCU by NXP (originally by Motorola, and later by Freescale).

This tool has been evolving for almost 20 years with new features, and occasional bug fixes, with very few and trivial backward compatibility issues. It is mature enough to cope with the most demanding applications both in terms of size and coding complexity.

There are many sometimes unique features that make writing clean, self-adjusting source code easy. Those make working with assembly language so much more fun for me, at least, than with certain higher level languages.

Most higher level language tools usually come with an ecosystem, a set of built-in libraries for the most mundane tasks a programmer needs. This is something most assembler writers unfortunately do not bother to include with their tools making it harder for newcomers to start using the language, successfully. And, eventually, they escape frustrated into other languages.

Although there’s a lot of code floating on the Net, this is often unreliable, untested, incomplete (fails to assemble out of the box), of little or no practical value, badly formatted and/or unreadable, and written for diverse sometimes unspecified assemblers whose details are not always clear making porting to your own assembler difficult and error prone. Most importantly, all this code, collectively, lacks consistency in coding style, naming and calling conventions, making it that much harder to integrate into your own application without significant rewrites.

I have been trying to change this trend. ASM8 comes with a significant royalty free code base, most of which has been in use in real life applications and proven over time. These libraries (found under the code subdirectory) in ASM8 distribution (freeasm8.zip) are wherever possible re-entrant, self-contained, and include the following:

• A rich set of general-purpose macros
• String functions
• Copy functions
• Internal Flash functions (for the most common MCU variants)
• Self-timed delays (based on user defined bus frequency)
• A special math library that can be used via a single Eval macro with the same ease as when writing math expressions in higher level languages (taking care of all lower level details such as operator precedence, and mixing variables of different sizes)
• A general-purpose print macro that can print a mix of constants, constant or variable strings, math expressions, and pointed strings. Using unified I/O, you only have to define putc macro to tell it where you want its output to go.
• A standalone tiny bootloader that accepts S19 records directly from an SCI (RS-232 or USB) attached terminal, such as PuTTY.

The above can be used as is, or become inspiration for even better ones.

My plans are to continually enrich this library not only with my own code but also code donated by others, hopefully. I urge anyone interested to donate any non-proprietary, well crafted, and tested libraries and/or applications. Please contact me if you have something to offer.

I happen to use ASM8 on a daily basis on a great number of applications and libraries written 100% in assembly language (well over one million lines of code by now).

Three versions are currently available:

• 32-bit Windows (also runs under 64-bit Windows)
• i386 Linux
• DOS with the GO32V2 memory manager extension built-in. It has also been tested under DOSBox v0.73-2 and DOSBox-X 0.83.9 and performs without problems.

See Linux/Win32 version addendum for behavioral differences related to the OS.

Version History

  +------+-------------------------------------------------------------+
  |12.30 |Added option -? for interactive definition of no-operand DEF |
  |12.20 |Added target address for BRCLR/BRSET instructions in listing |
  |12.12 |Removed redundant errors/warnings w/ inherent B[R]SET/B[R]CLR|
  |      |Added LSRHX extra (for dividing HX by two)                   |
  |      |Removed 'UNKNOWN' from unknown-mode instruction errors       |
  |12.11 |BugFix: #SEGMENT with ORG parameter would fail under SpacesOn|
  |12.10 |Added -H option & #[NO]HINTS to show/hide hints (default ON) |
  |12.01 |Minor internal bug fix in relation to PIN pseudo-op          |
  |12.00 |Major new feature release!                                   |
  |      |Added PIN pseudo-op to define port pins and zero-page flags  |
  |      |Added :PIN internal symbol to return last PIN used status    |
  |      |Added BCLR/BSET/BRCLR/BRSET recognition of PIN defined labels|
  |      |BugFix: Larger than 16-bit values are now #EXPORTed correctly|
  |      |BugFix: (since v8.90) size would update in false conditionals|
  |11.95 |Changed some messages from stderr to stdout to be captured   |
  |      |by redirection                                               |
  |11.90 |Allow expression as 1st parm to #EXPORT when alias follows   |
  |11.80 |Added optional 2nd parameter to #EXPORT to generate alias    |
  |11.70 |Changed "Shorter form wasn't used" from warning to hint      |
  |      |Changed "Direct mode wasn't used" from warning to hint       |
  |11.60 |Added -FN non-saveable option to hide line numbers in listing|
  |11.55 |Allowed && in #IF[N]DEF expressions                          |
  |11.51 |BugFix: #IF[N]DEF ignores a plain ! (NOT) in expressions     |
  |11.50 |#IF[N]DEF treats leading optional ! in expressions as NOT    |
  |11.42 |BugFix: Macro parameters no longer expand @@ in labels       |
  |11.41 |BugFix: ELSE checks for !IF as prefix instead of !IF exact   |
  |11.40 |-Dxxx will update same symbol from a previous -Dxxx option   |
  |11.31 |BugFix: 'Attempting global' would incorrectly flag some cases|
  |11.30 |#IFTOS expression may be followed by ,index, e.g.: var@@,sp  |
  |11.20 |#!MEMORY/#!VARIABLE hides warning on undefined expression    |
  |11.12 |Improved ALIGN bugfix about honoring -F= command line option |
  |11.11 |BugFix: ALIGN did not honor -F= command line option          |
  |11.10 |A colon beginning command-line path will be relative to root |
  |11.01 |BugFix: Segment ORG now shows errors in pass one like ORG.   |
  |11.00 |Added :VERSION internal symbol as integer with two decimals. |
  |      |Directives #S19WRITE, #HINT, #MESSAGE, #WARNING, #ERROR, and |
  |      |#FATAL no longer trim the string to write.                   |
  |      |Each segment now has its own ORG offset (possible minor      |
  |      |backward compatibility issues).                              |
  |      |BugFix: ORG with optional S19 expression did not always work |
  |10.00 |Improved S19 overlaps in MMU mode                            |
  |      |Added {...} format modifier (L) for hex8 without $ prefix    |
  |      |Added {...} format modifier (W) for hex4 without $ prefix    |
  |      |Added {...} format modifier (B) for hex2 without $ prefix    |
  | 9.99 |All segments can now be followed by an ORG expression        |
  |      |Added silenced error expression evaluation in ... comments   |
  |      |Changed purely informative harmless warnings to hints        |
  | 9.98 |Added warning under MMU on file-local CALL or global JSR/BSR |
  |      |Added -G, #GCALL, and #LCALL to enable/disable this warning  |
  | 9.97 |Added option -B[asename] to give a different output basename |
  | 9.95 |Improvement: Label may be followed by comment without spaces |
  | 9.94 |Added :MAXTEMP, :MAXTEMP1, :MAXTEMP2 internal variables      |
  | 9.93 |Undefined macro call starting with ! is ignored without error|
  | 9.92 |Added extra mnemonics `ASLH` (alias for `LSLH`), and `ASRH`  |
  | 9.91 |OR condition separator can be either alt-179/0166 or '||'    |
  |      |Made number of warnings and errors a long for huge numbers   |
  | 9.90 |Added :CCYCLES to return current cycles without zeroing them |
  |      |Changed hint 'Found [re]definition of' to '[Re]defined'      |
  | 9.89 |BugFix: procname was affected even inside false conditional  |
  |      |Show 'Found target address' hint macro name with -FX option  |
  | 9.88 |Default: "Free private/commercial use license (not resale)"  |
  |      |BugFix: Changed output to stdout for #ERROR and #WARNING     |
  |      |Changed max command-line -F option targets from 1 to 100     |
  | 9.87 |Improved NoICE map files and also removed proc local symbols |
  |      |DEF without any operand now gives a more informative error   |
  |      |Hint ... shows always and if prefixed with ! only when -D... |
  |      |BugFix: Spaces between #EXPORT arguments were not trimmed    |
  | 9.86 |BugFix: Correct implementation of empty string FCS case      |
  | 9.85 |BugFix: Correct MMU implementation of OS8 extra instruction  |
  |      |Warning 'P&E MAP files may not support more than 127 files'  |
  |      |Added extra mnemonic TSTH (test H) as PSHH/TST 1,SP/PULH     |
  |      |Added ... to mark incomplete sections with optional message  |
  |      |BugFix: Define labels next to MTOP, MDO, MLOOP, and MSUSPEND |
  |      |'Invalid SP offset' is a warning for zero but error for less |
  |      |Remove all macro and proc local symbols from P&E map files   |
  | 9.84 |#HomeDir now also tries _ASM_ and _FOSSIL_ before failing    |
  |      |BugFix: Failure to #Include a file keeps counter unchanged   |
  | 9.83 |CreateMap -MTA does not export byte size for missing labels  |
  |      |Added option -WW to save configuration with license removed  |
  |      |Optimized -U option processing                               |
  |      |Allowed FCS to be an empty string as it creates trailing zero|
  | 9.82 |Evaluate { ... } expressions w/out errors for informational  |
  |      |directives inside macros                                     |
  | 9.81 |Added OS8 extra instruction which does SWI followed by FAR   |
  |      |#![M]EXPORT does not give warning on undefined label         |
  | 9.80 |BugFix: #HOMEDIR first changes to the current file's path    |
  |      |Improvement: #INCLUDE displays normalized path with -FI hint |
  |      |Improvement: Added { ... } expressions in #INCLUDE paths     |
  |      |Improvement: MTRIM error now displays actual problem text    |
  |      |Improvement: Added AIS and AIX out-of-range warnings         |
  | 9.79 |Added #TEMP1 :TEMP1 #TEMP2 :TEMP2 similar to #TEMP :TEMP     |
  |      |#!DROP prevents 'macro not found' warning                    |
  | 9.78 |Enhancement: !MRESUME does not give error                    |
  |      |Enhancement: IF[N]DEF ORs alt-179/0166 separated conditions  |
  |      |Added value display in 'Repeater out of range' message       |
  |      |Added #!UNDEF to prevent 'symbol not found' warning          |
  |      |Enhancement: EXIT accepts alt-179/0166 separated conditions  |
  |      |Changed built-in defaults to -T+ and -C+                     |
  |      |Added :ERRORS and :WARNINGS internal variables               |
  | 9.77 |BugFix: In -X+ mode, ignore * after a push instruction       |
  |      |If '*' in FindSymbol target can be any substring of symbol   |
  |      |BugFix: Error 'invalid binary number' once for same number   |
  | 9.76 |MAP files when ?A or ?F root is present uses relative paths  |
  |      |Absolute path is used when -U option is given                |
  |      |BugFix: RMB first defines label; allows its use in expression|
  |      |Added -FI debugging option to show included filenames        |
  |      |Altered the default segment addresses for more practical use |
  | 9.75 |#FATAL no longer aborts all assemblies, only the current one |
  |      |Allowed Escape to break out of a long repeater loop          |
  |      |BugFix: Added recognition of \, as alias to • in macro calls |
  | 9.74 |Allowed !RMB or !DS to prevent warning about overlap         |
  |      |Added #S19WRITE directive that writes messages to S19 file   |
  |      |Added #S19RESET directive to forget all used S19 addr ranges |
  | 9.73 |Added -FX non-saveable option to enable macro line # display |
  |      |in ERROR, WARNING, MESSAGE and HINT directives (default: Off)|
  |      |-F: option now also displays the related value               |
  |      |-F: option too now honors the newly added -FX option         |
  |      |Help screen shows default -I option as DEFAULT_INCLUDE_PATH  |
  | 9.72 |Added -LLn option to use a non-default label size up to      |
  |      |MAX_LABEL_LENGTH. This option is global and cannot be saved. |
  |      |Added #MAXLABEL directive to specify new max label length.   |
  |      |Added :MAXLABEL internal symbol to get the max label length. |
  |      |#PUSH/#PULL now save/restore the value of :MAXLABEL          |
  |      |#MESSAGE and #HINT now show the macro line when inside macros|
  | 9.71 |REMACRO now keeps previous definition even of special ? macro|
  |      |Improved error precision by referring to exact directive name|
  |      |Updated help screen to add TPX and TXP internal macros       |
  | 9.70 |Added #ENDP, ENDP & :MAXPROC to allow nested proc definitions|
  |      |BugFix: Define ENDP and ENDM labels before processing the    |
  |      |actual directive so that they have local scope.              |
  |      |Added -F= alias to -F: for FindSymbol operation              |
  |      |-FQ no longer masks -F: operation                            |
  |      |Changed max command-line -D symbol definitions from 10 to 100|
  |      |Made 'Assembled' line formatting uniform in all cases        |
  |      |Added TPX and TXP internal macros for TPA/TAP with X register|
  |      |Augmented -F: option when numeric to find 1st use of address |
  | 9.69 |BugFix: #IFDEF processing always false on empty symbol       |
  |      |BugFix: Added error if expression operand is empty string    |
  |      |Added 'Elapsed time' display next to 'files processed'       |
  |      |Added CALL, JSR, and BSR max stack depth checking            |
  |      |Shortened warning message: Missing first operand in ...      |
  |      |Added auto-fitting of 'Assembled' message to screen width    |
  |      |Added :WIDTH internal symbol to return the width of screen   |
  |      |Added warning 'Redundant AIS with zero operand'              |
  |      |Added -FH option to force hidden macros in listings          |
  | 9.68 |Updated help screen to include internal symbols              |
  |      |Improved long name matching                                  |
  |      |Made the default -I option equal to ?2;?1;?a;?f              |
  |      |BugFix: v9.65 case-insensitive compare in Windows            |
  |      |Changed default tabsize to 10 to match proposed coding style |
  |      |BugFix: Only MSET has a #charset special merge option        |
  |      |BugFix: Use platform specific path delimiter in -I option    |
  |      |-FQ+ now also inhibits #HINT directive output                |
  |      |Added default include path in -I option if * is used empty   |
  |      |Added -FE option to convert warnings to errors               |
  |      |Changed default -LC option to No                             |
  | 9.67 |Added command option -F:symbol to find symbol (re)definitions|
  |      |Added #ELSE IFxxx capability                                 |
  |      |Added command option -FW to make free (non-error) warnings   |
  |      |Added #HINT directive (like #MESSAGE but non-maskable)       |
  |      |BugFix: Honored -T option for #MESSAGE directives also       |
  |      |BugFix: -MMU option command-line processing                  |
  | 9.66 |BugFix: Some macro processing occurred even inside false IFs |
  | 9.65 |BugFix: v9.63 path matching was wrong for many cases         |
  | 9.63 |Hide Fossil (?F)/Asm (?A) root dir from listings             |
  |      |Added better examples to -I option in help screen            |
  | 9.62 |Added O (offset) and M (macro) indicator in listing          |
  |      |Added dual address display in listing (actual and offset)    |
  |      |Added ORG second parameter to allow separation of S19 address|
  |      |Added :OFFSET internal symbol to return current offset value |
  |      |Added -FL non-saveable option to ignore #LISTOFF/#NOLIST     |
  |      |Added -FM non-saveable option to ignore #MAPOFF              |
  |      |Added saving/restoring of :OFFSET with #PUSH/#PULL           |
  |      |Added ORG missing 1st parm (*-:offset) when 2nd is present   |
  |      |Allowed return to no offset current location by just "ORG ," |
  |      |Added -F2 non-saveable option to force P&E 16-bit map        |
  |      |Minor correction in help screen                              |
  |      |BugFix: #USES now ignores filename case under Windows        |
  |      |BugFix: Checking ?F and ?A now uses OR logic instead of AND  |
  |      |BugFix: Added ChDir(GetPath(path)) in List() for Linux case  |
  | 9.61 |Enhancement: -I option ?A matches special _asm_ file root    |
  | 9.60 |Improved help screen for better fit in console window        |
  | 9.58 |Added -FQ option to control display of line number display   |
  |      |during assembly. Useful for IDE use.                         |
  |      |BugFix: -E option without +/- now works again                |
  |      |Added extra mnemonics ROLH, RORH, LSLH, and LSRH             |
  |      |Enhancement: -I option ?F matches FOSSIL root                |
  | 9.57 |Internal changes only                                        |
  | 9.56 |Enhancement: ?1 in -I option means main file path            |
  |      |             ?2 in -I option means parent file path          |
  | 9.55 |Enhancement: #MEXPORT now uses remacro instead of macro in   |
  |      |case of multiple exports of the same macro name.             |
  | 9.52 |Enhancement: !BGND does not give warning (BGND does)         |
  | 9.51 |BugFix: PUSH opsize presence suppressed redefinition warning |
  | 9.50 |New INCLUDE search order: as is, parent path, include path   |
  |      |BugFix: IFDEF, IFZ, IF now use PosStr() instead of Pos()     |
  |      |Added multiple -I option directories separated by semi-colon |
  |      |Allowed user editable -I dir list when ? is given as parm    |
  |      |-I '*' is a placeholder for current directory definition     |
  |      |#!IF/#!IFZ/#!IFNZ false w/out warning on undefined expression|
  | 9.45 |Added ExpToStr formats: Fn (space-fill) and Zn (zero-fill)   |
  |      |Added extra mnemonics INCH (increment H) & DECH (decrement H)|
  | 9.43 |Corrected multi-operand pseudo-instructions size calculation |
  |      |Added filename & linenumber display when canceling with ESC  |
  |      |Added :HOUR, :MIN, :SEC for clock time                       |
  | 9.42 |Internal changes only                                        |
  | 9.41 |BugFix: ::LABEL does not give error in pass one              |
  |      |Improved NEXT when no label on left to increment placeholder |
  | 9.40 |Made #SIZE second parm optional with :PC-LABEL as default    |
  | 9.37 |BugFix: ~n[charset]index~ can contain [ and ]                |
  |      |Charset can now also be delimited by " or ` quotes           |
  | 9.36 |BugFix: Added "if MacroRecording then exit" to IF/ELSE/ENDIF |
  | 9.35 |#IFNUM now detects bin & hex as numbers                      |
  | 9.33 |Added ~text,~ and ~,text~ placeholders.                      |
  | 9.32 |BugFix: Added missing size from EXP file symbols             |
  |      |"Macro already defined" message now shows only in pass one   |
  |      |Added "Non-proc symbol redefinition" warning for PSHx        |
  | 9.31 |BugFix in -MTA format when label is blank, size was misspaced|
  | 9.30 |Added size info in -LSS and -MTA output formats              |
  | 9.25 |Internal changes only                                        |
  | 9.23 |BugFix: Added MSTOP 'USER: ' msg. Removed MERROR ExpToStr()  |
  | 9.21 |BugFix relating to $$$ internal conversion in macros         |
  | 9.20 |BugFix: MergeParms now uses LastMacroParm                    |
  | 9.18 |BugFix: v9.05+ did not allow ',' in EQU etc.                 |
  | 9.17 |Internal changes only                                        |
  | 9.15 |MSET # now skips strings and allows quotes & parens in set   |
  | 9.10 |Allowed embedded { ... } expressions in macro calls          |
  | 9.05 |Added ,size option next to EQU/SET/DEF                       |
  |      |Added MSTOP in-macro parameter to display #Error             |
  |      |Added #SPA alias for #SPAUTO directive                       |
  | 9.02 |BugFix: ~n[set]index~ not working for all occurrences        |
  |      |Added ~n'set'index~ alternative                              |
  |      |Added ,size option as 'PSHx NAME,SIZE'                       |
  | 9.00 |BugFix: > and < over 32-bit now do not wrap-around           |
  |      |Added ~n[set]index~ macro parameter placeholder              |
  |      |Added MTRIM macro command                                    |
  | 8.90 |Added #SIZE LABEL,SIZE directive & ::label internal symbol   |
  |      |Added MSET # option to unite all parms into one              |
  |      |Added :SPMAX, #SPAUTO, depth option                          |
  |      |Added MSET #'charset' option                                 |
  |      |Made :SPMAX show maximum stack depth since last :SPLIMIT set |
  |      |Added :SPLIMIT to return the currently effective stack limit |
  |      |Added :NN internal variable to return total macro parm count |
  |      |Minor speedup when using -Q+ option                          |
  | 8.80 |Added placeholder ~[n.p]~ for smart part extraction          |
  | 8.70 |#PROC resets ~procname~ to null                              |
  |      |#AIS without argument resets :AIS counter to zero            |
  | 8.60 |Added MDEL in macros                                         |
  | 8.57 |Added MOV DIR,X+ & MOV X+,DIR instruction adjustment of :TSX |
  | 8.55 |Added :N internal variable (for number of macro parameters)  |
  | 8.50 |BugFix: #MEMORY and #VARIABLE #OFF# did not work correctly   |
  |      |Added "RMB overlap" warning                                  |
  | 8.40 |BugFix: Symbols over 19 chars gave no error on redefinition  |
  | 8.35 |Added ~filename~ ~basename~ ~path~ and ~#text~ placeholders  |
  |      |Fixed bug with range in listing                              |
  |      |Added #OFF# parameter to #MEMORY and #VARIABLE directives    |
  |      |Added ProcName assignment, and ~procname~ placeholder(s)     |
  | 8.31 |Improved code for the AAX internal macro                     |
  | 8.30 |Allowed ALIGN to align only label to the left (if present)   |
  |      |Added internal symbols to get current value of each segment  |
  |      |Fixed bug with labeled ALIGN with zero                       |
  | 8.21 |Fixed #MEXPORT by adding a new FindMacro in ASMACROS.PAS     |
  | 8.20 |Added #REMACRO to allow renaming to an existing macro name   |
  |      |Added ~self~ and ~text~ macro placeholders                   |
  | 8.15 |Added MSUSPEND and MRESUME and fixed :MINDEX recursion       |
  |      |MSTOP (with optional parm #ALL#) stops suspended macros      |
  | 8.11 |Fixed "Used Range" percentage in case of #MEMORY use         |
  |      |Allowed #EXPORT to come before the actual label definitions  |
  | 8.10 |Fixed ALIGN with zero bug                                    |
  | 8.09 |Added macro parm delimiter #PUSH/#PULL protection            |
  | 8.08 |Added REMACRO capability                                     |
  | 8.07 |Added MDO optional initializer expression                    |
  |      |Added :CPU internal symbol                                   |
  |      |Added #IFNUM and #IFNONUM to test a parm for being numeric   |
  | 8.05 |Added MSTOP                                                  |
  |      |Fixed long-standing bug #IFMDEF inside a macro               |
  |      |Allowed first source line to have symbol also used by -D     |
  | 8.04 |@macro or %macro can now start at column one                 |
  | 8.03 |Fixed long-standing bug with #MCF[2] no-@ call               |
  | 8.02 |Added #MCF2 mode                                             |
  | 8.01 |First macro level inherits :TEMP from main                   |
  | 8.00 |Added ;; comment removal from macros                         |
  |      |Added ~macro~ and ~00~ placeholders                          |
  |      |Added -S9 command-line option to disable S9 record           |
  |      |Added #EXPORT directive                                      |
  |      |Added #MEXPORT directive (for exporting macros)              |
  |      |Changed from 'SET' to 'set' in EXP files                     |
  |      |Fixed #MEXPORT to produce raw (fully unprocessed) macro lines|
  |      |#MEXPORT uses preserve defined macro name case               |
  |      |Added END INCLUDE message in #EXIT directive                 |
  |      |Fixed #MEXPORT from within macro when -EXP-                  |
  |      |Fixed some memory leaks related to macro use                 |
  |      |Added :TSX internal variable                                 |
  |      |Added :TEMP as possible label in NEXT, NEXP, SETN [#AIS]     |
  |      |Added ALIGN pseudo-op                                        |
  | 7.90 |Added :LINENO and :MLINENO internal variables                |
  | 7.85 |Added recognition of * and ?* wildcards to #DROP directive   |
  |      |Fixed MREQ with message to show correct message              |
  | 7.83 |Added :LABEL to return length of ~label~                     |
  | 7.82 |Added -FD command-line option for fixed date in internal vars|
  | 7.81 |Fixed #EXIT to restore conditional file level                |
  | 7.80 |Added #RENAME to rename a macro                              |
  | 7.75 |Allowed @@ to #@Macro #Macro and #MCF for nested calls       |
  | 7.72 |Allowed label next to MEXIT, etc.                            |
  | 7.71 |Internal changes only                                        |
  | 7.70 |Added #TEMP and :TEMP                                        |
  |      |Non-macro :TEMP keeps its pre-macro value                    |
  |      |Added == for IFPARM case-sensitive comparison                |
  | 7.60 |Added MDO MLOOP :MLOOP :MEXIT MTOP/MLOOP limits              |
  | 7.50 |Added :ANRTS & :ANRTC internal variables                     |
  |      |Added #EXIT directive to stop #INCLUDE file at that point    |
  |      |Added #USES#USING directives to #INCLUDE if not-yet included |
  | 7.40 |Added MERROR (combines #Error with mexit) for macros         |
  |      |Added MSTR to turn non-string macro parm into string         |
  | 7.30 |Added #IFB/#IFNB aliases for #IFNOPARM/#IFPARM, respectively |
  |      |Added MREQ for required macro parameters                     |
  | 7.21 |Internal changes only                                        |
  | 7.20 |Added DEF which does EQU if not already defined              |
  |      |BugFix: Command-line symbol definitions re-set for PASS2     |
  | 7.11 |Internal changes only                                        |
  | 7.10 |Added :PC and :PPC (#PPC)                                    |
  | 7.02 |Added :OCYCLES to return the previous (Old) #Cycles          |
  |      |MSWAP now silently ignores swapping with self                |
  | 7.01 |BugFix: Corrected cleanup of file-local macros on file change|
  | 7.00 |Added recursive macros and #MLimit to set max depth          |
  |      |Added MSET to change the text of a macro parm                |
  |      |:LOOP is reset when calling self with @@                     |
  |      |Added MDEF (similar to MSET but only #IFNOPARM)              |
  |      |Added MSWAP (swaps any two macro parameters)                 |
  | 6.90 |Added #IFSTR/#IFNOSTR conditional directives                 |
  | 6.80 |Allowed upto 125 total INCLUDE files                         |
  |      |Added #PROC, PROC and :PROC for local labels                 |
  |      |Allowed { ... } expression in labels even outside of macros  |
  |      |Removed @@ local labels from SYM file                        |
  |      |Added "Number of [#]PROCs used" message in LST               |
  | 6.70 |Internal changes only                                        |
  | 6.61 |Ability to hide all macros macros & their definitions        |
  | 6.60 |Added ability to hide all macro keywords                     |
  |      |{ ... } expressions can now be nested                        |
  | 6.50 |Internal changes only                                        |
  | 6.45 |Added :DOW internal variable (0=Sunday)                      |
  | 6.45 |Added MTOP                                                   |
  | 6.42 |Did not allow negatives in ReadParm and ~n.s.l~              |
  | 6.41 |Length :0 now works correctly                                |
  | 6.40 |Added "Line may have been truncated" warning                 |
  | 6.30 |Added :0 to :9 for getting length of macro parm              |
  | 6.21 |BugFix: #HOMEDIR not saving home between passes              |
  |      |Added #HOMEDIR without parms to restore original home        |
  | 6.20 |Do not show #ENDIFs with -LC-                                |
  | 6.10 |Improvement: No trailing commas when reading macro lines     |
  |      |Added: ~@~ and ~@@~ macro placeholders                       |
  | 6.03 |BugFix: Improved v6.02 EQU & SET BugFix                      |
  | 6.02 |BugFix regarding EQU & SET when used with repeaters          |
  | 6.01 |Internal changes only                                        |
  | 6.00 |Allowed { ... } expression> anywhere in macro text           |
  |      |BugFix: Other macro called right after #DROP                 |
  |      |Added reset macro counters capability by calling %macro      |
  | 5.90 |Added :INDEX for use from inside macros                      |
  | 5.85 |:MACROLOOP -> :MACRONEST, added :MACROLOOP                   |
  | 5.80 |Added :TOTALMACROCALLS, :MACROLOOP, :MACROINDEX              |
  | 5.71 |"Bug" fix. spxSP no longer updated with #SPAUTO              |
  | 5.70 |Added implicit "label set ::" next to any push instruction   |
  |      |BugFix for space parm delimiter self-replacing               |
  | 5.60 |Added #Cycles to (re)set :CYCLES to any value                |
  | 5.55 |Added \, and • to re-use last macro delimiter                |
  | 5.51 |Added 'Nested macro definition not allowed'                  |
  | 5.50 |Internal changes only                                        |
  | 5.40 |Added #MCF (Macros Come First) & MacroFirst                  |
  | 5.32 |Fixed misleading MMU "Attempt to jump to page"               |
  | 5.31 |Bug fix for ~#~ processing                                   |
  | 5.30 |Added ~n,~ and ~,n~ macro placeholders                       |
  |      |#PARMS SPACE makes separator a space                         |
  | 5.25 |Added #IFSPAUTO conditional directive                        |
  | 5.21 |Disallowed comments in #IFPARM/#IFNOPARM                     |
  | 5.20 |Added ~label~ macro placeholder                              |
  | 5.12 |Fixed recognition of comma in non-@ macros                   |
  | 5.11 |Internal changes only                                        |
  | 5.10 |Added #IFPARM with comma [,] for comparing two strings       |
  | 5.02 |Internal changes only                                        |
  | 5.01 |Bug fix in ',SPX' case with zero :SP                         |
  | 5.00 |Macro calling without the @ symbol >MacroAssume              |
  |      |Added warning "Macro repeater ignored"                       |
  |      |Replaced #NOMACRO with #@MACRO                               |
  | 4.90 |Internal changes only                                        |
  | 4.81 |Internal changes only                                        |
  | 4.80 |Automatically drop special ad-hoc '?' macro                  |
  | 4.70 |Added mapping for macro lines and #TRACEON/#TRACEOFF         |
  | 4.60 |Added optional macro parm for single call                    |
  | 4.52 |Fixed nested #IF(s) in macros not counted right              |
  | 4.51 |Internal changes only                                        |
  | 4.50 |Internal changes only                                        |
  | 4.40 |Internal changes only                                        |
  | 4.30 |Made IFPARM/IFNOPARM available outside MACROS                |
  | 4.20 |Added IFMDEF/IFNOMDEF for check macro presence               |
  | 4.10 |Added #MLISTON/#MLISTOFF & #MLIST/#NOMLIST                   |
  | 4.01 |Fixed local macro recognition                                |
  | 4.00 |Added MEXIT                                                  |
  | 4.00B|Added macro support (BETA due to significant code changes)   |
  |      |Added [n] display for macro errors/warnings                  |
  |      |Added IFPARM/IFNOPARM, #DROP, #PARMS                         |
  | 3.50 |Made Assembled display not truncate long names               |
  | 3.40 |-X option (dis-)allows simulated index modes                 |
  |      |Added warning 'Invalid SP offset'                            |
  | 3.33 |Added AIX instruction adjustment of TSX-based SP             |
  | 3.30 |Added ,SPX indexing mode to use TSX-based SP                 |
  | 3.20 |Added :SPX to return :SP-1 for #X :SPX                       |
  | 3.15 |Negative AIS instructions reset the :AIS symbol              |
  | 3.12 |:AIS is set to the #SP/#SP1/#SPAUTO offset                   |
  | 3.11 |Added :AIS internal symbol and #AIS directive                |
  |      |Added warning: Stack structure requires "AIS #?"             |
  | 3.10 |Added stdout for displaying to the console                   |
  | 3.03 |Added warning for SP symbols outside #SP[AUTO]               |
  | 3.02 |#iftos corrected to match v3.01 change                       |
  | 3.01 |Symbol :: is alias for 0-:SP when in #SP1 mode               |
  | 3.00 |Added #PSP to update PSP value with current :SP              |
  |      |Fixed #SPADD to not cancel SP1 mode                          |
  |      |Added #HOMEDIR directive                                     |
  |      |Added NEGHX extra mnemonic                                   |
  |      |Added #iftos directive [(expr + :SP) = 1]                    |
  | 2.50 |Added #X for X-indexed offset                                |
  |      |Added #SPCHECK and related code                              |
  |      |#SPAUTO with parameter #OFF# turns off SPAUTO                |
  |      |#PUSH/#PULL now save/restore #SPCHECK value                  |
  |      |Added :SPCHECK internal symbol returns the #SPCHECK value    |
  |      |Added :PSP internal symbol returns (:SP-:SPCHECK)            |
  |      |Added ,PSP (Preserved SP) indexed mode for +:psp             |
  |      |Help screen beautified and made more complete                |
  |      |Added :: as alias for 1-:SP for easy definition              |
  |      |Added :SPFREE (:PSP) to return :SP-:SPCHECK                  |
  |      |Added NEGXA extra mnemonic                                   |
  |      |Added XGAH and XGHX extra mnemonics                          |
  |      |Added #SPADD which adjusts :SP by a signed value             |
  |      |Added SEXA extra mnemonic, sign-extends A into XA            |
  | 2.40 |Added automatic SP adjustments for Push / Pull               |
  |      |Added directives #SPAUTO (cancel with #SP)                   |
  | 2.30 |Added PSHXA and PULXA internal macros                        |
  |      |Removed :1 alias for :SP1                                    |
  | 2.22 |Fixed OptRtsXX warning for CALL/RTC cases                    |
  | 2.20 |Change SP offset processing and fixed rare bug               |
  | 2.12 |Added ,ASP (Absolute SP) indexed mode does -:SP1             |
  |      |Added ,LSP (Local SP) indexed mode does -:SP                 |
  | 2.11 |Bug fix in #SP/#SP1 processing - word -> long                |
  | 2.10 |Added :1 internal symbol (alias for :SP1) ***REMOVED LATER***|
  | 2.02 |Added :SP1 internal symbol to return the zero-based SP offset|
  | 2.01 |Added #SP exp to offset SP indexed instructions              |
  |      |Added :SP internal symbol to return the one-based SP offset  |
  | 2.00 |Added #SP1 and #SP directives                                |
  |      |Added ABS (Absolute Value of A) internal macro               |
  | 1.80 |Added :AB (AddressBytes) internal symbol                     |
  |      |#PUSH and #PULL save and restore CurrentSeg                  |
  |      |Fixed cross-page jumping warnings                            |
  |      |Added :PAGE_START & :PAGE_END internal symbols               |
  | 1.70 |Made Date an atomic operation for consistency                |
  |      |Added #UNDEF and made EXP use 'SET', not 'EQU'               |
  |      |EXP only exports during PASS1                                |
  |      |Allowed strings up to long in EQUs                           |
  |      |Division by zero in { ... } expressions shows ???            |
  |      |(S)igned { ... } expressions auto-adjust by size             |
  |      |Added { ... } formats up to (9) for 32-bit                   |
  |      |#WARN and #NOWARN control warnings from code                 |
  | 1.60 |Corrected error message "Symbol does not start"              |
  | 1.59 |Added :CYCLES for counting cycles                            |
  | 1.58 |Added option -U to define output directory                   |
  | 1.57 |Conditionals IF, IFZ, IFNZ are 32-bit correct                |
  | 1.56 |Conditional directives now use full 32-bit word              |
  | 1.55 |Operator ]] returns the high word, [[ low word               |
  | 1.54 |Added CRC at end of listing file                             |
  | 1.53 |Fixed LONG bug                                               |
  | 1.52 |Added LONG for 32-bit constant data                          |
  |      |Added 32-bit label definitions                               |
  | 1.51 |Added PUSH and PULL extras                                   |
  | 1.50 |Internal changes only                                        |
  | 1.49 |BugFix: SET was updating label sequence                      |
  | 1.48 |Made TP option usable with console output                    |
  | 1.47 |Made TP option usable with common ERR files                  |
  | 1.46 |Added RESET extra instruction for forcing reset              |
  | 1.45 |Internal changes only                                        |
  | 1.44 |#PULL now flushes S19 if forceS2 state changes               |
  | 1.43 |"MMU is disabled" converted to Error                         |
  | 1.42 |Added #S2 (-S2+) and #S1 (-S2-) directives                   |
  | 1.41 |Made S2 appear only in MMU or ForceS2 mode                   |
  | 1.40 |Operator [[ returns the low word                             |
  |      |Allowed 24-bit constant strings                              |
  |      |Made S19CRC use linear address when -Z enabled               |
  | 1.39 |CRC and S19CRC counters initialized for pass 2               |
  | 1.38 |Added S2/S8, CALL/RTC, #MMU/NOMMU, FAR                       |
  |      |Added option -MMU[+/-]                                       |
  |      |Added { ... } formats (5) and (6) for 24-bit                 |
  |      |Added option -S2 for forcing S2 production                   |
  |      |Added option -Z[+/-] for linear addresses S19                |
  |      |Added #IFMMU and #IFNOMMU                                    |
  |      |When MMU is off, CALL -> JSR and RTC -> RTC &                |
  |      |-J option and #JUMP #CALL to control the same                |
  | 1.37 |Added S19CRC and made it display in summary                  |
  | 1.36 |Added error for unresolved { ... } expression                |
  | 1.35 |Added { ... } expression recognition in EQU strings          |
  | 1.34 |Added CRC display in completion status line                  |
  | 1.33 |#CRC shows error for undefined symbols                       |
  | 1.32 |Added #CRC directive and :CRC internal symbol                |
  | 1.31 |Added SETN pseudo-op                                         |
  | 1.30 |Improved #VARIABLE violation message                         |
  | 1.29 |Q option also disables #Message output                       |
  | 1.28 |Added NEXP pseudo-op                                         |
  | 1.27 |NEXT expression evaluates as Integer. Added show error.      |
  | 1.26 |Added optional expression to NEXT                            |
  | 1.25 |Added system variables YEAR, MONTH, and DATE                 |
  | 1.24 |Allowed repeaters to be expressions                          |
  | 1.23 |Added #VARIABLE directive                                    |
  | 1.22 |Added NEXT pseudo-op                                         |
  | 1.21 |Added { ... } format modifiers (1) thru (4)                  |
  | 1.20 |Change default format for embedded expressions               |
  | 1.19 |Added expression evaluation in strings                       |
  | 1.18 |Added expression evaluation in #Message etc                  |
  | 1.17 |Added SET pseudo-instruction                                 |
  | 1.16 |Added PSHCC and PULCC extra instructions                     |
  | 1.15 |Optimized AAX for 1 less byte, 2 less cycles                 |
  | 1.14 |Fixed bug with remaining Integer() parts                     |
  | 1.13 |Internal changes only                                        |
  | 1.12 |Added extra mnemonic XGAX (exchange A with X)                |
  | 1.11 |Optimized LSLHX from 8/14 to 6/10 bytes/cycles               |
  | 1.10 |Made #PUSH/#PULL save/restore #HCSON/#HCSOFF                 |
  | 1.09 |Fixed cycle counts and DBNZ ,x mode recognition              |
  |      |Fixed bugs with EOR                                          |
  | 1.08 |Use shorter indexed modes when possible                      |
  | 1.07 |Fixed bug with STHX ??,sp code                               |
  | 1.06 |Added support for HCS08 (#HCSON/OFF #IF[N]HCS)               |
  | 1.05 |Fixed cycle counts for several instructions                  |
  | 1.04 |Added THX and TXH extras                                     |
  |      |Added LSLHX extra (for multiplying HX by two)                |
  |      |Added ADDHX #nnnn extra                                      |
  | 1.03 |Added errorlevel 5 for "no files found"                      |
  | 1.02 |Added AAX extra to add A to H:X                              |
  |      |Added INX and DEX extras for INCX and DECX                   |
  | 1.01 |Added = as synonym to EQU                                    |
  |      |Changed VECTORS segment default to $FFDE                     |
  | 1.00 |Original (based on ASM5 v1.04) Started: 2001-07-06           |
  +------+-------------------------------------------------------------+

Reference Guide

Command-Line Syntax and Options

ASM8 [-option [...]] [[@][:]filespec [...]] [>errfile]

• option(s) may appear before, in between or after filespec(s).

• option(s) apply to all files assembled, regardless of command line placement.

• Text file(s) containing list(s) of files to be processed may be specified by naming the text file on the command line, prefixed with a @ character. These text files may not contain command line options.

• filespec(s) may include wildcard characters (?,*). Wildcards are not allowed in filespec(s) that are prefixed with a @ but are allowed in filespecs inside @files.

• If the filespec is a relative path and begins with a colon (:) then it will be relative to the _asm_ or Fossil root (in that order).

• If the file extension for a source filespec is omitted, the extension .ASM is assumed (see description of the -R.ext option below).

• Assembler errors may be redirected to errfile using standard DOS output redirection syntax. This capability may be used in conjunction with, or as an alternative to the -E+ option.

• Any label can hold a value that is 32-bit long. Even though the CPU cannot understand numbers larger than 16-bit for data or addressing (MMU not withstanding), the ability to have 32-bit labels allows keeping constants that are larger than 16-bit for use in later constant calculations. Decimal numbers are signed; the largest number is +/-2147483647. Hex or binary numbers are unsigned and can go up to the full 32-bit value (2³²-1). For example, a symbol holding the crystal frequency of operation can be expressed with Hz detail to be used later to derive other constant values (such as bps rates or cycle-based delays).

• The assembler will set the DOS ERRORLEVEL variable when it terminates as indicated:

  • 0 - No error, assembly of last file was successful
  • 1 - System error (hardware I/O failure, out of disk space, etc.), or -W option failure
  • 2 - Error(s) generated (or Escape pressed) during assembly of last file
  • 3 - Warning(s) generated during assembly of last file
  • 4 - Assembler was not started (help screen displayed, -W option used with success)
  • 5 - The assembler did not find any files to assemble
    
    

Source File Pseudo-Instructions

Assembler Directives

• All processing directives must be prefixed with a $ or # character. ASM8 will recognize either character as the start of a processing directive.

• If a directive has a corresponding command-line option, the directive in the source file will override the command line option at the point in which the source file directive is encountered.

• [text] will be trimmed of duplicate spaces. To have more than one consecutive spaces display, use the Alt-255 character, as many times as needed.
  

                    #spauto

Subroutine          ais       #-4                 ;local data

?                   set       ::
?Parm1              setn      ?,2
?Parm2              setn      ?,2

                    #ais      ?                   ;check frame definition

a                   macro
                    #Message  Inside original ~0~
                    endm

a                   remacro
                    #Message  Inside inner ~0~
                    #rename   ~0~,_{:totalmacrocalls}_
                    @@a
                    #remacro  ~0~,~self~
                    #Message  Inside inner ~0~
                    endm

a                   remacro
                    #Message  Inside outer ~0~
                    #rename   ~0~,_{:totalmacrocalls}_
                    @@a
                    #remacro  ~0~,~self~
                    #Message  Inside outer ~0~
                    endm

                    @a
                    #Message  -----------------------------
                    @a

Macros

• Macros must be defined anytime before they are invoked, and they can be invoked until the end of the current assembly (for global macros), end of current file (for local macros), or until a #DROP directive undefines them, in either global or local case.

• The body of macros is placed between MACRO and ENDM keywords, and it can contain any text. All that text is associated with the specified MacroName, as is. Normal semi-colon beginning comments are copied also. If you want comments to appear only in the macro definition but not in each later expansion of the macro, use double semi-colon (;;) for those comments to cause them not to be saved along with the macro.

• By default, macros are invoked using the @MacroName[,parm separator] syntax (see #MACRO, #@MACRO, #MCF, and #MCF2 directives). Note: You can also use the %macro call syntax (i.e., % prefix, instead of @) to force all macro counters (:MINDEX, :INDEX, :LOOP), except for :MACRONEST, for the specific macro to reset, as if you had dropped and recreated the macro.

• A possibly undefined macro can be called by prefixing the macro name with ! Example: @!macro will call macro only if it is defined. It is equivalent to the sequence:
  #ifmdef macro
@macro
#endif

• During invocation, the macro name may be followed by a comma and any non-alphanumeric single character (if more characters found, only the first matters). If this parameter override option is present, then the character right after the comma will act as a one-time parameter delimiter (just for this macro call. The #PARMS defined delimiter will not be affected.) If the character is a space, it does not require yet another space as field separator between macro name and parameters.

• The macro may refer to yet undefined labels or macros, as the code or definitions inside it are not truly parsed until the macro is actually used, if at all.

• The macro is expanded on a line-by-line basis. Each line in the macro body (the text between the MACRO and ENDM keywords), is expanded and then assembled, before the next line of the macro body is fetched.

• Conditionals used inside macros are always local to the current macro invocation, i.e., you cannot open a condition (like #IFDEF) inside a macro and then close it (#ENDIF) outside the macro.

• Local macro names start with the ? symbol (like it is done with normal file-local labels).

• The special local macro named ? (just a single question-mark) is to be used ad-hoc. This one special macro name is automatically dropped (without warning) at each new redefinition. It’s useful for quickly defining a temporary macro to be used immediately afterwards, and considered discarded later. For example, an instruction (or series of instructions) with a complex operand expression can be embedded inside a ? local macro using as parameter the variable part of the expression. This can often make your code more readable (and, editable more easily.)

• Parameters are passed during invocation in the operand field separated by commas (or whatever delimiter you have defined with the #PARMS directive, or the special one-time parameter separator override.) You can also have the macro decide how parameters are separated (see MSET).

• To use a null parameter, just put two delimiters next to each other (e.g., @MACRO PARM1,,PARM3). Note: This will work for any delimiter except for space; two or more consecutive spaces outside a string, of course are seen by the assembler as one space in the parameter field. Space delimiters can only be used with sequential parameters without gaps in between (which is good for the majority of cases, but not all). If you must know, this is because the assembler trims multiple spaces between fields to locate the operand field. If spaces were allowed to separate null parameters, it would also have to count the spaces from the macro name to the parameter field less one that is required to separate the two fields and possibly less one more that could be used with a “space” parameter override, and since the null parameters could be first in the list of parameters, this would be very confusing, and hard to get it to work correctly (especially since you can’t easily count spaces) while also maintaining the desired code formatting. So, when calling a macro with non-trailing null parameters, make sure the parameter separator is NOT a space (either by default or by override), or you will get incorrect macro expansions (and, depending on what the macro does and how it expands, you may not always get side errors).

• Macro-local labels must include the string $$$ at least once anywhere inside their name (except at the very beginning), e.g. Loop$$$ or Main$$$Loop

• Parameter text replaces placeholders anywhere within the body of the macro (label, operation, operand, comment fields) without regard to context. Parameter placeholders are ~0~ thru ~9~ (where ~0~ is reserved for the macro name itself, and ~1~ thru ~9~ for actual parameters.) You can have more than nine parameters but to access them you’ll have to use the ~n.s.l~ form with default s and l parts, e.g., ~10.~ accesses the 10^th parameter.

• ~Cn~ where n is a number from 0 thru 9 is equivalent to ~{n}.{:loop}.1~

• ~-Cn~ where n is a number from 0 thru 9 is equivalent to ~{n}.{:{n}-:loop+}.1~

• ~cn~ where n is a number from 0 thru 9 is equivalent to ~{n}.{:mloop}.1~

• ~-cn~ where n is a number from 0 thru 9 is equivalent to ~{n}.{:{n}-:mloop+}.1~

• The body of a macro may contain nested embedded expressions (in any field, even comments) of the form {expr}, like one can do with strings, where expr is any valid expression, normally including some parameter placeholder(s). Expressions are evaluated last, after expansion of parameter placeholders but before the ~n.s.l~ type placeholder (described later).

• To accommodate indexed mode instruction operands within any one parameter (provided the macro is called with a non-comma parameter separator), you can use the following variations of the placeholders: ~n,~ and ~,n~ (where n is the number 1 thru 9) and the comma position (either after or before the number) defines whether we want the part before the index (excluding the comma), or the index itself (including the comma), respectively. For example, the instruction lda ~1,~+1~,1~ will expand correctly whether parm ~1~ contains an index or not. (Using the simpler lda ~1~+1 will not expand as intended, when used with indexed operands, as the +1 will follow the index, and not the offset before the index.) If no index is within the parameter, ~n,~ is the same as ~n~ while ~,n~ is null. The assembler will pick anything following a possible comma (the first one) within a parameter as being an index (so you could get creative and use the feature for other purposes also).

• The special placeholder ~#~ returns either a null string or the character # if the first parameter’s (~1~) first character is a # (possibly, indicating immediate mode use). With conditional assembly (e.g., #IFPARM ~#~) one can treat the ~1~ parameter differently, assuming immediate mode.

• Similarly, the placeholder ~#n~ (where n is a number from 1 thru 9, zero also accepted but it is pointless) returns the parameter part after a possible # sign, if one is present. This allows getting an immediate mode type parameter in a form (stripped of the # symbol) that can be used in expressions (for example, in an #IF directive expression). Note: If no # is inside the parameter, ~#n~ is the same as ~n~ alone.

• Since one may often call a macro with a non-comma delimiter (such as when a parameter contains a comma in an indexed operand, e.g. 1,x), a possible chained macro call passing this parameter to another macro, or to self while looping by chaining to itself, must use the exact same parameter delimiter that was used to call the original macro, or else the parameter may not be passed on correctly, or not even as a single parameter. Using the default parameter separator (a comma) from within a macro to call another macro (or self) is problematic in those cases. To solve this problem, two equivalent special placeholders have been introduced. One is the ASCII code 149 [•] (e.g., use the ALT-7 method in the numeric keypad for entry in Win-PCs), and the other is the two-character sequence \, (a backslash followed by a comma) which should be possible to type in any editor. Either of these placeholders will be replaced by the same delimiter as the one used for the most recent macro call (either by default or by override), unless there is a new explicit one-time delimiter override (@macro,char call format).

• The special placeholder ~label~ (case-insensitive) returns the actual text of a label appearing in the label column of the last macro invocation (after expanding possible label embedded {expr}). This can be used with ‘function-like’ macros that need to set a label to a specific value (without having to pass the name of the label as a regular parameter). If no label is used in the same line as the macro invocation, then it returns a null (empty) string. If, however, no label is used with a chained (or nested) macro invocation (a macro invocation occurring from inside a macro) then the text value of ~label~ is not changed from the original macro’s. This way, a macro can chain to itself (for looping), or another macro and still have the ~label~ placeholder expand correctly. Note: The length of the actual text inside ~label~ can be found in the internal variable :label.

• The special placeholder ~macro~ (case-insensitive) returns the name of the top-level macro call (useful when used inside nested or chained macros). For example, if macro A calls macro B, which then calls macro C, then ~macro~ equals A inside all three macros.

• Similarly, the placeholder ~00~ returns the name of the macro calling this macro (i.e. the macro one-level above, or the same macro if calling itself). If at the top-level, ~00~ is the same as ~0~. Useful when combining common functionality macros but need the name of the previous macro calling this one. For example, if macro A calls macro B, which then calls macro C, then ~00~ equals A (when inside A or B) but ~00~ equals B (when inside C).

• The special placeholder ~self~ (case-insensitive) returns the original name of the current macro (useful if you #RENAME a macro from within it and then need to restore the actual name the macro had when entered, using #REMACRO). This allows front-ending any macro with additional functionality.

• The special placeholder ~text~ (case-insensitive) returns the current temporary text parameter of the current macro. This is a temporary placeholder that remembers its macro-unique value across different macro calls, adding extreme flexibility. You can also use it as temporary text workspace when manipulating regular macro parameters. ~text~ can be changed with MSET, MSWAP, MDEF using zero as parameter index. The current length of ~text~ can be found in the internal variable :TEXT

• Similarly, the placeholder ~#text~ (case-insensitive) returns the part after a possible # symbol(if one is present).

• The case-insensitive placeholder ~filename~ returns the current file’s filename including the file extension, while ~basename~ returns the filename without extension, and ~path~ returns the full path with filename and extension. The variant starting with m (for macro) shows the corresponding filename for where the macro definition is located (~mfilename~ etc.), which is not necessarily in the current file.

• The placeholder ~@~ is an alias for the full list of placeholders separated by • (starting from 1). Useful if you want to pass all parameters to another macro without explicitly rewriting them. The sequence produced by ~@~ is: ~1~•~2~•~3~•~4~•~5~•~6~•~7~•~8~•~9~

• The placeholder ~@@~ is an alias for the full list of placeholders separated by • but starting from ~2~. Useful if you want to pass the remaining parameters to the same macro when looping (assuming each loop only processes the first parameter, until that becomes null). The sequence produced by ~@@~ is: ~2~•~3~•~4~•~5~•~6~•~7~•~8~•~9~

• An alternative to the above technique, or if you need to pass more than nine parameters is to first use MSET # from within the calling macro to unite all parameter under ~1~, then call the other macro with just ~1~ as parameter, and finally have the receiving macro split the received parameters to as many places as needed by again using MSET #c where c is the assumed parameter separator.

• Trailing parameter separators (commas by default) and trailing commas due to macro expansion of null parameters are automatically removed. This is particularly useful when writing macros, which replace or enhance single-operand instructions. One can write the macro so that it does not require a parameter separator override during invocation, just so it can recognize a possible indexed operand. Example: LDA ~1~,~2~ will work even if ~2~ is null, because the now ‘dangling’ comma after ~1~ will be automatically removed, preventing an otherwise expected syntax error. Similarly, LDA ~1,~+1~,1~,~2~ will work for the following location pointed to by the expression in parm 1, regardless of the presence of an index in parm 1, parm 2, or at all.

• An alternative to the above method can be achieved (in most cases) by using the ~[n.p]~ format of the parameter placeholder (where n is the parameter number, or the case-insensitive keyword text) to extract the p^th byte of the argument (e.g., if ~1~ contains my_var,sp then ~[1.1]~ will return my_var,sp while ~[1.2]~ will return my_var+1,sp but if ~1~ contains an immediate value such as #$1234 then ~[1.-1]~ will return #$12 while ~[1.-2]~ will return #$34 etc. For a 32-bit example, for parm #$12345678 ~[1.1]~ will return #$12 while ~[1.-1]~ will return #$56. The p number can be any integer (positive or negative) but for immediate mode parameters the sign matters, and it only works up to 32-bit if positive (i.e., 1..4), or up to 16-bit if negative (i.e., -1..-2). For immediate mode only, a number above 4 or below -2 will return #0 since that is the effective value. This ~[n.p]~ placeholder makes it particularly easy to deal in a unified way with any parameter, be it immediate, direct, extended, or indexed mode. Care has to be taken to use a negative p if working with 16-bit immediate mode values, however.

• You can use the ~n[set]i~ format of the parameter placeholder to extract the i^th part of the n^th parameter using the character set [set]. The character set can be given as a string of characters with or without quotes (square brackets, instead). Therefore, quotes can also be part of the character set. Example, ~2[,.]3~ will return the 3rd part of the 2nd parameter, where parts are separated by any instance of comma and dot. (Note: ‘n’ and ‘i’ are optional. If ‘n’ is missing, the value one is assumed. If ‘i’ is missing, the value one is assumed. Care must be taken not to allow both to be missing, if the character set contains a dot because it will then be interpreted as a ~[n.p]~ placeholder, which is processed earlier.) If the character set contains only a single character, then embedded strings will be skipped over, otherwise characters even inside strings will be matched by the characters in the set.

• You can use the ~n.s.l~ format of the parameter placeholder (where n is the parameter number, or the case-insensitive keyword text or label, or a constant string enclosed in quotes, s is the starting position, or a constant string to search for, and l is the needed length, or a constant string to search for but past the s position) to extract only a portion of the text of the corresponding parameter or constant. The first dot is required (to disambiguate from ~n~ type parms) even if nothing follows. The s and l are optional. If s is not entered its value is assumed to be one, so that ~1.~ is the same as ~1~ alone. If l is not entered, its value is the length from s to the end of the parameter (i.e., the remaining string). Note: The assembler forces s and l to always be within the limits of the text length. So, specifying a position past the end of the parameter text will always return the last character. To check for past-of-text, check against the :nnn length internal symbol for the specific parameter (e.g., :1 for parm one). If you need to make n, s, or l the result of an expression you can use {expr} (for example: ~1.{:loop}.2~).

SPECIAL CASE: When inside a string, the expression will be evaluated when the string is processed by the assembler, which is after macro expansion of the various placeholders. This means we have lost our chance to expand this placeholder. But, we can use the \@ instead of quotes for strings inside a macro which contain ~n.s.l~ embedded expressions, and not only those (example: fcc \@~{PARM}.{FROM}.{LENGTH}~\@ to have it expand correctly. Because of the \@ the string does not appear as a string yet, and the expressions can be calculated during macro expansion. This way all expressions become simple constants, and the placeholder can be processed. Finally, the \@ dummy string delimiters are turned into single, double, or back quotes, depending on which one of these three doesn’t appear in the string at all, making the whole thing a proper string.

IMPORTANT COMPATIBILITY ISSUE: A couple or so versions compiled prior to 2010-09-24 23:00 used @@ instead of \@. The @@ was an unfortunate selection of dummy quote delimiter and it had to be replaced with a better one (\@) even though it meant possibly causing problems with existing code. Hopefully, not that many macros utilizing this feature were written in the few days the feature had been available with the problematic delimiter. because it caused syntax errors in certain cases, e.g. if single character string contained the @ char (with or without macro parameter expansion), or labels containing @@ inside their name.

• Order of placeholder expansion is: ~@~, ~@@~, ~label~, ~macro~, ~00~, ~self~, ~text~, ~#~, ~#n~, ~n~ (where n = 0..9, in that order), \,, and •, {expression}, ~[n.p]~, ~n.s.l~, ~n[set]i~, \@string\@, and ~Cn~ variations.
• During macro invocation, any parameter text may contain embedded expressions of the form {<expr>}, like one can do with strings, where is any expression, possibly including some parameter placeholder(s), if already inside a macro. This may be needed in situations where the parameter may be interpreted incorrectly while used inside the macro. For example, if the * (normally used to indicate ‘here’, as in BRA *) is passed as a parameter to be used inside the macro, it may have a different value, depending on where it is used. Passing this parameter as {*} is first ‘expanded’ using the current value, and then passed in the macro as a simple constant. Note: You can also do the same expansion from within the macro, making it worry-free for the user of the macro. For example, one of the first macro lines (i.e., before any PC incrementing code) can change * to {*} (using MSET) if the specific parameter is found to have this text.
• Macros cannot #INCLUDE files, but can ‘chain’ to one.
• Macros cannot define other macros.
• Macro-embedded macros are not supported. (Tip: Simple ‘embedded macros’ can be emulated by using any unused parameters to contain the text of the ‘embedded macro’. The MSET keyword can be used from within the macro to ‘define’ the ‘embedded macro’ in one or more unused parameters, each parameter representing a single line of the ‘embedded macro’ then use just the relevant placeholders wherever you want to expand the ‘embedded macro’.)
• Macros can ‘chain’ to self or other macros with no automatic return. This allows, among other things, for creating loops, making macros very powerful.
• Macros can temporarily invoke other macros, and then return back to continue with the original macro. Use the double @ (@@ or %%) notation when calling a macro from within another macro if you want to return back (as opposed to chain to another macro), regardless of macro mode. The default maximum nesting level is 100 (which should be more than adequate for most cases) but it can be changed to as high as 10,000 with the directive #MLimit, or as low as zero, which disables this capability completely. Note: Prefer using macro chaining over nested macro calling when feasible, or to get a looping effect, as it is more efficient both in terms of memory usage and assembly speed. Tip: To use macros as with some other assemblers, i.e., without having to type @ prefix, and having a default nesting (rather than ‘chaining’) behavior, enable the #MACRO @@ mode (see the relevant section for details) . Macro-chaining will be altogether disabled, however.
• To break out of an accidental endless macro loop, press [ESC] on the command-line.
• Macro labels may be case-sensitive (depending on #CaseOn/Off directives) when defined, but are always case-insensitive when invoked (like normal mnemonic names). Tip: A case-sensitive macro definition is important when using the ~0~, ~00~, and ~macro~ placeholders to have it correctly match a normal label named the same as the macro, under #CaseOn mode.
• Virtually unlimited number of macro definitions (memory permitting.)
• Virtually unlimited size of each macro (memory permitting.)
• Unlimited number of macro invocations (all internal macro counters are 32-bit).

Simple nested example (counts lines of intermediate source code, and issues warning if optional limit is exceeded):

                    org       *

CountLines          macro     [Limit][,Description]
                    mset      2, ~@@~
                    #temp     :lineno+1
                    msuspend
                    #temp     :lineno-:temp
                    #Message  Section~2~ spans {:temp} lines
          #ifnb ~1~
            #if :temp > ~1~
                    #Warning  Too many lines (>{~1~})
            #endif
          #endif
                    endm
; To use:
                    @CountLines ,OUTER
                    nop
                    @CountLines ,INNER
                    nop
                    nop
                    mresume
                    nop
                    mresume

String Expressions and Formatting

Note: [text] in directives and all strings may contain nested expressions enclosed in curly brackets, e.g. {expr}. The expression may not contain spaces (regardless of the -SP option state, or #SPACESON directive. An optional format modifier (case-insensitive) within parentheses after the expression can force the display in the specified format. - (D) for default/decimal, - (H) for hex word or long with leading $, - (B) for hex byte without leading $, - (W) for hex word without leading $, - (L) for hex long without leading $, - (S) for signed decimal, - (1) thru (4) (or, thru (9) for the 32-bit versions) for the corresponding number of decimal places after division by 10ⁿ where n is a number from 1 to 4 (or 9), - (X) for expanded (i.e., both decimal and hex), - (Fn) for space left filled, where n is optional (default is 2) and can range from 1 to 0 (0 meaning 10). - (Zn) for zero left filled, where n is optional (default is 2) and can range from 1 to 0 (0 meaning 10).

If no format modifier is used, (D) is assumed.

Some examples using this feature:

ROM                 equ       $F000
                    #Message  ROM is at {ROM}

displays: ROM is at 61440

Adding a format modifier has the following effect:

                    #Message  ROM is at {ROM(x)}

displays: ROM is at 61440 [$F000]

                    #Message  ROM is at {ROM(d)}

displays: ROM is at 61440

                    #Message  ROM is at {ROM(h)}

displays: ROM is at $F000

                    #Message  ROM is at {ROM(s)}

displays: ROM is at -4096

  #Message Clock: {:year}-{:month(z)}-{:date(z)} {:hour(z)}:{:min(z)}:{:sec(z)}

displays something like: Clock: 2013-11-05 13:00:00

It can also be used in strings, like so:

VERSION             equ       101       ;Firmware version as x.xx
MsgVersion          fcs       'Firmware v{VERSION(2)}',LF

is equivalent to:

MsgVersion          fcs       'Firmware v1.01',LF

but it automatically adjusts the MsgVersion string each time the symbol VERSION changes value. No need to re-adjust all relevant messages manually. The potential uses of this capability are only limited by imagination.

An expression that cannot be evaluated (due to forward references or undefined symbols) will display as three question marks (???) when used in directives, but no error or warning message will be issued. When used in strings, however, errors will be displayed as usual.

To prevent an expression evaluation in directives, enclose the [text] that contains the curly brackets within quotes.

To prevent an expression evaluation in strings, break the string into two so that both curly brackets are not part of the same string, e.g.:

instead of fcc '{Hello}' which tries to evaluate the symbol Hello use:
fcc '{','Hello}'.

Internal symbols

Some special internal symbols are always defined by the assembler. All such symbols begin with a single colon (:) character. Currently, the following internal symbols are defined:

• :: (without a symbol following) returns the current dynamically assigned stack offset. Very useful mostly in #SPAUTO mode so that you can assign labels to stack contents as they are created. (Same as 1-:SP in #SP[AUTO] modes, or 0-:SP if in #SP1 [sub-]mode.) Note: Beginning with v5.70 if any push instruction is followed by a label, that label will be SET to the current :: value (in #ExtraOn mode).

• ::symbol - a double colon followed by any previously defined symbol returns the current ‘size’ for the given symbol. A symbol’s size is determined either automatically (e.g., RMB pseudo-instruction), or manually via the #SIZE directive.

• :SP returns the current offset of the #SP or #SP1 directives. This value is the basis for several other internal symbols.

• :SPLIMIT returns the currently effective value of the #SPAUTO stack depth check option (i.e., the optional 2nd parameter of the #SPAUTO directive.) #PUSH/#PULL save/restore this value.

• :SPMAX returns the maximum used stack depth since the last time :SPLIMIT was explicitly set even if to the same value it already had. You can use this internal variable to find the maximum stack depth for a single routine, a collection of routines (e.g., a whole module), or even your whole application’s. Keep in mind, however, that it only counts stack depth in a linear fashion, i.e., without considering possible subroutine calls, recursion, or other indirect methods of altering the stack, such as the LDHX #STACKTOP / TXS sequence. It stills offers significant insight into your code’s approximate stack requirements.

• :SPX returns :SP-1 when in #SP[AUTO] modes and :SP-0 when in #SP1 [sub-]mode. Useful with #X as in #X :SPX. Alternatively and preferably as it is more readable, you may use the ,SPX simulated indexed mode, which does not depend on the :SPX value, and which is actually X-indexed mode but stack-relative to the most recent TSX instruction, and possible subsequent AIX and MOV X+ instructions. (Note: there are many ways to alter the contents of the HX index register; the assembler does not automatically account for all those possibilities; use #X expr where needed to manually adjust the offset, and use the plain X-indexed mode). This feature provides a very simple way of optimizing any SP-relative instruction to X-relative (by simply appending an X to ,SP making it ,SPX and using TSX anywhere before these instructions. All offsets are automatically adjusted.)

• :TSX is similar to :SPX but, although relative to the most recent TSX instruction, and possible subsequent AIX and MOV X+ instructions (like :SPX), it disregards possible following stack depth changes, unlike :SPX. (Note: there are many ways to alter the contents of the HX index register; the assembler will not automatically account for all those possibilities; use #X expr where needed to manually adjust the offset, and use the plain X-indexed mode).

• :SPCHECK returns the actual offset used with the most recent #SPAUTO directive.

• :SPFREE returns the current stack depth change (same as :SP-:SPCHECK). For example, you may use it with the AIS instruction to free so many bytes of stack. (The symbol :SP alone will not work for this purpose releasing remaining stack bytes unless #SPAUTO is used with a zero offset, while :SPFREE works, regardless of the initial offset.)

• :AIS returns the current stack depth change since and including the last stack-increasing AIS instruction (or #AIS directive when given without any parameters). For example, you may use it with a new [normally, stack-reducing] AIS instruction to free so many bytes of stack. :AIS is updated automatically after each stack-increasing AIS instruction, i.e., a negative AIS instruction with an actual instruction operand of $80 to $FF, losing whatever previous value was in :AIS, and it can be used to free whatever stack bytes remain since the last stack-increasing AIS instruction (used like so: AIS #:AIS). #SP, #SPAUTO, and #SP1 reset the :AIS symbol to zero or the value of the parameter used with the corresponding directive until the next AIS instruction.

• :PSP returns the current stack depth change since the last #PSP directive. For example, you may use it with the AIS instruction to free so many bytes of stack. Unlike :SPFREE which is related to the automatically updated :SPCHECK during any #SPAUTO directive, :PSP is only updated manually with the #PSP directive, and can be used locally (eg., after a subroutine call that passes some parameters on the stack) to free just the number of stack bytes for that specific section of code. Simply, place a #PSP directive right before stacking the subroutine parameters, call the function, and follow with AIS #:PSP to remove the parms.

• :SP1 returns the current offset of the #SP or #SP1 directives (like :SP), but also adds one only if we’re currently in the #SP1 mode. This value is always the true effective offset for both #SP and #SP1 modes.

• :AB returns the number of Address Bytes (useful for stack offsets). It returns 2 for normal mode, or 3 for MMU mode. This can be used primarily to correctly and automatically refer to caller stack regardless of the MMU mode being active or not. It can also be used to allocate storage for pointers and to calculate offsets into a pointer table regardless of mode.

• :X returns the current offset of the #X directive.

• :YEAR returns the year at assembly time (e.g., 2021) Hint: Use :YEAR\100 for two-digit year.

• :MONTH returns the month at assembly time (e.g., 2)

• :DATE returns the date at assembly time (e.g., 26)

• :HOUR returns the hour at assembly time (e.g., 13)

• :MIN returns the minute at assembly time (e.g., 0)

• :SEC returns the second at assembly time (e.g., 0)

• :CPU returns a number representing the CPU type (6808 for older 68HC08, or 908 for newer 9S08)

• :VERSION returns the assembler version as integer with two implied decimal digits.

• :CRC returns the current value of the running user CRC.

• :S19CRC returns the current value of the running S19 CRC.

• :PAGE_START returns the page window’s starting address.

• :PAGE_END returns the page window’s ending address.

• :CYCLES returns the current value of the cycles counter, and then it resets it to zero.

• :CCYCLES returns the current value of the cycles counter (v9.90+).

• :OCYCLES returns the older value of the cycles counter (but does not reset it).

• :TOTALMACROCALLS returns the current value of the total macro invocations. Use it for display, or even to restrict macro use (e.g.,
  
  #IFNZ :TOTALMACROCALLS
#ERROR Macro use not allowed for this application
#ENDIF
  placed at the end of your code).

• :MACRONEST returns the current value of the macro (chain) ‘loop level’ regardless if calling the same, or a different macro (think of it as the ‘nesting level’). A value of zero is returned if used outside any macros. First level is number 1. Each time the top-level macro is called, the number is reset to 1. Each time the same or a different macro is called from within a macro, the number is incremented by 1. The macro (chain) can also initialize itself during, say, count one.

• :MACROLOOP (or simply, :LOOP) is similar to :MACRONEST but it returns the current value of the macro ‘loop level’ only for the current macro. A value of zero is returned if used outside any macros. First level is number 1. Each time the macro is called from outside any macros, or from a different macro, the number is reset to 1. Each time the macro calls itself (by either a chained macro call, or the MTOP directive), the number is incremented by 1. This can be used as an automatic loop counter. The macro can also initialize itself during, say, count one. This differs from :MACRONEST in that chained macro calls will restart this counter for each new macro. This counter is also reset with an explicit %macro syntax call.

• :MEXIT holds the most recent MEXIT defined value. :MEXIT is reset to zero each time a macro is (re)entered, but its value can be changed by MEXIT instructions that specify an explicit expression. This feature can be used to pass back to the higher level any value from inside a (nested) macro (such as success/error status, the result of some computation, etc.) without using any label definitions.

• :MLOOP is similar to :LOOP but it is only affected by the MDO and MLOOP keyword pair. First count is number 1. Each time the MDO keyword is encountered, the number is reset to 1. Each time the MLOOP keyword is encountered, the number is incremented by 1. This can be used as an automatic loop counter. This counter is also reset with an explicit %macro syntax call.

• :MACROINDEX (or :MINDEX) returns the current value of the current macro’s number of invocations. A value of zero is returned if used outside any macros. First call of each macro is number 1. If the specific macro is dropped and re-created, the number is reset (it is, after all, a new macro). An example use is to create different labels at each invocation (not to be confused with automatic $$$ label generation, which assumes values based on :TOTALMACROCALLS and cannot be guaranteed to take sequential values between consecutive calls of the exact same macro since other macros may have increased the counter in between), or instruction offsets (e.g., with the special ad-hoc macro named “?”), etc. This counter is also reset with a %macro syntax call.

• :INDEX returns the next value of the current macro’s internal user index. A value of zero is returned if used outside any macros. First use in each macro is number 1. If the specific macro is dropped and re-created, the number is reset (it is, after all, a new macro). Its use is similar to :MACROINDEX but there is a significant difference. :INDEX is only updated each time it is accessed, regardless of how many times the macro is actually called. So, if used inside a conditional block of code, it will only be incremented when that part is expanded. Note: Because of the auto-increment on access, if you need to use the same value more than once in the same macro invocation, you must first assign the value to some label (or :TEMP), and then use the label, instead. This counter is also reset with a %macro syntax call.

• :0 to :999 return the length of the text of the corresponding macro parameter. You can use it alone or along with the ~n.s.l~ parameter placeholder. This can only be used from within a macro. It is not recognized as valid symbol outside a macro.

• :DOW returns the assembly time day-of-week number, from zero (Sunday) to six (Saturday).

• :PC returns the current program counter (same as *) but can be used even in expressions where the use of * is ambiguous.

• :PPC returns the previously saved program counter (see the #PPC directive). It can be used to get the byte distance between any two points without having to define a symbol just for this. It is also useful inside frequently called macros; for example, to avoid the use of a macro local label definition for simple loops (helps keep the symbol table smaller in larger applications).

• :PROC returns the current value of the internal local symbol counter. See PROC and #PROC.

• :MAXPROC returns the currently maximum value of the internal local symbol counter. See PROC and #PROC.

• :LABEL returns the length of the ~label~ placeholder’s content used inside macros.

• :TEMP, :TEMP1, and :TEMP2 return the current value of each of these internal user-defined assembly-time variables. See the directives #TEMP, #TEMP1, and #TEMP2 for more details.

• :MAXTEMP, :MAXTEMP1, and :MAXTEMP2 return the current maximum value of their respective :TEMP variable. They are reset to zero with #TEMP, #TEMP1, or #TEMP2 directives, respectively. They are preserved with respect to macros the same as with :TEMP variables. When entering a macro, these variables are initialized to the current value of their respective :TEMP variable, and restore their previous value on exiting the macro.

• :TEXT returns the length of the current text of the ~text~ macro parameter only from within macros.

• :LINENO returns the current file line number.

• :MAXLABEL returns the current value of the maximum recognized label length. See -LL command-line option and #MaxLabel directive.

• :MLINENO returns the current macro line number only from within macros.

• :N returns the current macro number of contiguous arguments only from within macros.

• :NN returns the current macro number of all arguments only from within macros. It equals the maximum parameter index even if previous parameters are null.

• :ANRTS returns the address of the most recent RTS instruction (i.e., always points back). It produces an error if an RTS hasn’t appeared already.

• :ANRTC returns the address of the most recent RTC instruction (i.e., always points back). It produces an error if an RTC (MMU mode) or either RTC or RTS (normal mode) hasn’t appeared already.

• :ROM, :RAM, etc. All segment directives have a corresponding internal variable that returns the current value of that segment.

• :OFFSET returns the current S19 addressing offset from the physical address (see ORG).

• :WIDTH returns the current width of the console screen. Useful for formatting user messages.

• :WARNINGS returns the current number of warnings.

• :ERRORS returns the current number of errors.

Notes about :SP and :SP1:

:SP returns the current automatic SP offset (the same for both #SP and #SP1 modes). It will NOT account for the extra ‘plus one’ of the #SP1 mode, however. Use it to adjust the current SP offset manually, or to work with labels that are dependent on the current #SP or #SP1 mode; for example, the current level labels while a one-based or zero-based offset is in effect. The local labels will still need to be in the same (zero or one) base, however. You can also use the simulated indexed mode ,LSP (Local SP) to get the same effect.

:SP1, on the other hand, returns the current automatic SP offset just like :SP but which will be ‘plus one’ if we’re currently in #SP1 mode. This is always the true difference between automatic and actual stack offset, regardless of mode. You may also use the simulated indexed mode ,ASP (Absolute SP) to get the same effect.

For example, use ,ASP (or -:SP1) to cancel out all offsets for dealing with absolute numbers:

                    #sp1      SOME_OFFSET
                    ...
?_a_                equ       1
                    pshx
                    cmpa      1-:sp1,sp           ;absolute offset
                    cmpa      ?_a_-:sp1,sp        ;absolute offset
                    cmpa      ?_a_,asp            ;absolute offset (preferred)
                    pulx

All three CMPA instructions above will compare against the stacked value from the immediately preceding PSHX instruction, regardless if the directive earlier is #SP or #SP1, and regardless of the presence or value of the optional parameter SOME_OFFSET. It is equivalent to cmpa 1,sp when #SP mode is off, and you can use it regardless of the current #SP mode and offset, and even if the #SP directive is never used, use it to lock the offsets (so that possible future #SP or #SP1 automatic offsets in related code will not affect these lines).

This feature is most useful when a section of code is under #SP control (say, because most instructions refer to the parent routine’s stack frame, and coding becomes simpler and more readable under #SP control) but you temporarily want to access local stack without any automatic offsets. That way, you don’t have to turn off #SP or #SP1 mode just for one instruction, or so.

To switch from zero-based label [or numeric] offsets to one-based (normal) stack offsets, without changing the current stack depth (automatic SP offset), you must do this:

                    #sp       :sp

Similarly, to switch back to zero-based offsets without changing the current automatic SP offset (current stack depth), you must do this:

                    #sp1      :sp

You can also use the :SP internal symbol to adjust X-indexed offsets after a TSX to refer to higher stack levels (say, a parent routine). For example:

MyOffset            equ       0                   ;zero-based offset

                    ais       #-1                 ;allocate temp space
                    ...
                    tsx
                    sta       MyOffset,x          ;save to local stack
                    bsr       Sub
                    ...

;*******************************************************************************

                    #sp1      2                   ;account for RTS (zero-based)

Sub                 proc
                    tsx
                    lda       MyOffset,sp         ;gets A from parent stack
                    lda       MyOffset+:sp,x      ;(equivalent)
                    lda       MyOffset,spx        ;(equivalent, preferred)

Examine the following assembler listing to see the corresponding produced offsets for each case.

 1      0000         ?    equ       0
 2
 3      F600              org       *
 4
 5                       ;#sp                 ; default mode, no offsets
 6
 7 F600:9EE6 01 [ 4]      lda       1-:sp,sp  ; SP/SP1 relative offset
 8 F603:9EE6 01 [ 4]      lda       1,lsp     ; SP/SP1 relative offset
 9 F606:9EE6 01 [ 4]      lda       1-:sp1,sp ; absolute offset
10 F609:9EE6 01 [ 4]      lda       1,asp     ; absolute offset
11 F60C:9EE6 00 [ 4]      lda       ?,sp
12
13                        #sp1                ; zero-based offset mode
14
15 F60F:9EE6 02 [ 4]      lda       1-:sp,sp  ; SP/SP1 relative offset
16 F612:9EE6 02 [ 4]      lda       1,lsp     ; SP/SP1 relative offset
17 F615:9EE6 01 [ 4]      lda       1-:sp1,sp ; absolute offset
18 F618:9EE6 01 [ 4]      lda       1,asp     ; absolute offset
19 F61B:9EE6 01 [ 4]      lda       ?,sp
20
21                        #sp       10        ; one-based plus 10
22
23 F61E:9EE6 01 [ 4]      lda       1-:sp,sp  ; SP/SP1 relative offset
24 F621:9EE6 01 [ 4]      lda       1,lsp     ; SP/SP1 relative offset
25 F624:9EE6 01 [ 4]      lda       1-:sp1,sp ; absolute offset
26 F627:9EE6 01 [ 4]      lda       1,asp     ; absolute offset
27 F62A:9EE6 0A [ 4]      lda       ?,sp
28
29                        #sp1      :sp       ; zero-based plus :SP (10)
30
31 F62D:9EE6 02 [ 4]      lda       1-:sp,sp  ; SP/SP1 relative offset
32 F630:9EE6 02 [ 4]      lda       1,lsp     ; SP/SP1 relative offset
33 F633:9EE6 01 [ 4]      lda       1-:sp1,sp ; absolute offset
34 F636:9EE6 01 [ 4]      lda       1,asp     ; absolute offset
35 F639:9EE6 0B [ 4]      lda       ?,sp

Notes about :AIS:

:AIS returns the number of stack bytes still allocated since the most recent stack-increasing AIS instruction (normally useful only in #SP[AUTO] modes).

Example usage:

                    #spauto                       ;auto mode and zero offset

                    push                          ;protect all registers

                    ais       #-7                 ;(negative AIS marks current :SP)
                    ...
                    ais       #2                  ;de-allocate some locals (no marking)
                    ...
                    pula                          ;de-allocate some locals (no marking)
                    ...
                    ais       #:ais               ;deallocate stack (4 in this case)
                                                  ;still left since negative AIS
                    pull                          ;restore all registers
                    rts

                    #sp                           ;cancel auto mode and offsets

Notes about #SPAUTO:

Besides providing a method for automatic adjustment of stack offsets that refer outside/within a certain block of code (so they remain ‘apparently’ constant), #SPAUTO can also be used to automatically de-allocate the correct number of stack bytes at the end of a block of code. This allows for easier and more accurate coding (since no mental accounting is required) and possible future changes in existing code do not require adjustment of any ‘usually’ affected instructions.

The following is an example of code that shows both of the above uses:

                    #spauto                       ;auto mode and zero offset

                    ldhx      Size,sp
                    pshhx
                    ldhx      ToAddress,sp        ;no need for: ToAddress+2,sp
                    pshhx
                    ldhx      FromAddress,sp      ;no need for: FromAddress+4,sp
                    pshhx
                    call      CopyMemory          ;call the action routine
                    ais       #:spfree            ;deallocate however many bytes
                                                  ;were allocated for parameters
                    ...
                    #sp                           ;cancel auto mode and offsets

Now, as an example, if you wanted to add yet another set of parameters to the CopyMemory routine (assuming the routine was modified to accept them) you would add some extra push instructions to the above code (shown in orange in the modified code below), but no other code or offsets would need adjusting.

The previous example becomes:

                    #spauto                       ;auto mode and zero offset

                    #psp
                    ldhx      #SkipTo             ;new instruction added later
                    pshhx                         ;new instruction added later
                    ldhx      #SkipFrom           ;new instruction added later
                    pshhx                         ;new instruction added later
                    ldhx      Size,sp
                    pshhx
                    ldhx      ToAddress,sp        ;no need for: ToAddress+2,sp
                    pshhx
                    ldhx      FromAddress,sp      ;no need for: FromAddress+4,sp
                    pshhx
                    call      CopyMemory          ;call the action routine
                    ais       #:psp               ;deallocate however many bytes
                                                  ;were allocated for parameters
                    ...
                    #sp                           ;cancel auto mode and offsets

To appreciate how #SPAUTO can help, look at the same changed code but without #SPAUTO, where all three SP-indexed instructions plus the AIS instruction would have to have their offsets appended with an extra +4 (not to mention the original extra offset that must be in place as stack grows with each push). After a while this can get messy and error-prone.

                    ldhx      #SkipTo             ;new instruction added later
                    pshhx                         ;new instruction added later
                    ldhx      #SkipFrom           ;new instruction added later
                    pshhx                         ;new instruction added later
                    ldhx      Size+4,sp
                    pshhx
                    ldhx      ToAddress+2+4,sp    ;2 (original) +4 (for new)
                    pshhx
                    ldhx      FromAddress+4+4,sp  ;4 (original) +4 (for new)
                    pshhx
                    call      CopyMemory          ;call the action routine
                    ais       #6+4                ;deallocate 6 (original)
                                                  ;+4 (for new)

With automatic SP offsets, you can’t be sure at all times of the actual offset used (after all, the idea is to let the assembler figure it out automatically), so certain optimizations that depend on specific stack offsets may no longer work if stack ordering is later changed. For example, divide HX by ten:

                    pshhx                         ;place number to divide on stack
                    clrh
                    ldx       #10                 ;divisor
                    pula                          ;A = MSB (assuming number at TOS)
                    div                           ;divide it
                    psha                          ;put it back on stack
                    lda       2,sp                ;A = LSB (assuming number at TOS)
                    div                           ;divide it
                    sta       2,sp                ;save it back to stack
                    pulhx                         ;HX = result

will work. But, if it were changed to:

                    pshhx                         ;place number to divide on stack

                    #spauto                       ;auto mode and zero offset

                    psha                          ;<<< added later to protect A

                    clrh
                    ldx       #10                 ;divisor
                    pula                          ;A = MSB (assuming number at TOS)
                    div                           ;divide it
                    psha                          ;put it back on stack
                    lda       2,sp                ;A = LSB (assuming number at TOS)
                    div                           ;divide it
                    sta       2,sp                ;save it back to stack

                    pula                          ;<<< added later to protect A
                    ...
                    #sp                           ;cancel auto mode and offsets

it will no longer work because PULA / PSHA always work on the top-most stack element (#SPAUTO does not alter mnemonics), which in this case is no longer the number we want to divide (as PSHA before CLRH has placed its own value on the top-of-stack, as we now decided to protect register A from destruction during the division operation) moving the MSB of the number we want to divide to the true offset 2,SP.

Here’s then what to do to have the assembler use the optimization but only if the TOS (top-of-stack) has the number:

                    #spauto                       ;auto mode and zero offset

Routine             proc
                    pshhx     number@@            ;stack & name number to divide

                    psha                          ;added later to protect A

                    clrh
                    ldx       #10                 ;divisor
        #iftos number@@
                    pula                          ;A = MSB (assuming number at TOS)
                    div
                    psha
        #else
                    lda       number@@,sp         ;A = MSB
                    div
                    sta       number@@,sp
        #endif
                    lda       number@@+1,sp       ;A = LSB
                    div
                    sta       number@@+1,sp

                    pula                          ;added later ...

                    ...
                    ais       #:ais               ;deallocate however many bytes
                                                  ;still allocated on stack
                    ...
                    #sp                           ;cancel auto mode and offsets

Here, we use #SPAUTO outside the whole code block. We then stack and assign a name to the number. Finally, using conditional assembly (#IFTOS), we test for the number@@ sp offset having the effective value 1 (i.e., TOS), and if so, we can use the optimization, otherwise we code it as if it were any other stack offset. (This is particularly useful in general-purpose macros, where it’s not possible to know in advance if the operand is going to be the TOS or not, but we want to have the best possible code generation for each case.) If the instruction pair PSHA/PULA (shown in green) is later removed, no changes are required to any of the remaining code. The PULA/PSHA optimization will automatically be activated, and due to #SPAUTO, all offsets will be adjusted accordingly.

Another method to stack and name the number is:

                    #spauto                       ;auto mode and zero offset

Routine             proc
                    pshhx
number@@            set       ::,2                ;stack & name number to divide

using the :: internal variable (which always i.e., regardless of current stack depth and the #SP/#SP1 setting of #SPAUTO mode refers to the top-of-stack item, so it must be placed immediately following the stack operation i.e., before another stack altering operation).

The above example introduces the use of the :: internal symbol.

The special :: internal symbol (a shortcut for the equivalent expression 1-:SP for #SP[AUTO] modes, or 0-:SP for #SP1 mode) is a very useful dynamic symbol for quickly and easily and without any mental calculations assigning labels to any stacked content, and at the exact time you push anything on the stack (no need to have your stack frame organized in advance, just define it as you use the stack). Because of the automatic SP adjustment while in the #SPAUTO mode, a symbol defined this way will always point to the correct location in the stack. No possibility of user error (assuming correct placement of #SPAUTO and/or related directives). This symbol will always point to 1,SP if used outside of #SP[AUTO] modes (or 0,SP in #SP1 mode, which is practically useless), and a warning will be issued whenever you use a stack-related internal symbol outside of a relevant SP-adjusting mode.

To use, always start a subroutine with #SPAUTO. Any stack offsets ‘above’ the current routine (normally, that would be in the parent routine’s stack) will be defined ‘before’ the #SPAUTO directive (not necessarily ‘physically before’ but ‘logically before’, i.e., based on a fixed starting offset value, usually the value one, and NOT the dynamic value of :SP), while stack contents within the routine will be defined logically ‘after’ the #SPAUTO directive using the :: internal symbol as a base offset. An #SP directive after the end of the subroutine turns all automatic SP adjustments off.

You may even re-define a stack-offset symbol (either using a ‘named push’ or the name SET :: method) and use it again with an updated stack location to prevent accidentally accessing the wrong stack item. For example, copying a parent routine’s variable to local stack so that you may change the local copy without affecting the parent stack’s variable is as simple as:

                    #spauto                       ;auto mode without any offsets

Parent              proc
                    pshhx     parm@@              ;stack parm and name it
                    ...
                    bsr       Child
                    ...
                    sthx      parm@@,sp           ;affects Parent's stack variable
                    rtc

;*******************************************************************************

                    #spauto   2                   ;auto mode plus RTS

Child               proc
parm@@              equ       1                   ;caller TOS before calling Child
                    ldhx      parm@@,sp           ;get parm from Parent's stack
                    pshhx     parm@@              ;stack local copy of parm and name it
                    ...                           ;(name "parm@@" now refers to Child's copy)
                    sthx      parm@@,sp           ;affects Child's stack variable
                    pulhx
                    rts

                    #sp                           ;cancel auto mode and offsets

Once you see in practice how this (#SPAUTO and related language extensions) can help you maintain the correctness of all stack references in a program as you alter stack operations (e.g., add new push/pulls, or change the order of push/pulls; you’re still responsible for keeping the correct LIFO order yourself, however), you may be surprised how you ever managed without it. Certainly, I was!

Several coding examples that collectively implement all the features described here can be found at http://www.aspisys.com/code and in the code subdirectory of the assembler ZIP archive.

Notes about :X and #X mode

:X will return the current automatic X offset. This allows you to get the true difference between automatic and actual X offset. You can also use the simulated indexed mode ,AX (Absolute X) to get the same effect.

As an example, you can use the #X mode to adjust X-indexed offsets after a TSX to refer to higher stack levels (e.g., parent routine). For example:

MyOffset            equ       0                   ;zero-based offset

                    ais       #-1                 ;allocate temp space
                    ...
                    tsx
                    sta       MyOffset,x          ;save to local stack
                    bsr       Sub
                    ...
                    #sp1      2                   ;account for RTS (zero-based)
                    #x        :sp

Sub                 tsx
                    lda       MyOffset,sp         ;gets A from parent stack
                    lda       MyOffset,x          ;(equivalent to above)

Notes about :cycles:

• The cycles counter is reset to zero right after it is accessed. To count cycles for a section of code, you must access :cycles twice, once before the code section to reset its value to zero (if not already zero from a previous access to :cycles or a #CYCLES directive), and once right after the code section to get the accumulated cycles.

• Because of the auto-reset on access, if you need to use the same value in more than one place at a time (e.g., code and #MESSAGE directive), you must assign it to a label first, then use the label.

• The obvious advantage is that if you alter code as in the example loop below (e.g., by adding conditional early escape code inside the loop), it will still be timed correctly without requiring a manual adjustment of the delay constant. A second advantage is that you do not have to keep separate cycle counts for 9S08 and HC08 families. A third advantage is that conditionally enabled code will be cycle counted correctly in all cases, again without requiring a manual recalculation for each conditional case.

• Example use of :cycles that automatically calculates the appropriate delay constant for a given bus speed (BUS_KHZ symbol should be defined accordingly):

                              #Cycles             ;reset cycles counter
Delay10ms           proc
                    pshhx
                    ldhx      #DELAY@@
                              #Cycles             ;grab cycles (and reset)
Loop@@              aix       #-1
                    cphx      #0
                    bne       Loop@@
                              #temp :cycles       ;grab cycles (and reset)
                    pulhx
                    rtc                           ;(normal and MMU compatible)

DELAY@@             equ       10*BUS_KHZ-:cycles-:ocycles/:temp

Example assembly code for calculating user CRC

;*******************************************************************************
; Purpose: Calculate the same user CRC as that produced by ASM8
; Input  : StackLo = StartAddress
;        : StackMd = EndAddress
;        : StackHi = Initial/Previous CRC
; Output : Stacked CRC updated
; Note(s): Call repeatedly for different address ranges, if skipping sections
; Call   :          ldhx      #CRC_SEED
;        :          pshhx
;        :          ldhx      #EndAddress
;        :          pshhx
;        :          ldhx      #StartAddress
;        :          pshhx
;        :          call      GetAsmCRC
;        :          ais       #4
;        :          pulhx                         ;HX = CRC

                    #spauto   :ab                 ;account for [RTS/RTC]

GetAsmCRC           proc
                    #temp     1
start_address@@     next      :temp,2
end_address@@       next      :temp,2
my_crc@@            next      :temp,2

                    push

Loop@@              ldhx      start_address@@,sp
                    cphx      end_address@@,sp
                    bhi       Done@@

                    lda       ,x
          #ifdef COP
                    sta       COP                 ;in case of many iterations
          #endif
                    beq       Cont@@
                    cbeqa     #$FF,Cont@@

                    mul                           ;low address with data byte
                    add       my_crc@@+1,sp
                    sta       my_crc@@+1,sp
                    txa
                    tsx
                    adc       my_crc@@,spx
                    sta       my_crc@@,spx

                    ldhx      start_address@@,sp
                    lda       ,x
                    thx
                    mul                           ;high address with data byte
                    tsx
                    add       my_crc@@,spx
                    sta       my_crc@@,spx

Cont@@              tsx
                    inc       start_address@@+1,spx
                    bne       Loop@@
                    inc       start_address@@,spx
                    bra       Loop@@

Done@@              pull
                    rtc

                    #sp                           ;(usually, only at end of file)

Example coding for skipping CRC calculation for volatile sections:

?crc                set       :crc                ;use SET, not EQU

          ;CODE/DATA TO SKIP FROM CRC CALCULATION HERE

                    #CRC      ?crc

or, in more recent ASM8 versions, you could use the #temp directive (preferred):

                    #temp     :crc

          ;CODE/DATA TO SKIP FROM CRC CALCULATION HERE

                    #CRC      :temp

Expression Operators and Other Special Characters

• Expressions are evaluated in the order they are written: left to right. All operators have equal precedence. Many other assemblers behave the same in this respect. Although at first this may seem like a nuisance, in practice for assembly language coding in particular it turns out that in most cases this allows for less complex, easier to read expressions, and it also makes it easier to use with macro parameters. For example, instead of lda {~1~}*2,x one simply writes lda ~1~*2,x as ~1~ is already known to evaluate correctly regardless of the operators used in a possible expression inside ~1~, such as OffsetB-OffsetA. Care is needed when porting code from other assemblers that don’t use left- to-right operator precedence to transform all expressions, accordingly. This should be straight forward in most cases. You can use { ... } to change the default precedence, such as {1+2}*{3+4}. The only limitation is no forward references are allowed.

• Avoid inserting spaces between values and operators (unless using -SP+ command-line switch or the #SpacesOn directive together with ; beginning comments). Otherwise, the expression will evaluate until the first space encounted and you will get unexpected results.

ASM8 Extended Instruction Set

The instructions listed below are not actually new instructions, rather, internal macros that generate one or more HC08/9S08 CPU instructions. These instructions are only recognized if the extended instruction set option is enabled (-X+ command line option or #EXTRAON processing directive), and are used just like normal instructions, but NOT like user-defined macros.

Error, Warning, and Hint Messages

This section provides the lists of error and warning messages.

Errors inform the user about problems that prevent the assembler from producing usable code. If there is even a single error during assembly, no files will be created (except for the ERR file, if one was requested).

Warnings inform the user about problems that do not prevent the assembler from producing code but the code produced may not run exactly as intended, or it may be inefficient. A program that has warnings may be totally correct and run as expected.

Hints inform the user about problems that do not prevent the assembler from producing correct code but there may be optimization opportunities.

Errors and warnings that begin with ‘USER:’ are generated by #ERROR and #WARNING directives, respectively. The source code author decides their meaning and importance. Hints generated by the #HINT directive do not begin with ‘USER:’, however.

In the lists below, what’s enclosed in angle brackets (< and >) is a variable part of the message. That is, it is different depending on the source line to which the error or warning refers.

The order the messages appear below is random. Some messages have similar meanings; they simply result from different checks of the assembler.

Errors

Warnings

Hints

Local Symbols

File-local Symbols

All symbols that begin with a question mark [?] are considered to be local on a per-file basis. Each INCLUDE file (as well as the main file) can have its own locals that will not interfere with same named symbols of the remaining participating files.

Advantages:

1. Symbols can be re-used in another INCLUDE file in a completely different way.

2. Local symbols are not visible outside the file that contains them.

This last benefit makes it possible to write quite complex INCLUDE files while making only the global variables and subroutine entry labels visible to the outside.

Procedure-local Symbols

All symbols that contain [@@] are considered to be local on a per-proc basis. Each proc can have its own locals that will not interfere with same named symbols of the remaining procs.

See the #PROC and PROC directives for details.

Advantages:

1. Symbols can be re-used in another proc in a completely different way.

2. Proc-local symbols are not visible outside the proc that contains them.

This last benefit makes it possible to write quite complex procedures while making only the subroutine entry label visible to the outside.

Macro-local Symbols

All symbols that contain [$$$] are considered to be local on a per-macro invocation basis. Each macro can have its own locals that will not interfere with same named symbols of the remaining macros or the different invocations of the same macro, even when calling itself.

See the macro directives for details.

Advantages:

1. Symbols can be re-used in another macro invocation in a completely different way.

2. Macro-local symbols are not visible outside the macro invocation that contains them.

This last benefit makes it possible to write quite complex macros while hiding all internal labels from outside access.

ASM8’s Miscellaneous Features

Repeaters

Each mnemonic (but not macro calls) may be suffixed by a colon [:] and a positive integer or expression evaluating to a number between 1 and 32767. This is referred to as the repeater value.

Some examples:

                    lsra:4                        ;Move high nibble to low

                    fcb:256   0                   ;Create a table of 256 zeros

                    fcb:{COUNT+1} 0               ;Create a table of expression COUNT+1 zeros

Segments

Eight special directives allow you to use segments in your programs. Segments are useful mostly in conjunction with the use of INCLUDE files. Since often it is not possible to know the current memory allocation for variables and code when inside a general-purpose INCLUDE file, segments help overcome this (and other problems) with ease.

Also, we often want to have our code and data (strings, tables, etc.) grouped in a different way in our source-code than the resulting S19 (object). Segments again give us the ability to have related code, variables, and data together in the source but separated into distinct memory areas in the object file. When using segments, it is common to have a single ORG statement for each of the segments, near the beginning of the program. Thereafter, each time we need to ‘jump’ to a different memory segment/area, we use the relevant segment directive.

Although the eight segments are named #RAM, #ROM, #EEPROM, #XRAM, #XROM, #DATA, #SEGn, and #VECTORS their use is identical (except for the initial default values) and they are interchangeable. Use of segments is optional. If segments aren’t used, you are always in the default #ROM segment (which explains why code assembles beginning at $F600).

Using BSR, JSR, and CALL instructions efficiently

Although the assembler does not restrict the programmer what instructions to use when calling subroutines, the following advice will help you keep your sanity in larger applications, so make it a habit to always do so in your programs.

Use BSR and JSR instructions exclusively for calling file local subroutines. (And this, assuming each file is only meant to reside in the same block of memory. In other words, a single file will be in the same logical memory space, whether that is non-paged, or paged memory for MMU equipped MCUs.)

File local subroutine names start with ?. And, if the appropriate ASM8 option is turned on, you’ll be hinted to change JSR to BSR when the distance is close enough, saving a byte for each change. Or use !JSR to avoid the hint. Make sure to terminate those subroutines with an RTS instruction.

Use CALL instructions to call global subroutines, i.e., subroutines with names not beginning with ?. Important: Global subroutines can be defined in the same file they are used or some other file. What makes a subroutine global is its name, not where it is defined. Make sure to terminate those subroutines with RTC instructions.

If you follow this advice, NEVER assume a same file subroutine can be called with BSR or JSR. Look at the name instead. If it starts with ? use BSR or JSR, otherwise use CALL. If you change a subroutine from global to local or vice-versa, make the necessary changes to all calls and don’t forget to change the return instruction, also. Alternatively, add a wrapper subroutine so that your subroutine can effectively be called either way; locally for better efficiency, by using the ? beginning name, and globally, otherwise. Two entry points, preferably named the same except for the leading ? to mark the file-local version (as per assembler requirement). Like so:

                    #spauto   :ab

Sub                 proc                          ;global entry to be CALL-ed
                    push                          ;save whatever caller's registers are used in our proc (if any)
                    #ais

                    ...
                    bsr       ?Sub
                    ...

Done@@              ais       #:ais               ;de-allocate local stack variables (if any)
                    pull                          ;restore caller's registers
                    rtc

;******************************************************************************

                    #spauto   2

?Sub                proc                          ;file-local entry to be BSR/JSR-ed
                    push                          ;save whatever caller's registers are used in our proc (if any)
                    #ais

                    ...

Done@@              ais       #:ais               ;de-allocate local stack variables (if any)
                    pull                          ;restore caller's registers
                    rts

(Care must be taken when ?Sub uses parent’s stack variables. These must be copied from the global Sub before the BSR to ?Sub and the results copied back to the parent stack after the BSR to ?Sub.)

The CALL instruction is normally only available in MMU equipped variants of 9S08 MCUs. But, by default configuration, the assembler will automatically convert all CALL and RTC instructions to JSR and RTS ones, respectively but only when in #NoMMU (-mmu- command-line) mode.

It will also not issue hints when the target gets too close for a BSR instruction as you wouldn’t want to change these to BSR so they continue working when the code (e.g. a general library) is also used in MMU mode in some other application.

This makes your code 100% compatible with both MMU and non-MMU variants. All you need is to use the #MMU or #NoMMU directive, respectively. (Normally, this would be done inside the MCU specific include file, only once for each MCU.)

If using ASM8’s automatic stack offset adjustments (highly recommended), your global subroutines include the #spauto directive as shown in the previous example:

The :ab will be converted to 3 when in MMU mode, and 2 when out of MMU mode.

Marking big blocks as comments

#IFDEF without any expression following will always evaluate to False. This can be used to mark out a large portion of defunct code or comments. Simply wrap those lines within #IFDEF and #ENDIF directives. This saves you the trouble of individually marking each line as comment, e.g.:

#IFDEF

This is a block of comments explaining all the little
details of this great assembly language program...

Blah, blah, blah...

#ENDIF

The only drawback is that the listing file will not include this section. In some cases this is desirable, in others it isn’t.

Creating ‘menus’ of possible -D option values

ASM8 -Dxxx [[-Dxxx]...] is used to pass up to one hundred symbols to the program for conditional assembly. Here’s a tip for creating ‘menus’ of possible symbols to use with the -D option, so you don’t have to remember them.

An example follows:

#ifdef ?
          #Hint     ******************************************
          #Hint     * Choice of run-time conditional symbols
          #Hint     ******************************************
          #Hint     * DEBUG: Turns on debugging code
          #Hint     * QE128: Target is MC9S08QE128
          #Hint     * GP   : Target is MC68HC908GP32
          #Hint     ******************************************
          #Fatal    Run ASM8 -Dx (where x is any of the above)
#endif

The command ASM8 -D? PROGNAME.ASM will display the above ‘menu’ of possible -D values and terminate assembly. If you make it a habit of doing this in all your programs, then at any time you’re not sure which conditional(s) to use, simply try assembling with the -D? option and you will get help. (A question mark is the smallest possible local symbol you can define. It is a perfect candidate for this job as it is easy to remember because it’s like asking for help, and also because it is only visible in the main file. You could, of course, use any other symbol name you like, but be consistent or you’ll lose the benefit of this ‘trick’.)

Using -Dx with specific values

You may also assign a specific value to a symbol defined at the command-line. This makes it possible, among other things, to assemble a program at different locations on the fly. For example, the following program:

;SAMPLE.ASM

ROM                 def       $F800               ;Default ROM location

                    #ROM      ROM                 ;(switch to ROM segment and ORG it at ROM)

Start               proc
                    rsp                           ;the program begins here
                    ...                           ;(left to imagination)
                    bra       *                   ;the program ends here

will be assembled at $F800 with the command ASM8 SAMPLE but you could also assemble with a command similar to this: ASM8 SAMPLE -dROM:$8000 to move ROM to a different location at assembly time. (You can use either : or = to assign a value to the symbol.)

As another example, you could declare an array where you override the default dimension during assembly. No need to edit the source. The same source could produce different versions.

;SAMPLE.ASM

ARRAYSIZE           def       10                  ;Default size for array

          #if ARRAYSIZE < 2                       ;check for minimum size allowed
                    #Warning  ARRAYSIZE ({ARRAYSIZE}) must be at least 2
ARRAYSIZE           set       2                   ;Minimum size for array
          #endif
                    #RAM

status              rmb       ARRAYSIZE           ;status for each object
.object             rmb       ARRAYSIZE*2         ;pointer to each object
                    ...

                    #ROM

Start               proc                          ;the program begins here
                    rsp
                    ...                           ;(left to imagination)
                    bra       *                   ;the program ends here

Getting rid of the No ORG... warning

If you are annoyed by the No ORG... warning that shows up whenever the assembler attempts to produce code or data without first having encountered an ORG statement, here’s how to turn it off without actually specifying a fixed origin.

Somewhere before any code or data, and regardless of the current segment, use the pseudo-instruction:

                    org       *

This is a No Operation ORG statement because it will simply use the current location counter for the ORG. It effectively does nothing. It will, however, set the appropriate internal flag that tells the assembler an ORG has been used and, thus, no warning!

Calling ASM8 from PE’s WinIDE

Here’s how to setup the WinIDE to use ASM8.EXE instead of PE’s assembler. This will let the IDE catch possible errors during assembly and take you to the problem source file and line.

Create a batch file, called ASM8.BAT, which contains the following lines:

@echo off
c:\utils\asm8.exe %1 %2 %3 %4 %5 %6 %7 %8 %9 -T+ >c:\temp\error.out

where c:\utils is the directory ASM8.EXE is located and c:\temp is a directory you want to use for sending the temporary file with errors.

In WinIDE, select “Environment -> Setup Environment -> Assembler/Compiler -> EXE Path” Put the path of the ASM8.BAT file you created earlier.

In the box Type, select “Other Assembler/Compiler” In Options, type: %FILE%

Select the checkboxes for “Wait for compiler to finish”, “Save files before assembling”, and “Recover Error from compiler” and de-select the remaining ones.

The Error Filename should be c:\temp\error.out (or whatever filename you actually used in your ASM8.BAT above).

The Error Format should be “Borland Compatible”.

Tips on using the MEMORY directive

The MEMORY directive is generally very useful for any program. It could help you save precious debugging time by alerting you whenever you accidentally put code and/or data where there is no real or available memory. The best place to use this directive is the same include file that defines the particulars of a specific MCU. And, assuming you always #INCLUDE one such file in every program you write, you can forget about it.

Another use for the memory directive is to help you write a program that does not necessarily reside in specific memory locations but, rather, it occupies no more than so many bytes. For example, you’re writing a small program that must be no more than 100 bytes long. Here’s how to set the MEMORY directive to warn you should you go over this limit:

Start               proc                          ;the program begins here
                    rsp
                    ...                           ;(left to imagination)
                    bra       *                   ;the program ends here

                    #Memory   Start Start+100-1   ;allowed range = Start to 100 bytes later

If while writing your program you begin getting MEMORY Violation warnings, you’ll know you have reached (actually, gone beyond) the allowed limit. You must cut down the size of your code until the warning disappears.

My own source code style and naming conventions

Synopsis:

• Tabs are never used.
• End of line spaces are removed (automatically by the editor or a separate utility as required).
• End-of-line is Linux style (LF) even under Windows.
• Labels begin in column 1 (assembler requirement).
• Non-conditional directives begin in column 21.
• Conditional directives outside a code block begin in column 1.
• Conditional directives inside a code block begin in column 11.
• Each nested conditional directive is indented by 2 spaces from its parent.
• Instruction mnemonics and most macro calls begin in column 21.
• Instruction operands begin in column 31.
• End of line comments begin in column 51 unless a long operand pushes them further to the right, in which case at least one space separates the comment from the operand.
• All comments begin with semi-colon (the assembler does not enforce this).
• Stand-alone comments begin in column 1.
• In-line proc comments begin in column 11 or follow a dotted line (;---) that begins in column 11 and runs to column 49, leaving column 50 blank, then a semi-colon in column 51 followed by the comment text.
• Dot-ending names (XXX.) indicate a unique bit by position number (0 thru 7).
• Underscore-ending names (XXX_) indicate a bit mask (possibly including multiple bits).
• Underscore surrounded names (_XXX_) indicate special system symbols such as CCR offsets, etc.
• All constants are uppercase and use underscores to separate words as needed (MY_CONSTANT).
• All variables are lowercase and use underscores to separate words as needed (e.g., my_var).
• All pointer variables begin with a point/dot (.var).
• Code labels use CamelCase.
• File-local labels begin with ? (a question mark). This is an assembler requirement.
• Proc-local labels end with @@ (although the assembler allows @@ to be anywhere past the first character of the label).
• Macro-local labels end with $$$ (although the assembler allows $$$ to be anywhere past the first character of the label).
• Subroutines always begin with a proc pseudo-op to mark the beginning of the subroutine. This allows proc-local symbols to be used inside the subroutine without worrying about name collisions with other subroutines’ symbols.
• Subroutines normally use #spauto mode with optional :ab offset when the proc may reference caller-level stack variables.
• Local (stack) variables are defined near the beginning of the subroutine either directly (with AIS #-nn) or with the use of the local macro which follow an #AIS directive. These variables are de-allocated using the AIS #:AIS instruction.
• Each subroutine is separated from the previous one with an 80-column semi-colon beginning comment line full of asterisks (i.e., ;***...).
• File-local subroutine names begin with ? as required by the assembler to keep the name local to that file.
• File-local subroutines end with an RTS instruction. They are called with either JSR or BSR instructions.
• Global subroutines end with an RTC instruction. They are called exclusively with the CALL instruction (for MMU compatibility).
• Very small (few lines) and obvious purpose subroutines usually have no spaces between instructions.
• Regular subroutines separate each block of related assembly language instructions with a single blank line, or a dotted comment line (see earlier).
• Segments are used to separate object code into distinct areas. Segment #RAM is used for zero-page RAM variables that may need B[R]SET or B[R]CLR instruction access. Segment #XRAM is used for all other variables. Segment #ROM is used for normal code. Segment #VECTORS is used for vector definitions.
• File inclusion is done primarily with the #Uses directive. #Include is only used when the same file must be included more than once (where #Uses would fail by design), or when we need to be sure the inclusion point is at the #Include directive (since a #Uses may have already included the file at some earlier point).
• All file inclusion paths are relative and depend on the assembler’s default include path search. Specifically, they are first relative to the current file being assembled, then to the main file of the current assembly, and finally to the root file (filename _asm_) if one exists.
• Ad-hoc ? macros are used extensively to simplify repeated sequential coding of complicated expressions or coding patterns.
• Hungarian notation is never used.

Some of the above points in a bit more detail…

_MY_OFFSETS_ are constants (see above) surrounded by single extra underscores.

MyRoutines are CamelCase names. They may also use underscores mostly to separate module from function name, as in InitializeSCI which could also be written as Initialize_SCI or SCI_Initialize (preferred).

File local symbols follow the above rules but always start with ? (question mark) by requirement of the assembler. Example: ?my_variable

Proc local symbols follow the above rules but always end with @@, example: Loop@@ by requirement of the assembler. (Note: The assembler requirement is only for the presence of @@ anywhere after the first character and not that they appear at the end of the label as in my own convention.)

Macro local symbols follow the above rules but always end with $$$, example Loop$$$ by requirement of the assembler. (Note: The assembler requirement is only for the presence of $$$ anywhere after the first character and not that they appear at the end of the label as in my own convention.)

Comments always start with a semicolon. Macro comments that do not need expansion start with a double semicolon, and are not saved with the macro.

Labels are defined starting in column 1 (assembler requirement) and use the default maximum label length of 19 (including expansion of @@ or $$$) so they remain compatible with P&E Micro map files.

Mnemonics and pseudo mnemonics (e.g., ORG) start in column 21 and are always written in lowercase. Exception to the lowercase convention is when an instruction is meant to do something other than the obvious, e.g., RTS when used to JMP to a previously stacked address will be written in uppercase to signify the special use.

Macro calls normally start in column 21 just like regular mnemonics but they may also start in column 1 if, and only if, they are invoked as @macro (leading @). This is useful when there are long operands to make it easier to view without any/much horizontal scrolling of the editor window.

Operands start in column 31 unless a long repeater expression or macro name pushes them further to the right. For macro calls that start earlier than column 21, operands may start anywhere, usually after a single space from the macro name.

Comments start in column 51 unless a long operation/operand combination pushes them further to the right, separated by at least one (preferably two) space character(s).

Procs are separated with an 80-char comment line full of asterisks that always begins with a semicolon. (Most editors allow shortcut macros that quickly produce such template code.)

A non-trivial proc uses a header with Purpose, Input, Output, and Note(s) that describes the purpose of the proc and the calling interface. Something like:

;*******************************************************************************
; Purpose:
; Input  : HX ->
;        : A =
; Output : Carry Clear on success, Carry Set on Error
;        : HX ->
;        : A =
; Note(s):

All procs use automatic SP offset adjustment with the #spauto assembler directive immediately preceding the proc directive and separated from it with a blank line.

Procs that refer to caller stack follow #spauto with an appropriate offset. If the proc is near (i.e., ends with an RTS instruction) it normally uses the offset 2. If the proc is far (i.e., ends with an RTC instruction) it normally uses the offset :ab which adjusts automatically based on whether an MMU is used or not.

Each proc begins with the proc name and the assembler directive proc. An endp directive at the end of the proc is normally not used, unless we specifically want to embed a proc inside another, usually much larger proc, for proximity reasons (e.g., frequent BSR use optimization), in which case we need to protect the parent proc’s label locality.

Each proc protects all caller registers except for CCR (with few exceptions that need to also protect CCR), and those registers that pass out return values. Usually the PUSH instruction is used right after proc and the PULL right before RTS or RTC. If RegA is used to return a value then either we replace PUSH and PULL with PSHHX and PULHX or we name the return register and save the result to it, like so:

                    #spauto

Sub                 proc
                    psha      ans@@
                    pshhx
                    #ais

                    ...
                    sta       ans@@,sp            ;save result for caller
                    ...

Done@@              ais       #:ais
                    pull
                    rtc

Procs are written in a modular (structured) way with entry, main body, and exit sections. (There are exceptions when clarity of purpose is more evident, otherwise.)

Proc-local labels are used in a consistent manner where possible. So, a proc with a single loop will have it start at label Loop@@ and continue at the label Cont@@.

A proc’s exit section begins at label Done@@ where any exit requirements are enforced. This usually includes releasing temporary stack variables with the AIS #:AIS instruction that automatically releases as many bytes as were allocated by either AIS or PSHx instructions at the entry section.

Each proc may return (in addition to any registers), a success or failure status in the CCR[C] register bit. Success is always CCR[C] = 0 which is achieved with a single CLC instruction. Failure, on the other hand, requires a SEC instruction. Note this is different from C language convention where a zero is considered false. Here, a zero Carry flag is success (or true in true/false determining proc).

The body section should release its own stack as it is used.

Note: My own code and/or examples may not yet adhere to all of the above, as most of it was written long before these conventions were put into action.

But, each time some code gets updated, I try to also update the coding style to conform to my most current conventions. And, the conventions are subject to improve (in my subjective view) with experience.

Each instruction (with the exception of trivial operations) is documented in the comments area with appropriate comments that do not repeat the instruction but explain what happens and/or for what purpose.

Following the above conventions has helped me produce consistently bug-free code (within reasonable expectations), and easy to read logic.

Linux/Win32 version addendum

The DOS, Win, and Linux versions are practically identical. Where there are differences, these are noted.

A few differences with the Linux or Win32 versions are listed below:

Standard error redirection works for Windows, and all messages, hints, warnings, and errors are redirected. For Linux all output (not just the errors) is redirected, but this may not be in a very readable format as it may include the line counters during Pass1 and Pass2. To have proper ERR files created, please use only the -E option.

Beginning with v1.20, the DOS/Win32 versions allow wildcards on the command line for matching multiple assembly language filenames. The Linux version uses standard Linux syntax for multiple filenames. For Win32/Linux case, filenames are not limited to the DOS 8.3 format. The #INCLUDE directives within the source code may also specify long filenames.
Currently, spaces within long paths or filenames are not supported.

For all versions, you must keep the included asm8.cfg in the same directory as the asm8[.exe] binary (for example, ~/bin for Linux or C:\Utils for DOS/Win32, etc.). Any time you change options and save them (with the -W option) a new asm8.cfg file will be created in the current directory (or updated if it already exists). If you want to make this new configuration the current directory project’s default, leave the .cfg file in that directory, and run asm8 from there. Note: If you happen to rename the executable to whatever other name, you MUST also rename the .cfg file to the same base name, or it won’t be found.

In case you also want to make this .cfg file the new global default, “mv” (Linux) or “move” (Win32) it to the ~/bin or other directory where your asm8[.exe] binary is, and anytime a local asm8.cfg isn’t found, the global one will be used instead.

Another difference imposed by Linux is that filenames are case-sensitive. But, to ease porting from DOS/Win, if a file (e.g., #INCLUDE) is not found, it will be searched for again as “all lowercase” and, if not found a second time, it will be searched for once more as “all uppercase.” This makes it easier to transfer files from DOS/Win to Linux and not have to rename them, or do so but not have to also change the source code.

These are pretty much the only differences in behavior.

Assembly language source code syntax is identical for all platform versions, except where noted otherwise.

Setting up FreeMASTER (from Freescale/NXP) for use with ASM8

IMPORTANT: You must use the -MTA option for generation of ASM8 map files. This will create ASCII map files that can be parsed by a regular expression text parser. (The default P&E Micro map files cannot be used for this purpose.)

In FreeMASTER application, go to Project/Options/MAP Files option and define a RegExp text parser as the File Format. Then fill out the screen that appears as follows: ([0-9A-F]+) +([0-9]+) +([0-9]+) +([^ ]+) +([1-9][0-9]*)

ASM8 v12.30, February 13, 2022, Copyright (c) 2001-2022 by Tony G. Papadimitriou (email: tonyp@acm.org)