Disassembly Notes
A great deal of Apple II source code is written in 6502 or 65816 assembly language. The simplest way to disassemble raw data into something understandable on a real Apple II is to load the program, enter the monitor with "CALL -151", and list the data with the 'L' command ("2000L"). The output seen depends on which model of Apple II you have.
The CiderPress file viewer allows you to create monitor-style code disassemblies that closely match the original. The disassembler is selected automatically for appropriate files.
All files are ranked in a priority scheme by file type. "High" priority means that disassembly is the preferred method for viewing the file. "Medium" means use it if nothing better comes along (e.g. an 8192-byte BIN file will be decoded as a hi-res image rather than disassembled, but both options will be available in the file viewer). "Low" means the option to disassemble will be available, but will be prioritized below converted text or "raw" display.
The "extract files" feature when used in "easy access in Windows" mode will write the converted data to a text file. This is an easy way to dump a monitor listing of a file to disk.
Apple ][, ][+, //e monitor
The classic Apple IIs come with the monitor built into the F8 ROM. It's able to display all 6502 operations as three-letter mnemonic operations and hexadecimal values.
CiderPress emulates this output as closely as possible, but adds two features for convenience. First, the new operations introduced with the 65C02 CPU are properly displayed. Second, annotations have been added to the following:
Files of type SYS, CMD, 8OB, and P8C are categorized "high priority".
Files of type BIN are categorized "medium priority".
Files of type NON and $F1 through $F8 are categorized "low priority".
Apple IIgs monitor
The Apple IIgs monitor introduced a number of new features. The 65816 CPU added several new instructions as well as 24-bit addresses and variable-width registers.
The output of the disassembler closely matches the IIgs output. Annotations have been added to the following:
Disassembly of 65816 code is tricky because the width of the registers can change, which affects the size of instructions with "immediate" mode addressing. CiderPress gives you the option of listing a file with "long" (16-bit) or "short" (8-bit) registers, but does not try to track the mode. Obtaining a complete disassembly of a chunk of code may require listing it twice and merging pieces together.
There is also a preference to control whether BRK and COP commands are displayed as two-byte operations ("BRK 00") or single-byte ("BRK"). The former matches the behavior of the IIgs monitor, but the latter can make the disassembly easier to read in some circumstances, e.g. instructions following an odd number of zeroes.
The IIgs monitor listing mode includes limited OMF (Object Module Format) support. OMF files are broken into segments, and the disassembly restarts at the top of each segment.
Files of type OBJ, LIB, S16, RTL, EXE, PIF, TIF, NDA, CDA, TOL, DVR, LDF, FST and OS are categorized "high priority".
Files of type BIN, SYS, CMD, 8OB, P8C, and NON are categorized "low priority".
Notes
If you want to see a disassembly of a file with the wrong type, e.g. you want to view assembly language code embedded in a BAS or INT file, change the file type to "BIN".
If a disassembly is starting at the wrong address, or you want to change the start address because the code relocates itself early on (fairly common for SYS files), change the file type to BIN and set the aux type to the desired start address.
The annotations on memory locations and OS calls come from a file called NList.Data, which can be found in the CiderPress installation directory. The data file was developed by Dave Lyons as part of the Nifty List desk accessory, and is included with permission of the author. If you want to add additional locations (perhaps Applesoft entry points) or expanded commentary, the file format is pretty self-explanatory.
The format of the Nifty List annotations may not be immediately obvious. The following is an excerpt from the Nifty List v3.4 manual.
------------------------------------
Interpreting the parameter summaries
------------------------------------
Some tools take no parameters and return no information. These
appear with an empty pair of parentheses after the tool name:
GrafOff()
SystemTask()
Tools that take one or more parameters and return no information are
listed like this:
SetPort(@Port)
WriteBParam(Data,Parm#)
An "@" in front of a parameter means it is a pointer and takes 4
bytes (2 words). All parameters not specially marked take 2 bytes
(1 word).
Tools that take no parameters but return one are listed like this:
GetPort():@Port
FreeMem():FreeBytes/4
A "/" and a digit after a parmeter means it takes the specified number
of bytes. (When making a tool call, you must push space on the stack
for any result values *before* pushing the input values.)
A few tools return more than one value. In these cases, the
results are listed in the order they have been pushed onto the
stack (so that the first value PULLED is the last one listed):
GetMouseClamp():Xmn,Xmx,Ymn,Ymx
Each of these values takes 2 bytes (1 word), since there is no
indication of a different size.
Tools that take and return values are listed like this, where a
trailing "H" indicates a Handle (4 bytes):
EqualRgn(Rgn1H,Rgn2H):Flag
-----
Review of parameter sizes:
Leading "@" 4-byte pointer
Trailing "H" Handle (4 bytes)
Trailing "/n" n bytes
All other values are 2 bytes long
-----
For ProDOS calls, the parameters are shown in parentheses even
though they actually belong in a parameter block. For ProDOS 8,
the first item in the list is the parameter count, which should
be in the first byte of the parameter block.
P8:RENAME(2:pn1,pn2)
ProDOS 16 calls (also called class-0 GS/OS calls) do not have a
parameter count.
P16:CHANGE_PATH(@Path1,@Path2)
Class-1 GS/OS calls have parameter blocks beginning with a parameter
count word. Some calls allow a range of values for the parameter
count (like Create, which can take from 1 to 7 parameters), and some
(like Destroy) have a single acceptable value:
GS/OS:Create(1-7:@P,Acc,Typ,Aux/4,Stg,EOF/4,rEOF/4)
GS/OS:Destroy(1:@P)