So What Software

Tag: TextMate

APW-ORCA/M Framework for MacOSX

by on May.29, 2009, under Programming


While dealing with editing my code in TextMate and uploading that to the GS emulator, certain things just begged for automation. Nothing too fancy, just some helpful utilities I have bundled into a framework of sorts. I call it the APW-ORCA/M Framework for MacOSX. It creates and manages projects written in ORCA/M assembly tailored for the AppleIIgs on MacOSX.

Download it: (AWPFrameWork1.1.tar.gz).

I have apw_projects designated as my Apple IIgs assembly language folder so I would put APWFrameWork1.1.tar.gz in that folder, then change directory to that folder and issue a “tar -xzf APWFrameWork1.1.tar.gz”. This will install the framework. You can then delete the tar file “rm APWFrameWork1.1.tar.gz” to save space.

You’re ready to go, first thing is to read the _README file. That will show you how to use the framework properly.

Additionally __LIBRARY/APW-ORCA:M.tmbundle is provided, Click to install this assembly language environment bundle to TextMate. It provides color coded syntax which makes editing APW sourcecode much easier.

Suggested TextMate settings:

Choose “Sunset” theme.
Set TAB SIZE = 15
Set Preferences/Advanced:LineEndings to CR (Mac OS Classic).

The macro generator in the framework is especially handy for generating the macro files and way easier to use than the MACGEN method provided in APW. The libraries are as up to date as possible, including macros for Marinetti. Included as well are some program templates that make the most basic desktop application. Additional tricky or painful templates for popular functions will be included in future releases.

This framework is written in Perl because I am old school and I have been writing  in Perl for more than 15 years. I could have made it in PHP or Ruby but I’m better and quicker writing Perl… the results all wind up the same no matter which high level language you use. By the way… The underlying same-ness of languages is best viewed and understood from the assembly side of things.

I use this framework exclusively for all my IIgs programming projects and have found no bugs, but I’m sure someone out there will find some, it always happens.

As a final thought… If you have been reading along in these postings so far and don’t have APW or ORCA/M, squeeze out a couple bucks and get it here: ( I’m sure “Sheppy” will be thrilled to send you a copy. You can get all the manuals there as well.

Comments Off :, , , , more...

Chapter 3: Disassembly, decoding OMF2 & ExpressLoad

by on Apr.26, 2009, under Programming

Although you probably want to create programs anew, and I’m with you there, knowing how to disassemble code is really important today with such an old system.

Much of the wisdom and the “knowing of things” is lost to time, it’s amazing how much gets discarded. The only real record is in the actual code itself, but you have to decode and decipher to regain that lost wisdom. Even with the most complete documentation library, many things are not still clear and having a good old working example goes miles to filling in those little what the hey’s.

Disassembly is the practice of decoding binary file images and producing a sourcefile. You could do this by hand, reading byte for byte and looking up the meaning of the byte as interpreted at the particular location in the code and translating that to the proper assembly syntax, and of course that would take “deep time” as the cosmologists would say.

A quicker way is to use a disassembler.

These come in all flavors, from the mundane to the sublime. I think I used to have a beta of the ORCA disassembler but that’s long gone, all I have left is the listing from it. I looked around the Internet and the only thing I could find was a Windows based disassembler for the 65816 called D816.

Now, D816 don’t know anything about Apple firmware, software and the like. It’s a generic 65816 disassembler knowing only the microprocessor opcodes and modes but we’re getting ahead of ourselves a bit here.

Let’s backup a notch and deal with the file some more.

The file you want to disassemble will be a ProDOS 8 binary file or relocatable OMF type. Determining which is which will be vital to successful disassembly.

A ProDOS8 binary is filetype BIN($06) but relocatables can be of several filetypes:

GS/OS or ProDOS 16 application S16($B3)
Shell application EXE($B5)
Permanent initialization PIF($B6)
Temporary initialization TIF($B7)
New desk accessory NDA($B8)
Classic desk accessory CDA($B9)
Tool set files TOL($BA)
Apple IIgs device drivers DVR($BB)
Generic loadfile LDF($BC)
GS/OS file system translator FST($BD)

If you want to disassemble a ProDOS8 BIN($06) file then you can go straight to the disassembler, but if you want to do a relocatable filetype (most likely) you need to do some pre decoding, or de-OMFing.

Oh yeah, OMF stands for Object Module Format which is basically how relocatable code it’s still done today, only the specifics have changed, the principle remains the same. All computer code must run at a specific location, it’s ORG. In short, code needs to be relocatable when a robot such as the Toolboxes Memory Manager is in control. It relentlessly works to dole out and keep track of blocks of memory in the IIgs usually at the next most convenient location. It also compacts memory (move things around to create larger available spaces).

Because it chooses where a program will be initially loaded, the code needs to be installed at and re-written for that location.

Because it moves blocks of code around, the code in them has to be re-written to operate correctly at their new location.

That’s why a relocation scheme is necessary, in the case of the AppleIIgs that’s OMF2.

Many of these filetypes can be stripped of OMF segmentation by using the MAKEBIN utility in APW as long as you change the filetype to EXE($B5). If they are multi-segment or  ExpressLoad type however, this trick will not work and MAKEBIN will let you know. One thing about MAKEBIN is that it will ORG the code at $2000 instead of the normal disassembler ORG of $0. Remember this difference for later on.

In tough cases what you need to do is a little hex editing of the file to remove and expand the necessary parts of the code. Many applications use just a few segment types while a few can use the entire list. You need to learn how to read OMF, it’s not that bad but you will need a reference with the OMF segments and headers described. I know this documentation exists in the GS/OS Reference Manual and the APW Reference Manual. It may also appear elsewhere.



Figure#3.1 shows two HexEdit windows where the left one contains a straight OMF2 file and the right one contains an ExpressLoad OMF type of file. The most noticeable difference is that the ExpressLoad header is bigger… it even has the word ExpressLoad in it’s header. De-OMFing either is done the same, it’s just that the header is different, the segment codes however are exactly the same.

I have highlighted the headers in blue for clarity this is Photoshop magic, although HexEdit can do this, it looks better when dolled up in Photoshop for web publication.



We’ll do the easier of the two by doing the OMF2 file on the left, CB.PRELAUNCH. After loading this file into HexEdit I open up a TextEdit window and make some zeroes… several lines of 32 zeroes each this corresponds to each line having 16 bytes ($10). These will be used for type $F1 (DS) segments. See Figure#3.2.



Now that I am setup for decoding OMF lets take a look at exactly what we are up against. Figure#3.3 shows CB.PRELAUNCH with all important regions color coded. Blue is the header and trailing zeroes, Green is LCONST segment headers, Orange is DS segment headers, Purple is the relocation dictionary and yellow is static code bytes (what we are after here). I picked this file because it is simple and also because it will fit on one screen, most programs are a bit bigger than this one.

The key skill involved with this in my opinion is “pattern recognition”, much like as is dramatized in the movie “A Beautiful Mind”. Just remember to never interact with those imaginary people!

The first 64($40) bytes are the header, it has a lot of 00 and 20′s (spaces) all that information means something but for our purposes only one bit is of interest. 8 bytes in there is the pattern “7C 02 00 00″. This is the finished length of the file contained, make a note of this. If you are new to the IIgs, numbers are stored in memory in reverse order what is really being represented is a 4 byte value (long) “00 00 02 7C” or just plain “27C” ignoring the leading zeroes. That’s a number represented in hexidecimal and after a quick tap on the calculator the file will be 636 decimal bytes long. You could of course do this conversion in your head if you were painfully smart. Personaly, I need my calculator set to programmer.



After the header there is another pattern “F2 A2 01 00 00″… a five byte pattern. This is an LCONST($F2) segment header. Once again make note of the last four bytes, they are the length of bytes to follow that contain static program code.  Here we go… Select the first 69($45) bytes which is the header and this segment header and delete them!

Now, index in $1A2 bytes and you will find another pattern: “F1 9A 00 00 00″ immediately followed by another pattern “F2 40 00 00 00″. This is a DS segment header followed by another LCONST segment header. The DS header says to insert $9A(154) zeroes at that point in the code. Go to the TextEdit window with the zeroes and highlight $9A of them, hit



copy and then highlight both of these headers in HexEdit (10 bytes) and hit paste. See Figure#3.4 and Figure#3.5.

Now we’re nearly there, see… I told you it would not be real hard. The last thing to do because we are all out of construction segments is to highlight and remove the relocation dictionary and trailing spaces Figure#3.6. On most code, that’s all there is to it except for their being more DS followed by LCONST headers in the code, do them one by one in sequence and you will not have any problems.




INTERSEG headers can appear when the program is broken down into multiple load segments where each segment has it’s own relocation dictionary, you will come across INTERSEG headers and special relocation headers which have to be dealt with differently. Read up about these segments and it will all become clear. Now you have a properly constructed binary image of the file ORGed at $0… perfect! Save this away to disk as CBPRE.BIN and get ready to stick it in the disassembler.

The next chapter will be a continuation of this chapter but it will actually deal with authentic disassembly, the meat and potatoes of the process, until then try this out a bit and get a feel for relocatable architecture.

As a side note here, if you have the ORCA disassembler then you really don’t need to do any of this stuff because ORCA knows how to read OMF along with a bunch of other stuff and does all this cutting and pasting for you automatically. I just though it would be good background on what’s really happening when you load a relocatable file by telling you this at the end of this section rather than before where you might tend to skip over this vital information.

Next Post: Chapter 3 (cont.): Actual disassembly

Comments Off :, , , , , , , , more...

Chapter 1: The programming environment

by on Mar.26, 2009, under Programming

appleiigsWhere do we start… Probably the best place is the tools and information you would need to start programming. You could blow the dust off your old IIgs and start there but you’re a modern homo sapien and probably have a gig or better machine sitting in front of you. The IIgs mainly ran at 1 megaherts, 2.8 tops and frankly is a bit slow for this type of task. I do my assembly language programming on a modern Mac mini, more than fast enough for the task. Back in the day much work on the IIgs was actually done on the Mac, you will find the two very similar in many ways.

I use the Sweet16 Apple IIgs emulator by Eric Shepard for the IIgs portion of things. This emulator has no drawbacks as far as I can see and is really a brilliant implementation. I use the Apple IIgs Programmers Workshop (APW) and AppleworksGS in the emulator. No other IIgs software is really needed and AppleworksGS is only used for graphics. All other software is either Mac or Windows based. I have not found a place where you can buy a copy of AppleworksGS, I use my original copy purchased in 1988.

On the Mac I have the Sweet16 emulator installed as well as Parallels which runs Window XP. The only thing I use Windows for is to run a 65816 disassembler I found on the web called D816. It’s not the best one I have ever seen but with some coaxing, it produces useable source code segments. There are basically two Mac applications I use in my process, TextMate and HexEdit. Click here for a complete listing of the programming environment.

You may have noticed that I have disassembler capabilities in the environment which usually is not needed for regular programming but, in working with an old system like the Apple IIgs many times I want to upgrade existing software and I don’t have or have lost the source code. The techniques for disassembly are probably just as important for me as is straight forward programming.

With all the hardware in place it’s on to the reference documentation which should be as comprehensive as possible. Most of the documentation is still available from but be prepared to get some 3 ring binders because the reference manuals are only available in 3 hole punched, 2 sided xerox copy form these days. Finding some real old manuals on eBay or Amazon may be preferable or digging through an old timers documentation stash if you know one.

Although this development environment is on modern systems using emulation, you still should have a real Apple IIgs on hand for operational confirmation. There’s nothing like seeing your work running on the real deal. I have a couple machines on hand for these purposes, all Woz’s and they are just too cool for words. It makes people do double takes when they visit seeing an array of computers, some my development machines and some my play machines and some LINUX and Windows machines. Having the odd Apple II, +, C or E is fun too. Fortunately I never throw things out and over the past 30 years I have accumulated a virtual museum of great old equipment.

That’s about all for the preparation so next time we will get down to actually doing something with all this stuff.

Next post – Chapter 2: Dealing with files

Comments Off :, , , , , , , more...

Looking for something?

Use the form below to search the site:

Still not finding what you're looking for? Drop a comment on a post or contact us so we can take care of it!

Visit our friends!

A few highly recommended friends...


All entries, chronologically...