TweetFollow Us on Twitter

XCMD Chat
Volume Number:4
Issue Number:11
Column Tag:HyperChat™

XCMD Cookbook

By Donald Koscheka, Apple Computer, Inc.

on HyperChat

A Nice Chat

While doing the Sunday crossword puzzle recently, I was hit with a very interesting thought. One of the clues in this particular puzzle called for a synonym for “small talk”. The answer was “chat”. This struck me as odd because in many ways HyperTalk is very much the preferred object oriented programming language for the Macintosh. One of the earliest object oriented languages, as you know, is called “SmallTalk”. By calling this column “HyperChat”, Fred makes a rather obscure reference to HyperTalk’s philosophical roots. Chat implies a looseness of speech, a vernacular that is easy to master. That is exactly what HyperTalk is - an easy to grasp interface to the Macintosh Toolbox. What HyperTalk lacks in power, it certainly makes up for in ease of understanding!

At the opposite end of the spectrum is Assembly language programming. This much maligned language conjures all sorts of anxieties in the minds of otherwise fearless programmers. Yet most professional programmers will admit that an understanding of assembly language can improve one’s ability to write efficient code in a higher-level language as well as better understand those mysterious looking dumps that one gets when suddenly presented with a memory dump from TMON or MACSBUG.

Worse yet, those of us who choose to work in higher level languages provide a great disservice to the assembly language programmer by not showing them how to interface with our languages. HyperTalk documentation is certainly sparse in describing how an assembly language programmer can write an XCMD in assembly.

Assembly Interface

I started writing this month’s column hoping to be of service to the assembly language programming community. I wasn’t very far along when I realized that this column offers a second service, at no extra charge to the reader.

The process of showing you how to interface to HyperCard in assembly language also introduces the Pascal and C programmer to debugging in Macsbug or TMON (Forth programmers take heart: Jörg Langkowski’s article in the December, 1987 issue of Mactutor provides you with the information you’ll need to write XCMDs; even if you don’t program in Forth-like languages, you should read Jörg’s column; his insights into the Macintosh are often astonishing).

The most important reason to code in Assembly language is that it provides a rich opportunity to improve on the more generic code generated by Pascal and C compilers. Consider the following string comparison in Pascal:

len: INTEGER;
Match : Boolean;
Str1  : Str255;
Str2  : Str255;

Str1 := ‘Hello World’;
Str2 := ‘GoodBye Cruel World’;


IF Length(Str1) <> Length( Str2 ) THEN 
 match := FALSE
ELSE
BEGIN
 Match := True;  { assume they will match}
 k := 1;

 While (k <= Length( Str1)) AND (match) DO
 IF Str1[k] <> Str2[k] THEN 
 match := False
 ELSE
 k := k + 1;
END;

Listing 1. String Comparisons in Pascal

String compares can be made more efficient than this in Pascal. I chose this example for its simplicity. In comparing strings, we must consider the end points, if the strings are not the same length, they are not equal. If you haven’t been programming in Assembly language, you may not see how this routine could be made more efficient. One measure of a program’s efficiency is a count of the number of bytes of instructions needed to execute the program. If you compile listing 1 and dump the object code, you would discover that the while loop requires 82 bytes of instructions to execute. Assembly language programmers know by instinct that 82 bytes is too much code to perform a single string compare.

An assembly language equivalent of the while loop in listing 1 can be shrunk by an order of magnitude as in listing 2. If you’re trying to speed up a particularly slow loop, a few bytes of well-written assembler might be just what the doctor ordered. But optimizing code is just one reason to familiarize yourself with assembly language. A more compelling reason for the high-level language is that an understanding of assembler will help you make sense of your TMON or MacsBug dumps.

 ; A0, A1 point to the 2 strings
 Move.b (A0)+, D1; get the length of string 1
 Move.b (A1)+, D2; get the length of string 2
 Cmp.b  D1,D2  ; are they the same length?
 Beq  CompareChars ; yes, go ahead and compare them
 Move #0, D0; set the result to false
 Bra  Done; and exit

CompareChars     ; compare Str1<->Str2
 Cmp.b  (A0)+,(A1)+; do the characters match?      
 Beq  Done; yes, see if we’re at end of string
 Dbra D1, CompareChars
 Move #1, D0; they match, set the result true

DONE  sne D0       ; Result is true if strings match,          
 false otherwise

Listing 2. String Compare in Assembler

Entering XCMDs

The real trick to writing an XCMD in assembly language is understanding that HyperCard expects to see an XCMD that was generated by the Pascal compiler. This implies that parameters are pushed on the stack from left to right and that subroutines are responsible for removing the pushed parameters from the stack. XCMDs receive only one parameter so the push order isn’t important. What is important is remembering to remove that parameter from the stack before returning to HyperCard. Listing 3 is the assembly language interface for XCMDs. The fields in the paramBlock record are identical to the Paramblock record in Pascal or C.

On entry to a subroutine in assembly language, the last item on the stack is the return address of the calling routine. Normally, when we are done with the subroutine, an rts (return from subroutine) instruction will pop this return address off the stack and into the Program Counter resuming execution at the instruction pointed to by that location. This won’t do for Pascal routines since convention dictates that we also remove the parameters from the stack. One way to do this would be to pop the return address into a temporary register, say D0, remove the parameters from the stack by adding the size of the parameters to the stack pointer and then pushing the contents of D0 onto the stack and executing an RTS. A more efficient method exists: Pop the return address into an address register, say A0. Unbias the stack parameters by adding 4 to the stack (the size in bytes of the parameter block pointer). Finally, since register A0 contains the return address, execute the Jmp Indirect instruction on A0: Jmp (A0).

Globals in XCMDs

If your XCMD requires local variables, you’re going to need a place to store them. Assembly language XCMDs bear the same restriction placed on high-level languages: you don’t have access to the globals. A simple solution would be to allocate a handle large enough to store all your globals and keep that handle available in an address register. This works fine if the data is very static but not very well otherwise since you could easily run out of registers while manipulating even a small number of handles. Pascal and C use a more efficient approach, one that you’ve already seen if you’ve done any debugging in TMON or Macsbug.

On entry to the subroutine, we know that the stack pointer, register A7, already points to the next available space on the stack (the bottom of the stack). Why don’t we allocate our data on the stack by pointing an address register, say A6, to the bottom of the stack, subtracting the number of bytes that we need for our locals from A7 effectively growing the stack by the amount we need (the stack grows downward). Now A6 points to our local variables and A7 continues its role as stack pointer below our local stack frame (figure 1 ).

The process of creating a stack frame can be performed with one assembly language instruction: link. Used judiciously, the link instruction buys us a whole lot more: it saves the old value of the address register and gives a reference point to the parameters passed by the caller.

By executing link A6,#LocalSize, before doing anything else, we set up up a stack frame at the stack bottom. If stacksize were set to zero, we wouldn’t actually allocate any stack space for globals, but the instruction would still provide a payback. Because nothing else was put on the stack between the call to this routine and our link instruction, A6 also doubles as a pointer to our parameters! First, 0(A6) contains the previous value of A6 (can you think of anything this might be useful for?), next 4(A6) is the return address, and 8(A6) is the paramblock pointer passed to us by HyperCard. By putting 8(A6) into A3, we save the pointer to our parameters in an address register.

The offsets defined in the parameter block equates now become offsets off A3 for each field. The first field in the record is paramCount(A3) the count of the number of parameters in the params array. Accessing the handles in the params array poses another question. The first handle in the array is at params(A3). Getting to the other handles in the params array requires a straightforward application of arithmetic. By definition, handles occupy 4 bytes in the Mac. Any array element, i, is at offset (i-1)*4 byte in the array. We subtract 1 from the element number because array indices count from 0 not from 1. If we put the array index into D0, subtract 1 and multiply by 4 we have the offset from the beginning of the array. All we need to do is add this number to params[A3] and we have the handle. The 68000 has just an instruction: indexed addressing with offset. Here is how this instruction can be used to get the third parameter in the list:

Moveq     #3, D0   ; Access the third parameter in the list 
Sub.w     #1, D0   ; arrays count from 0, not 1
Asl.w     #2, D0   ; shift left by 2 is same as multiply by 4! 
Move.l    params(A3,D0.w), A0 ; A0 now holds the third handle 

Since stack frames are oriented from the highest memory location they occupy to the lowest, local variables are always referred to by negative offsets. In Pascal, the following declaration

VAR
myInt   : INTEGER;
myLong  : LongINt;
myRect  : Rect;

would have the following counterpart in assembly language:

myInt        EQU -4        ; locals start at offset -4 in the frame
myLong  EQU myInt-2; Integers are 2 bytes
myRect      EQU myLong-4  ; longs are 4 bytes
LocalSize EQU myRect-8  ; rectangles are 8 bytes.
LocalSize is equal to 14 bytes.  The stack frame is set up to read:
LINK    A6,#LocalSize; create the local variable pool.
Move.w  (A0),D0

If you’re having a bit of difficulty with this material, try writing a simple XCMD in Pascal or C and disassembling it in TMON or Macsbug. You can do this by invoking the Debugger call as the first statement in you XCMD.

Exiting the XCMD

Leaving the XCMD requires a little house cleaning. First, we restore the registers that were saved onto the stack. Next, we execute an unlink (UNLK) instruction to undo the last Link instruction. At this point, the stack looks just like it did when we entered the XCMD. More importantly (A7) is the return address of the calling routine. Popping this value into A0 allows us to save the return address in a safe place so that we can remove the parameters from the stack. We know how much space the parameters take. The stack contains only one parameter, XCmdBlkPtr, whose length is four bytes. Adding 4 to A7 shrinks the stack to the right size. Now all that’s left is to Jmp to the location pointed to in A0 and we’re done!

Conclusion

If you’re already programming in assembly language, this article is enough to get you started with XCMDs, especially if you’re not familiar with Pascal calling conventions. If you’re a Pascal or C programmer, the above discussion should help you to debug your code by explaining some of the assembly code you may have been looking at in TMON or Macsbug. In any case, understanding how compilers take your statements and convert them into machine executable code is a great way to learn more about the inner-workings of your programs and those seemingly mysterious bugs that just are not obvious in your Pascal or C source code. Hopefully, I’ve been able to fill some gaps in your debugging skills with this information. If the information in this article was useful, please let me know, I’ll be happy to offer more information on assembly language and debugging techniques.


;******************************
;* File: SimpleXCMD.a*
;* *
;* A simple XCMD written in *
;* Assembly language to show*
;* how XCMDs are written in *
;* assembler...  *
;* -------------------------- *
;* By:  Donald Koscheka   *
;* Date:16 July, 1988*
;******************************

;******************************
;* Build Sequence
;*
;* asm -w SimpleXCMD.a
;* link  -rt XCMD=1200 -sn Main=SimpleXCMD
;* SimpleXCMD.a.o
;* -o “YourStackName”
;******************************

;***  ParamBlock structure***
paramCountEQU    0   
params  EQU paramCount+2
returnValue EQU  params+( 16 * 4 )     
passFlagEQU returnValue + 4 
entryPointEQU    passFlag + 2   
request EQU entryPoint + 4  
result  EQU request + 2
inArgs  EQU result + 2
outArgs EQU inArgs + ( 8 * 4 )
pBlkSizeEQU outArgs + (4 * 4 )

;*** ------------------ ***
;*** THE LOCAL VARIABLES  ***
;*** (WILL GO ON STACK)   ***
;*** Note that the stack frame***
;*** counts backwards from 0***
;*** so that the value of ***
;*** LocalSiz will always be  ***
;*** negative    ***

LOCALS  EQU 0
LASTLOCAL EQU    LOCALS
LOCALSIZEQU LASTLOCAL
;*** ------------------ ***


SimpleXCMDMAIN   EXPORT
;******************************
;* In:
;*
;* 0(A7) == Return Address
;* 4(A7) == ParamBlockPtr
;* 
;* Link A6 to create a stackframe
;* that points to these vars.
;******************************

 ;*** Set Up Stack Frame
 LINK   A6,#LOCALSIZ ; Size of the local frame
 MOVEM.LD5-D7/A3/A4,-(SP) ; save some registers
 
 ;*** Get Pointer to paramblock
 MOVE.L 8(A6), A3; Point to parameters
 CLR.L  returnValue(A3) ; set to “empty”
 TST.W  paramCount(A3)  ; Any Parameters?
 BEQ    DONE; no, just return
 
   ;*** Insert your code here.  If your XCMD doesn’t take any 
 ;*** parameters eliminate the atest on paramcount ...
 
DONE    ;*** Prepare for Return to HyperCard
 MOVEM.L(SP)+,D5-D7/A3/A4 ; restore registers
 UNLK   A6; wipe out stack frame
 MOVE.L (A7)+, A0; get the return address
 ADD.L  #4, A7   ; unbias the stack
 JMP    (A0); return to HyperCard
 END

Listing 3. SimpleXCMD in Assembly Language

end HyperChat
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

TextSoap 8.4.1 - Automate tedious text d...
TextSoap can automatically remove unwanted characters, fix up messed up carriage returns, and do pretty much anything else that we can think of to text. Save time and effort. Be more productive. Stop... Read more
TextSoap 8.4.1 - Automate tedious text d...
TextSoap can automatically remove unwanted characters, fix up messed up carriage returns, and do pretty much anything else that we can think of to text. Save time and effort. Be more productive. Stop... Read more
Backblaze 4.3.0.44 - Online backup servi...
Backblaze is an online backup service designed from the ground-up for the Mac. With unlimited storage available for $5 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more
Numi 3.15 - Menu-bar calculator supports...
Numi is a calculator that magically combines calculations with text, and allows you to freely share your computations. Numi combines text editor and calculator Support plain English. For example, '5... Read more
EtreCheck 3.3.3 - For troubleshooting yo...
EtreCheck is an app that displays the important details of your system configuration and allow you to copy that information to the Clipboard. It is meant to be used with Apple Support Communities to... Read more
BusyContacts 1.1.8 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more
TunnelBear 3.0.14 - Subscription-based p...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
Apple Final Cut Pro X 10.3.4 - Professio...
Apple Final Cut Pro X is a professional video editing solution.Completely redesigned from the ground up, Final Cut Pro adds extraordinary speed, quality, and flexibility to every part of the post-... Read more
Hopper Disassembler 4.2.1- - Binary disa...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32-bit and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about... Read more
Slack 2.6.2 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.6.2: Fixed Inexplicably, context menus and spell-check... Read more

Latest Forum Discussions

See All

The best new games we played this week
We were quite busy this week. A bunch of big mobile games launched over the past few days, alongside a few teeny surprises. There're lots of quality games to load your phone with. We've gone and picked out five of our favorites for the week. [... | Read more »
Magikarp Jump beginner's guide
Magikarp Jump is a mystifying little game. Part Tamagotchi, part idle clicker, there's not a whole lot of video game there, per se, but for some reason we can't help coming back to it again and again. Your goal is to train up a little Magikarp to... | Read more »
Goat Simulator PAYDAY (Games)
Goat Simulator PAYDAY 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: ** IMPORTANT - SUPPORTED DEVICES **iPhone 4S, iPad 2, iPod Touch 5 or better Goat Simulator: Payday is the most... | Read more »
GRID Autosport delayed until autumn
Sorry mobile racing fans -- GRID Autosport has been delayed a few months. The game is now expected to launch this fall on iOS. Feral Interactive announced that they wanted more time to work on the game's UI and overall performance before launching... | Read more »
Zombie Gunship Survival Beginner's...
The much anticipated Zombie Gunship Survival is here. In this latest entry in the Zombie Gunship franchise, you're tasked with supporting ground troops and protecting your base from the zombie horde. There's a lot of rich base building fun, and... | Read more »
Mordheim: Warband Skirmish (Games)
Mordheim: Warband Skirmish 1.2.2 Device: iOS Universal Category: Games Price: $3.99, Version: 1.2.2 (iTunes) Description: Explore the ruins of the City of Mordheim, clash with other scavenging warbands and collect Wyrdstone -... | Read more »
Mordheim: Warband Skirmish brings tablet...
Legendary Games has just launched Mordheim: Warband Skirmish, a new turn-based action game for iOS and Android. | Read more »
Magikarp Jump splashes onto Android worl...
If you're tired ofPokémon GObut still want something to satisfy your mobilePokémon fix,Magikarp Jumpmay just do the trick. It's out now on Android devices the world over. While it looks like a simple arcade jumper, there's quite a bit more to it... | Read more »
Purrfectly charming open-world RPG Cat Q...
Cat Quest, an expansive open-world RPG from former Koei-Tecmo developers, got a new gameplay trailer today. The video showcases the combat and exploration features of this feline-themed RPG. Cat puns abound as you travel across a large map in a... | Read more »
Jaipur: A Card Game of Duels (Games)
Jaipur: A Card Game of Duels 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: ** WARNING: iPad 2, iPad Mini 1 & iPhone 4S are NOT compatible. ** *** Special Launch Price for a limited... | Read more »

Price Scanner via MacPrices.net

Memorial Day savings: 13-inch Touch Bar MacBo...
B&H Photo has the 2016 Apple 13″ Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: - 13″ 2.9GHz/512GB... Read more
Apple refurbished 13-inch MacBook Airs availa...
Apple has Certified Refurbished 2016 13″ MacBook Airs available starting at $849. An Apple one-year warranty is included with each MacBook, and shipping is free: - 13″ 1.6GHz/8GB/128GB MacBook Air: $... Read more
Apple restocks refurbished 11-inch MacBook Ai...
Apple has Certified Refurbished 11″ MacBook Airs (the latest models recently discontinued by Apple), available for up to $170 off original MSRP. An Apple one-year warranty is included with each... Read more
12-inch 1.2GHz Retina MacBooks on sale for up...
B&H has 12″ 1.2GHz Retina MacBooks on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: - 12″ 1.2GHz Space Gray Retina MacBook: $1449.99 $150 off... Read more
15-inch 2.7GHz Silver Touch Bar MacBook Pro o...
MacMall has the 15-inch 2.7GHz Silver Touch Bar MacBook Pro (MLW82LL/A) on sale for $2569 as part of their Memorial Day sale. Shipping is free. Their price is $230 off MSRP. Read more
Free Tread Wisely Mobile App Endorsed By Fath...
Just in time for the summer driving season, Cooper Tire & Rubber Company has announced the launch of a new Tread Wisely mobile app. Designed to promote tire and vehicle safety among teens and... Read more
Commercial Notebooks And Detachable Tablets W...
Worldwide shipments of personal computing devices (PCDs), comprised of traditional PCs (a combination of desktop, notebook, and workstations) and tablets (slates and detachables), are forecast to... Read more
Best value this Memorial Day weekend: Touch B...
Apple has Certified Refurbished 2016 15″ and 13″ MacBook Pros available for $230 to $420 off original MSRP. An Apple one-year warranty is included with each model, and shipping is free: - 15″ 2.6GHz... Read more
13-inch MacBook Airs on sale for up to $130 o...
Overstock.com has 13″ MacBook Airs on sale for up to $130 off MSRP including free shipping: - 13″ 1.6GHz/128GB MacBook Air (sku MMGF2LL/A): $869.99 $130 off MSRP - 13″ 1.6GHz/256GB MacBook Air (sku... Read more
2.8GHz Mac mini available for $973 with free...
Adorama has the 2.8GHz Mac mini available for $973, $16 off MSRP, including a free copy of Apple’s 3-Year AppleCare Protection Plan. Shipping is free, and Adorama charges sales tax in NY & NJ... Read more

Jobs Board

*Apple* Media Products - Commerce Engineerin...
Apple Media Products - Commerce Engineering Manager Job Number: 57037480 Santa Clara Valley, California, United States Posted: Apr. 18, 2017 Weekly Hours: 40.00 Job Read more
Best Buy *Apple* Computing Master - Best Bu...
**509643BR** **Job Title:** Best Buy Apple Computing Master **Location Number:** 001482- Apple Valley-Store **Job Description:** **What does a Best Buy Apple Read more
*Apple* Media Products - Commerce Engineerin...
Apple Media Products - Commerce Engineering Manager Job Number: 57037480 Santa Clara Valley, California, United States Posted: Apr. 18, 2017 Weekly Hours: 40.00 Job Read more
*Apple* Mac and Mobility Engineer - Infogrou...
Title: Apple Mac and Mobility Engineer Location: Portland, OR Area Type: 12 month contract Job: 17412 Here's a chance to take your skills to the limit, learn new Read more
*Apple* Retail - Multiple Positions, White P...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.