Macros for McAssembly

By Paul F. Snively, Columbus, IN, MacTutor Contributing Editor

Question: What do you get when you combine the MDS assembler, linker, RMaker, PackSyms, and a mini-make utility all in one 39K program?

Answer: McAssembly, from Signature Software.

This new development system comes complete with Apple's Edit, McAssembly, three versions of McBug, and an entire disk full of files which were licensed from Apple covering everything from the low RAM equates and OS and Toolbox equates to interface routines for MacinTalk, AppleTalk, Graf3D, and the RAM based serial driver.

As you can see, McAssembly represents quite a step up for me (a veteran MacASM user) in terms of complexity and power. I've always ranted against MDS, so why am I using a very MDS-like system now?

First of all, I'm getting into more esoteric climes in terms of what I'm trying to do with the Mac. MacASM is extremely good at what it promises to do, namely allowing the user to easily and quickly develop stand-alone Mac applications.

MacASM lacks the ability to do some things that I now find myself wanting to do, such as write desk accessories and link object code with code produced by other development systems, such as TML Pascal (more about that later). In addition, McAssembly maintains two strong advantages that MacASM had over MDS - speed and more importantly (n my case, anyway), size. I am, after all, a 512K one drive user.

Let's talk about this new assembler. Edit is by now the de facto standard Macintosh editor, so I won't talk about that here.

The best way to talk about McAssembly is menu by menu, so

Fig. 1. The File Menu

The file menu controls execution of the major components of McAssembly: the assembler (called McAsm when referred to alone), the linker (called McLink when referred to alone), and the job controller (no, it's not called McJob, it's just the job controller).

Choosing "Assemble" brings up the standard file dialog with a list of all files with an .Asm extension. Selecting a file causes McAsm to assemble the file, generating a .REL file.

Choosing "Link" brings up the standard file dialog also, but this time it shows files with .Lnk and .Job extensions (I'll explain the apparent contradiction a bit later). The .Lnk and, in this context, .Job files are linker control files, and choosing one causes McLink to try to link together the .REL files that it specifies.

The "Run job" option shows only .Job files. .Job file execution is different depending upon whether the user selected the file from "Link" or from "Run job."

A linker control file is really just a specific kind of job control file. All that is in a linker control file is a list of the .REL files to be linked (any filenames not ending in .REL will have the extension added automatically), segmenting information (in the form of $ [ P ] [ L ] lines, where $ is the segment break specifier and P and L are optional "Purgeable" and "Locked" flags, respectively), filenames of resource files to be linked in (preceeded by a "%" - great if you are in the habit of creating your resources with ResEdit, for example), and the name of the resulting resource file (preceeded by a "/").

Job control files, on the other hand, are more powerful, but are still simple. They can contain comment lines, which start with an asterisk ("*") as well as all of the other kinds of lines. That is the only visible difference, and it's not really a difference, since .Job files can be specified from the "Link" menu option. There are, however, other, more subtle differences.

For job control files executed via "Run job," if the filenames have no extensions the job controller does not assume one. Instead it assumes that the file is to be both assembled and linked if at all possible. Files with .REL extensions are only linked.

If the /filename line is supplied the job controller assumes that there needs to be a link phase. Otherwise only the assembly phase is executed.

Now for the interesting part: if a filename in a job control file has no extension and there is a / line for the resource file specification the job controller will attempt to assemble the .Asm file if 1) the .Asm file is presently online and there is no corresponding .REL file or 2) the modification date on the .Asm file is more recent than the modification date on the .REL file (the .REL file is out of date). If the .REL file is not out of date, the job controller will not reassemble the .Asm file. This intelligent "do I need to assemble or not" feature is the mini-make utility that I mentioned.

Executing a job control file that has a / line as a linker control file will behave exactly as any other linker control file - there will be no attempt to assemble at all.

Incidentally, this description of how the job controller works is somewhat at odds with the description in the manual. The manual says that the job controller assumes that the filenames will have no extension and does not specify what happens if that is not the case. Fortunately, files with .REL extensions are linked but not assembled - which is how it should be, since in some cases (Graf3D.REL, for example) the user has the object code but not the source code.

The "Quit" option, of course, returns to the Finder.

Fig. 2. The Assembler Menu

Figure 2 shows the assembler options menu. As it is above the default options are enabled.

"Object file" enables/disables the generation of the .REL file. This is useful for just checking the .Asm file for obvious syntactical errors.

"Listing to printer" selects whether or not to send any output to the printer.

"Listing to screen" selects the monitor as an output device.

"Listing to file" selects a file with an .LST extension as an output device. This is handy for use in Edit to look for the lines in error.

"Errors only listing" toggles between listing only lines in error or listing the entire program (subject to the list directive value in the source code).

"Symbol table" toggles the option to display a list of all symbols and their values.

"Cross reference" toggles the ability to display a list of what refers to what. All symbols are shown except local labels.

".PSM file" toggles the generation of a file of packed symbols for the program being assembled. This probably won't be used much; but the assembler's ability to load .PSM files will - .PSM files are compact and speed up assembly greatly, because they require no interpretation and are only read on the first pass of the assembly.

"DEF all symbols" toggles the external definition of all symbols in the assembly. The primary purpose of this is to have a complete set of symbols to load into McBug, which is a symbolic debugger.

Sound good so far?

Fig. 3. The Linker Menu

The "Symbol table" option allows for the linker to display all externally defined symbols in the module. The "Symbol table" option for the assembler, incidentally, displays all symbols, not just the externally defined ones.

Don't get too excited about the ".MAP file output." The .MAP file that it generates is just a copy of the module map displayed by the linker; it bears no relationship to the .MAP file generated by the MDS linker.

"Printer output" prints linker output on the printer as well as the screen.

"McBug .SYM file" toggles the generation of a .SYM file for the program, which can be loaded into McBug for symbolic referencing. This file format is NOT the same as MDS' .MAP format, although the end result is essentially the same. One of my future projects is rewriting TMON's User Area routines so that they will accept the McAssembly .SYM file format.

A few words about McLink: First of all, no, it is not compatible with MDS' linker, Apple's forthcoming linker, or any other linker, for that matter. Dave McWherter, the author of McAssembly, tells me that his .REL file format is very similar to Apple's new one, but he is leery of being the first third-party vendor to implement a compatible format - especially in light of the fact that Apple's linker hasn't been released yet! If you are interested in McAssembly supporting Apple's .REL file format, please help me try to convince him.

You MDS/Consulair linker users needn't feel left out, though. Included with the McAssembly system is a utility that converts McLink .REL files to MDS format. Dave admits that he doesn't like the idea; he doesn't like some things about the MDS linker, such as the fact that it can't deal with BR type instructions (BRA becomes JMP with the MDS linker, for example). Also, his utility cannot as of yet convert named resources - the name is lost in the conversion. This is a minor thing anyway, but he may come up with a version that will solve that problem (it revolves around the fact that with MDS resource names are symbols whereas with McAssembly they are not). The conversion is one way - McLink -> MDS Link and not vice-versa. Dave says there are some things that his linker does that MDS doesn't and vice-versa, which doesn't surprise me. One of the things that McLink allows the user to do is to specify an offset from A5 at which global allocation for the module is to begin. The pseudo-op that does this - A5OFF - affects the current module and any subsequent modules that don't have A5OFF's of their own. Another nice little feature is that if a .REL file contains a standard BNDL resource, McLink will automatically set the bundle bit on the resulting resource file. More about resources in a moment. Also, McLink is blindingly fast compared to MDS Link!

Fig. 4. The Jobs Menu

Figure 4 shows the "Jobs" menu with the default options enabled. "Stop if Asm error" does exactly that - assembly stops if there is an error during the assembly process.

"No link if Asm error" causes the link phase to be bypassed if there were any assembly errors. Both of these options, and their rationales, are fairly self-explanatory.

"Force assemblies" is the non-obvious one. It causes the assembly phase to be executed whether the .REL files are current or not. The reason for this is that McAssembly has an INCLude pseudo-op which can include other source files. What happens if the user changes an included file? The file that includes it does not show a new modification date, so the job controller ordinarily would not assemble it if a current .REL file was available. Thanks to the new include file, though, the .REL file wasn't really "current" anymore. With "Force assemblies," modified include files can be reassembled without loading and saving the including source so as to force a new modification date.

Fig. 5. The Beeper Menu

The Beeper menu is simple, too. Enabling the beep causes McAssembly to beep whenever it encounters the end of an assembly, a link, a job, and/or an error.

Fig. 6. The Transfer Menu

The Transfer menu is pretty straightforward. "Edit" gets the user there, and "Other" allows the user to choose any online application. Incidentally, Edit's Transfer choices are "hardwired" as strings in the code, even though the menu itself is a resource - bad news. That means that you have to rename McAssembly "Asm" on your work disk if you want to be able to get there from Edit. Reports are that Apple has contracted with Bill Duvall to revise Edit and MDS to be fully HFS compatible. Presumably, this means the "hardwired" strings would be removed and placed in resources or in some way made compatible with the new standard file package. The current version of McAssembly is 3.2, which is fully HFS compatible on the Mac Plus, except for the MDS Edit program problem, which is licensed from Apple and supplied on the McAssembly disk.

That covers all of the menu items and should give you some ideas about McAssembly's capabilities. Now let's take a look at some of the pseudo-ops that McAssembly places at the user's disposal.

A5SEC and A5END are the pseudo-ops that delineate the module's global variable area. The pseudo-ops surround a collection of DS pseudo-ops and serve to automatically make referrences to the labels defined relative to A5. A5SEC and A5END are actually specialized versions of BASE.

BASE causes one or more labels to be referred to relative to a given address register whenever that label appears alone or with an additive offset. Incidentally, the first version of the assembler that I received had a bug - the additive offset could only be a constant, not a label. In other words, if you BASE A0,ioFlUsrWds and try to use a line such as CMP.L #'APPL',ioFlUsrWds+fdType (a real life example from Launch Doc), the result is CMP.L #'APPL',$20 instead of CMP.L #'APPL',$20(A0). This has been corrected.

The A5SEC and BASE pseudo-ops make it possible to forget about what address register you are dealing with and make the use of offset labels (which abound in Mac development systems) far more natural. It would not be difficult to BASE offsets from A6, for example, giving the user a convenient local variable capability. I'll give some specific examples of this capability later.

Some other important pseudo-ops are NOLOC and LOCSYM. NOLOC causes local label scoping to behave the same way as MDS's. This is helpful, since without it the user would have to insert a LOC pseudo-op immediately next to every major label in the code to get the same effect.

LOCSYM allows the user to define the local label character. McAssembly normally uses the period as the local label specifier, but once again for the sake of MDS compatibility LOCSYM "@" can be used to set the local label character to be the same as MDS's.

We've talked about the assembler, the linker, the symbol packing function, and the job controller. Now let's take a look at resource definition in McAssembly.

Dave McWherter apparently took a hint from Mainstay (the people behind MacASM) with his resource generation. The resource compiler is an integral part of the assembler itself, and there's no particular reason why you couldn't use the assembler strictly as a resource compiler (no code), nor is there any reason why you can't put assembler source code in a non-CODE resource (meaning that writing desk accessories, new INIT resources, new FKEY resources and the like is a snap - no more RMaker TYPE DRVR = PROC)!

McAssembly's resource compiler has two basic modes - standard resource compilation and user defined resource compilation.

Standard resources start with the delimiter $$ and have no ending delimiter. The supported standard resource types are: ALRT, BNDL, CNTL, CURS, DITL, DLOG, FREF, ICON, ICN#, MENU, PAT , PAT#, STR , STR#, and WIND.

User defined resources start with the delimiter [[ and end with the delimiter ]]. They can be of any type and can contain any valid McAsm data and/or code.

Any resources defined in McAsm source files must come after the program's code. If the user attempts to add code after resource definitions errors will result. Furthermore, if you use the linker control line "%Filename," where Filename is the name of a pure resource file, it must also come after any code that is to be linked. The bottom line is that non-CODE resources are always last in McAssembly.

The application signature is a good example of a user defined resource. A signature is nothing more than a STR255 resource by another name. A type is chosen and the TEXT pseudo-op is used with the # option, giving the STR255 type string, e.g.

[[ LDOC,0
        TEXT        # "Launch Doc 1.0"
]]

Standard resources look like this:

$$ FREF,128
APPL
0
|

Notice that the programmer does not need to know the size (word, long, etc.) of the resource item, only its type. A | indicates a null string.

All but a tiny fraction of MDS programs can be assembled with McAssembly simply by putting A5SEC and A5END around the globals (and moving them to the front of the file, if necessary), adding NOLOC and LOCSYM "@" to the front of the code, and converting any resources from RMaker format to McAssembly's format (it's easy) and appending them to the source file. Assembling and linking should generate a working application (or whatever).

Assembler, editor, linker, resource compiler, job controller ah, yes, the debugger!

McBug is a small, rather elegant little symbolic debugger. It's symbolic in that if you (I)nstall an application McBug will look for a .SYM file for that application and, if it finds one, will allow references to code and data in the application by the labels defined in the .SYM file.

While McBug is certainly not on a par with TMON, it is quite capable of holding its own against such debuggers as MacsBug. It offers the following features:

A - ASCII change memory

B - Set relocation base

C - Compare memory blocks

D - Display memory block

E - Eject diskette

F - Fill memory block

G - Go to user program

H - Hex add/subtract

I - Install an application

J - Display trap address

K - Convert hex to decimal

L - Locate a hex byte string

M - Move a memory block

N - Set display screen size

P - Peripheral device on/off control

Q - Quit McBug, execute startup

R - Read disk sectors

S - Hex change memory

T - Trace a user program

U - Execute a user subroutine

V - Display user registers

W - Write disk sectors

X - Change user registers

Y - Disassemble user program

Z - Enter patch assembler

Not bad for a little (20K) debugger, huh? There are some things that aren't implemented as commands that are nice too, such as the indirection operator (*). Want to disassemble at the current PC? Easy - Y*PC. To make a range that in practice extends forever, end a range with the highest possible value, which would be all bits high, which translates to -1. So, to disassemble from the current PC onwards, Y*PC -1.

'I' is nice - I wish other debuggers had it. It somehow loads the first segment of the specified program ("I LAUNCH DOC" for example) and passes control back to McBug right at the JMP instruction which passes control from segment zero to segment 1. Before your program can execute its first instruction you have control. It beats intercepting _InitGraf, which is what I generally find myself doing with TMON.

The disassembler knows the trap names, so the user is spared the agony of looking them up all of the time. The patch assembler does, too, but it doesn't know something else that can be frustrating - the mask value for the registers on a MOVEM instruction. The user must code the register mask by hand. Yecch.

Still and all, it's not a bad little debugger. In fact, I used it to debug my McAssembly version of Launch Doc and in so doing discovered the additive offset label bug mentioned above.

So how do I like it? Have I traded in my MacASM wings for McAssembly ones? To whom, if anyone, would I recommend this system?

If you are a serious Mac programmer who wants access to most, if not all, of the support files that come with MDS and you want a fast, compact, powerful, inexpensive system that is mostly compatible with MDS, McAssembly is your system. It is especially an alternative to consider if you are writing assembler code libraries to be linked into code generated by a high-level language such as TML Pascal.

I'd like to take this opportunity to thank Dave McWherter for providing a copy of the McAssembly system for review and for being one of the fastest, most responsive programmers that I've known. Not only did he get the original review copy to me, he sent one round of upgrades to me on his own initiative, wrote MDS Convert basically because I asked him to, and fixed the additive offset label problem the same day that I told him about it and has sent me that fix, as well as other upgrades. If he treats all of his customers the way that he treats MacTutor contributing editors, he should have no problem selling his system.

The Bottom Line

McAssembly strong points: It's small, fast, flexible, powerful, relatively inexpensive, and extraordinarily well supported. With MDS Convert it's also .REL file compatible (to an acceptable extent) with the MDS linker. McAssembly comes with a complete application example in source form, as well as a very comprehensive application "shell" for I/O intensive applications requiring only one large window (curiosity and suspicion lead me to disassemble just enough of McAssembly itself to reveal what I suspected to be true: McAssembly is written in itself and uses the "shell" provided with the system - in effect, the shell source is part of the McAssembly source)!

Some new features of version 3.2 is a trap compiler, which removes the burden of setting up registers and stack for the trap calls. Instead, you specify the trap name, followed by a list of the parameters in the Pascal order, using the addressing mode of assembly. The trap called in this manner invokes a Macrox which sets up the stack for you and checks for the correct number of parameters. For example, if I wanted to call the trap to get a new dialog box:

      Old Way:
 CLR.L  -(SP)  ; returned result
 MOVE.W #$100,-(SP); Dialog number
 CLR.L  -(SP)  ; place on heap
 MOVE.L #-1, (SP); put in front
 _GetNewDialog ; do trap call

      New Way:
 GetNewDialog  #$100, $0, #-1

These parameters are simply values being passed to a Macro, and hence any valid source operand expression may be used. As you can see, this trap compilation saves a lot of time and space setting up all those stack based parameters, and the checking for the correct number of parameters is a big help. Notice we don't have to do anything about clearing space for the returned result. The Macro takes care of that for us, so we can simply pop the result off the stack after the trap call as we normally would.

McAssembly weak points: The terminology can be confusing; I had hoped that McAssembly .MAP files were the same as MDS .MAP files. Nope. The documentation could use a little help. This probably stems from the fact that the docs are old; the copy that I received says in the corner of each page that it's for V1.3 of the assembler! Using words like "relatively" is dangerous; McAssembly is a $90 assembly language development system, which is inexpensive relative to MDS at full retail, but who pays full retail for anything? The first V2.0 copy that I got had some minor bugs, but Dave corrected those and got upgrades out so rapidly that I've all but forgotten them already.

[The linker is the last problem remaining as it shares the distinction with the Microsoft (Absoft) Fortran linker of not being too bright. Why everyone insists on writing their own linker when the Consulair smart linker already exists is something we fail to comprehend. Rumor has it that the Consulair linker, which is downward compatible with the MDS ".REL" file format, will be licensed soon to compiler authors like TML Pascal, which will make it the standard of the industry if it is not already. We would encourage Dave to either license this linker or make his conversion utility compatible with it so as to allow McAssembly users to be able to link McAssembly files with Pascal and C files using the Consulair smart linker. In a future issue we will be publishing the Consulair link format to encourage standardization of object code file formats. -Ed]

As promised earlier, I have some macros which make writing code for linking into TML Pascal a snap, or, for that matter, simulating a Pascal style interface for any reason, such as writing new CDEF, MDEF, or WDEF resources, or writing I/O completion routines or filter procs for dialog or alert boxes.

First of all, SFBegin is the macro which is used to start a stack frame, which is what you may have when coming into the code.

Long, Word, LongResult, and WordResult are macros which define stack frame elements of that length. The Result macros are used to make space for the results of functions; they are not dropped from the stack upon exit from the routine. Struct is used to define a structure of a size other than a word or a longword.

SFEnd is used to terminate the stack frame definition.

LVBegin is used to start the local variable definitions. Local variables are created by your routine at run time.

LVLong, LVWord, and LVStruct are the element definition macros for local variables.

LVEnd terminates local variable definition.

Enter is used to go into a Pascal-like procedure or function.

Exit is used to return from a Pascal-like procedure or function.

Here's the source code for the macro's:

SFBegin macrox   begin a stack frame
 dsec 0
 endm

SFEnd macroxend a stack frame
 ds.l 2 space for return address 
 and stacked a6
.fsize  equ *    size of stack frame
 dend
 endm

Long  macrox&1   a long stack frame item
 ds.l 1
&1 set  .fsize-*
 base a6,&1
 endm

Word  macrox&1   a word stack frame item
 ds.w 1
&1 set  .fsize-*
 base a6,&1
 endm

LongResultmacrox &1a long stack frame result
 ds.l 1
&1 set  .fsize-*
 base a6,&1
.parms  set *
 endm

WordResultmacrox &1a word stack frame result
 ds.w 1
&1 set  .fsize-*
 base a6,&1
.parms  set *
 endm

Struct  macrox &1,&2
 ds.b &2
&1 set  .fsize-*
 base a6,&1
 endm

LVBegin macrox   begin local var stack frame
 dsec 0
 endm

LVEnd macroxend a local var stack frame
.lvsize equ *    size of local stack frame
 dend
 endm

LVLong  macrox &1a long local variable
 ds.l 1
&1 equ  -*
 base a6,&1
 endm

LVWord  macrox &1a word local variable
 ds.w 1
&1 equ  -*
 base a6,*
 endm

LVStructmacrox &1,&2 a generic local stack  item
 ds.b &2
&1 equ  -*
 base a6,&1
 endm

Enter macroxa stack based proc or func
 ifdef  .lvsize  Exist?
 link a6,#-.lvsize      stack space for locals
 else
 link a6,#0 No locals
 endi
 endm

Exit  macroxexit a stack based proc or func
 unlk a6clear locals from stack
 ifdef  .fsize Are there parameters?
 move.l (sp)+,a0 Get ret address
 ifdef  .parms Function as opposed to proc?
 add.l  #.fsize-.parms,sp If so, remove only 
  input parameters
 else   If proc
 add.l  #.fsize,sp        Drop parameters
 endi   In either case...
 jmp  (a0)To caller
 else   No input or output on stack
 rts    To caller
 endi
 endm

These macro's (macrox's, really, meaning that they can refer to local labels outside themselves) rely on a very interesting pseudo-op: IFDEF. IFDEF is a conditional operator which evaluates to true if the operand (a label) is defined anywhere in the source code and to false otherwise. It exists primarily to allow the creation of exactly the kind of macros that you see above: ones that alter their behavior dependent upon whether some other macro has been invoked or not (for example, Exit's behavior is dependent upon whether SFEnd, LVEnd, and/or either of the Result macro's have been invoked). IFDEF can also be used to ensure that a necessary symbol file (such as SysEqu.PSM) has been included by checking a particular system equate and, if IFDEF returns false, using the PRMT pseudo-op to display a message on the screen.

That about wraps it up - I've spent way too long on this column the way it is. Look in the future for applications, desk accessories, and some code libraries for linking into TML Pascal - all written with McAssembly. In the meantime, if you're looking for a good assembly language development system, please give McAssembly your most serious consideration. McAssembly is available from:

Signature Software

2151 Brown Ave.

Bensalem, PA 19020

(215) 639-8764 $89.95