Applesoft Disassembly

I went looking for a disassembly of Applesoft.
The best one I found was the S-C DocuMentor Applesoft listing which has meaningful labels and comments, but was a little cumbersome to peruse as it was spread over multiple files and lacked hyperlink crossreferences.

So I have created a consolidated and cross-linked version.

the ruby script I used to create this is:

html="<PRE>"
$<.each_line do |line|
 line.gsub!('<','&lt;')
 if line=~/^....-.{21} [J|B]...([A-Z]\S+)\s/
 dest_label=$1
 line[31,dest_label.length]="<a href=\##{dest_label}>#{dest_label}</a>"
 end

 if (!line.include?(" .EQ ") && (line=~/^.{20}([A-Z]\S+)\s/))
 this_label=$1
 line[20,this_label.length]="<b><a name='#{this_label}' id='#{this_label}'>#{this_label}</a></b>"
 end
 line[15,4]="" if line[15,4]=~/\d\d\d\d/
 html+="#{line}" unless line=~/^\s+SAVE /
end
html+="</PRE>"
puts html

Future retro challenge – resurrect the Senior PROM?

About 2 years ago I got interested in “copy cards” for the Apple 2. These are cards that have a button that when it is pressed while make a snapshot of RAM on disk. This lets an executing program be ‘frozen’ and then later restored. The ‘legitimate’ use of these cards is to allow people to save a game at any point, and come back and play it later. The obvious illegitimate use of these sorts of cards is it makes it  easy to make a copy of a game or other program.

These cards are not 100% effective, e.g. they won’t work if a program loads data from a protected disk between levels, but are nevertheless interesting. There is also a lot of overlap between this sort of “copy card”, home made “crack roms”, and legitimate “debugging” cards or ROMs.

Some examples :

As far as I know, there has never been any attempt to recreate any of these devices for the Apple 2 (c.f. the C64 which has the Retro Replay, a clone of the “Action Replay” )

In late 2007, Mike Maginnis (who hosts the magnificent Hardcore Computist archive) and Bill Garber (of garberstreet electronics) made available a scan of manuals and eprom images for Mike’s Senior PROM (accessable from the ‘download’ link Bill’s website, also mirrored here.

The EPROM images came from the version of the Senior PROM built for a beige //e, i.e. for motherboards where there is 1 ROM holding AppleSoft BASIC (residing in $D000..$DFFF) and another ROM holding the Monitor (residing in $E000..$FFFF).

The original Senior PROM consisted of a circuit board that plugged in the place of these 2 chips, and also included a wire that was to be clipped directly onto pin 6 (/NMI) on the 65c02 on the main board. That circuit board also included a button and a 3 position switch.

In the 1st position, the ‘normal’ BASIC & Monitor ROM code is  ative.
In the 3rd position, the special ‘Senior PROM’ code is active – this allows access to utility routines e.g. to save all or part of RAM, a disassembler, a sector editor etc.
In the2nd (middle) position, the system boots as normal, but activates the ‘Senior PROM’ code when the pushbutton is pressed (i.e. at the same time as an NMI is generated).

Since this circuit plugs straight in to EPROM sockets on the motherboard, it was pretty easy for me to replicate (I really only know how to make ‘dead bug‘ style circuits, the PCB fabrication necessary for making a card that plugs into an expension slot is beyond me).

Since I was using a ‘platinum’ //e which has a single EPROM for $D000..$FFFF) I needed to merge the 2 seperate .bin files into a single file ( available here ). Then I burned that merged file into a 27256 that had a toggle switch wired up to A15, and hooked a debounced pushbutton up to the /NMI pin on the 65c02.

This let me boot a single load program using the normal A2 ROM, then flip the toggle switch and trigger an NMI and get into the Senior PROM utilities.

Which was cute, but I was hoping to be able to actually generate a ‘resurrect’ disk, i.e. copy a running program to disk in a way that it could be restarted. Unfortunately the Senior PROM needs a seperate utility disk when it is making the ‘resurrect’ disk, and there didn’t seem to be a copy of that disk available.

There were copies of some versions of the Senior PROM utilities, but they were from different versions of the Senior PROM than the version I had the EPROM image of, and were incompatible. Despite a few plaintive posts on CSA2, I wasn’t able to ever find a matching set of EPROM images and disk images that were from the same version of Senior PROM.

So I gave up.

But just recently, Mike passed on a copy of a Senior PROM utility disk that is from version 3.0 of the Senior PROM which is not quite the same version number as the EPROM image (that is 3.01) but it’s very close and so there’s a good chance they are compatible.

Unfortunately I don’t have access to my old circuits or a workspace to build a new version and test this out in. So I’m posting this in the hope that someone may be interested enough to put together the necessary circuit and see if we really do have a winning combination. Which would be nice!

retro challenge roundup

In at least some parts of the world, it’s still July 31, so I’ll claim this Apple 2 gopher client as being a 1.0 release within the Retro Challenge timeframe. A last minute change of platform, to be sure, mainly because gopher really needs 80 columns. Here’s a screenshot:

A2 Gopher Sreenshot 

To use –

  • You must have an Apple 2 with an uthernet in slot 3 (or at least an emulator like AppleWin), and a functioning DHCP server on your LAN.
  • Press up and down arrows (or ^P / ^N) to scroll up and down between pages.
  • Press TAB to enter a new gopher server (just the server name e.g. gopher.floodgap.com, not a full URL like gopher://gopher.floodgap.com and bad luck if you want to connect to a non-standard port)
  • Press the left arrow (or ^B) to go back to the previously visited location.
  • Press any letter displayed in inverse to navigate to to the adjacent resource (e.g. pressing’c’ in the screen shot above would take you to arfink’s gopher space)
  • There are lots of bugs/issues etc, the most notable being pages over 16KB will crash the client. But hey, at least I hit the launch date. And 16KB should be enough for anyone. Except maybe luddite.

Some reflections:

  • UI design is harder than implementation. I believe that the Mac was the first operating system to provide APIs for applications to use a standard “look & feel”. The coding I’ve done this month is the first major app I’ve ever done where I couldn’t take for granted widgets or common interface metaphors. And it sucks, both as a user and a developer.
  • Although the end product may resemble an authentic Apple 2 application, this was far from an authentic Apple 2 development process. Kudos to the chaps I met from MtKfest who do it “the hard way”. I never could have done this without a decent text editor, google to find RFCs, irc and newsgroups for instant answers to questions, an edit/assemble/execute cycle measured in seconds not hours and all the other conveniences that eliminate the accidental and let one focus on the essential 
  •  State Machines are both a marker and a reducer of complexity. If a design has a state machine, it’s probably solving a complex problem, but it will be simpler (and easier to write) than an alternative design solving the same problem with a diffuse and intertwined set of globals.

notes on an apple iie front panel

I’m working on some ideas that may eventually evolve into a ‘front panel’ for my //e.
The proposed feature list (in descending order of likelyhood that I will have the time & skill to implement):

  • A toggle to flip between a ‘standard’ ROM and a crack-ROM (most likely "Senior PROM")
  • A debounced ‘NMI’ pushbutton
  • A 4 digit readout of the current program counter
  • hardware breakpoints (i.e. an address can be entered through a 4×4 keyboard, and when that address is executed, read or written, an NMI is generated).
  • A ‘single step’ mode.

I intend to use one or more Atmega8 microcontrollers in this. Here are some relevant links so I can keep track of them:

dsktool 0.4.2

I’ve just released version 0.4.2 of dsktool.rb, a command line tool
and library for working with DSK images, written in ruby.

The major changes in this version are:

* DOS 3.3 support now read/write
* NADOL support (read/write)
* ProDOS support (read only)
* Pascal support (read only)
* Hi Res Graphics converted to PNG

Instructions on how to install and get started with dsktool.rb are at
http://dsktool.jamtronix.com

two apple 2 related items

Item the first: 

I’ve turned the ‘Hardcore Computist‘ article index into a web page so
you can navigate from each article directly to the page containing the
article. In the process, I’ve created a mirror of the scans from
http://www.computist-project.net/, so i could link directly to a page.

The article index is at http://computist.jamtronix.com/article_index.html

Item the second:

I’ve released a new version of dsktool.rb. Change log:

V0.2.1
* Added support for NADOL disks (Nibbles Away Disk Optimized Language)
* Added sector viewer to dskexplorer.rb
* DOS 3.3 support now more robust

If you don’t know what NADOL is, it’s the "Nibbles Away Disk Optimized Language" – a simple DOS + Pascal like language orientated towards building scripts for deprotecting disks. But it’s turing complete, and has enough text and graphics commands to allow creation of (for example) a BRICKOUT clone. Docs are at http://www.textfiles.com/apple/DOCUMENTATION/nibbles.away.iii.txt and there’s a DSK image at http://jamtronix.com/dsks/NADOL.DSK 

using dsktool.rb on ubuntu

first install the dsktool gem with sudo gem install dsktool

now try to run dsktool.rb with dsktool.rb -v

If you get an error message like "-bash: dsktool.rb: command not found" then you will need to put the gem bin directory into your path:
open up ~/.bashrc  in the editor of your choice, and at the bottom of the file add 
export PATH=$PATH:/var/lib/gems/1.8/bin
Then save .bashrc, and restart your terminal window.

Now try to view the catalog of an online dsk file:

dsktool.rb http://www.apple2.org.za/mirrors/ftp.apple.asimov.net/images/unsorted/White_Disks/white_25a.dsk.gz -c

Your should get back a listing like:

*T 049 BASICS OF KRACKING 2
*A 00A HELLO
*T 030 KRACKING CYCLOD2
*T 049 BASICS OF KRACKING 3
*T 042 BASICS OF KRACKING 4
*B 01B DEMUFFIN PLUS
*A 003 LIST TEXT FILES: INSTRUCTIONS
*A 003 LIST TEXT FILES
*T 021 KRACKING WAY OUT
*T 047 KRACKING CYCLOD
*T 037 BASICS OF KRACKING 1
*T 01D KRACKING WAY OUT2

Now you can read one of the individual files, like this:
dsktool.rb http://www.apple2.org.za/mirrors/ftp.apple.asimov.net/images/unsorted/White_Disks/white_25a.dsk.gz -e "BASICS OF KRACKING 1" | less
to view one of the classic introductions to removing copy-protection from Apple II disks by Krackowicz

More complete docs can be found at http://dsktool.rubyforge.org/

dsktool.rb

dsktool.rb

dsktool.rb is a command line tool + libraries (all in ruby) for manipulating DSK format images used by Apple 2 emulators. Currently only DOS 3.3 format is supported.

Usage
—–
dsktool.rb [switches]

-c | –catalog               display catalog
-l | –list FILENAME         monitor style listing (disassembles 65C02 opcodes)
-e | –extract FILENAME      extract file by name (either to stdout,
                              or file specified by –output)
-h | –help                  display this message
-o | –output FILENAME       specify name to save extracted file as
-x | –explode               extract all files
-v | –version               show version number

examples:

       dsktool.rb -c DOS3MASTR.dsk
       dsktool.rb -l FID DOS3MASTR.dsk
       dsktool.rb -l fid -o fid.asm DOS3MASTR.dsk
       dsktool.rb -e "COLOR DEMOSOFT" DOS3MASTR.dsk
       dsktool.rb -e HELLO -o HELLO.bas DOS3MASTR.dsk
       dsktool.rb -x DOS3MASTR.dsk

 

Apple //e Soft Switch, Status, and other I/O locations

MEMORY MANAGEMENT SOFT SWITCHES

$C000 W 80STOREOFF Allow page2 to switch video page1 page2
$C001 W 80STOREON Allow page2 to switch main & aux video memory
$C002 W RAMRDOFF Read enable main memory from $0200-$BFFF
$C003 W RAMDRON Read enable aux memory from $0200-$BFFF
$C004 W RAMWRTOFF Write enable main memory from $0200-$BFFF
$C005 W RAMWRTON Write enable aux memory from $0200-$BFFF
$C006 W INTCXROMOFF Enable slot ROM from $C100-$CFFF
$C007 W INTCXROMON Enable main ROM from $C100-$CFFF
$C008 W ALZTPOFF Enable main memory from $0000-$01FF & avl BSR
$C009 W ALTZPON Enable aux memory from $0000-$01FF & avl BSR
$C00A W SLOTC3ROMOFF Enable main ROM from $C300-$C3FF
$C00B W SLOTC3ROMON Enable slot ROM from $C300-$C3FF

VIDEO SOFT SWITCHES

$C00C W 80COLOFF Turn off 80 column display
$C00D W 80COLON Turn on 80 column display
$C00E W ALTCHARSETOFF Turn off alternate characters
$C00F W ALTCHARSETON Turn on alternate characters
$C050 R/W TEXTOFF Select graphics mode
$C051 R/W TEXTON Select text mode
$C052 R/W MIXEDOFF Use full screen for graphics
$C053 R/W MIXEDON Use graphics with 4 lines of text
$C054 R/W PAGE2OFF Select panel display (or main video memory)
$C055 R/W PAGE2ON Select page2 display (or aux video memory)
$C056 R/W HIRESOFF Select low resolution graphics
$C057 R/W HIRESON Select high resolution graphics

SOFT SWITCH STATUS FLAGS

$C010 R7 AKD 1=key pressed 0=keys free (clears strobe)
$C011 R7 BSRBANK2 1=bank2 available 0=bank1 available
$C012 R7 BSRREADRAM 1=BSR active for read 0=$D000-$FFFF active
$C013 R7 RAMRD 0=main $0200-$BFFF active reads 1=aux active
$C014 R7 RAMWRT 0=main $0200-$BFFF active writes 1=aux writes
$C015 R7 INTCXROM 1=main $C100-$CFFF ROM active 0=slot active
$C016 R7 ALTZP 1=aux $0000-$1FF+auxBSR 0=main available
$C017 R7 SLOTC3ROM 1=slot $C3 ROM active 0=main $C3 ROM active
$C018 R7 80STORE 1=page2 switches main/aux 0=page2 video
$C019 R7 VERTBLANK 1=vertical retrace on 0=vertical retrace off
$C01A R7 TEXT 1=text mode is active 0=graphics mode active
$C01B R7 MIXED 1=mixed graphics & text
$C01C R7 PAGE2 1=video page2 selected or aux
$C01D R7 HIRES 1=high resolution graphics 0=low resolution
$C01E R7 ALTCHARSET 1=alt character set on 0=alt char set off
$C01F R7 80COL 1=80 col display on 0=80 col display off

Apple //e links

Apple //e reference manual (PDF – from 1000bit)

Beneath Apple DOS ( PDF – from 1000bit)

Apple II : The DOS manual (PDF – from the Nitrozone Five apple // collection)

Apple II Monitors Peeled (PDF – from the Nitrozone Five apple // collection)

The Computist Project 

ADTPro – Transfers images between modern PC and Apple II

Apple Assembly Line

Zero Page variables 

KRAKOWICZ’S KRACKING KORNER

comp.sys.apple2 newsgroup

Apple 2 Technical Notes 

ProDOS 8 Technical Reference Manual