Table of Contents

Copyright © 1994-1996, Michael O'Brien
Copyright © 2001, Oliver Schmidt
Copyright © 2002-2005, Tom Charlesworth

Acknowledgements

Select one of the following categories:
  • Quick Start
  • Historical Information
  • Disks and Disk Images
  • Using the Toolbar
  • Using the Keyboard
  • Using the Debugger
  • Resources


Acknowledgements

I would like to thank the following for their contributions:

Thomas Stahl: TV emulation mode

Chris Foxwell: SSI263 phoneme samples

Robert Hoem: Harddisk card: source module & f/w


Quick Start

AppleWin runs Apple II programs from disk images, which are single files that contain the contents of an entire Apple floppy disk.

Starting an Apple program is a simple two step process:

  1. Click the Drive 1 button on the toolbar and select a disk image file.
  2. Click the Run button on the toolbar to boot that disk.

After booting, you may use the emulated Apple exactly as you would use a real Apple.

Of course, using an Apple is not much fun unless you have a library of Apple programs to run, so you'll probably want to get some disk images right away. The easiest way to do that is to download images from the Internet; see the Resources section for more information. Or, if you want to learn more about creating your own disk images, see the Disks and Disk Images section.


Historical Information

The Apple II holds a unique position in the history of computing. It was the first truly general purpose personal computer, and the first widely successful one. The Apple II took the personal computer revolution from the garages of hard core hobbyists and brought it into business and into millions of homes around the country.

It was developed largely by one man, Steve Wozniak. He designed the system board, employing a number of tricks which made it easier to build but harder to program. He created a floppy drive interface, a hugely important feature at that time, during a marathon two week session in December 1977. He programmed the Apple ROM's and even wrote the first BASIC interpreter for the Apple.

From the start, the Apple II was a major success, fueling the PC revolution and launching Apple Computer Corporation as a major force in the computer industry. By 1980, Apple Computer's yearly revenues already exceeded 100 million dollars. In December of that year, the company went public, making co-founders Steve Wozniak and Steve Jobs each multi-millionaires.

Although the Apple II had originally been designed for hobbyists and home users, about 90% of them were being sold to small businesses. Apple therefore decided that the successor to the Apple II, the Apple III, should be a serious business computer. When it was released in 1980, it featured more memory, an advanced new operating system, and support for 80-column text and lowercase characters.

When we came out with the Apple III, the engineering staff canceled every Apple II engineering program that was ongoing, in expectation of the Apple III's success. Every single one was canceled. We really perceived that the Apple II would not last six months.

-- Steve Wozniak

However, the Apple III was late and suffered from poor backwards compatibility and a nearly 100% hardware failure rate. Although Apple eventually addressed these issues, they were not able overcome the Apple III's bad reputation. Apple III sales remained poor, while sales of the older Apple II continued to climb.

In 1983, Apple finally returned its attention to the Apple II series, introducing the Apple IIe. The IIe borrowed some features from the failed Apple III, including 80-column text and lowercase support. However, it was at its heart an Apple II, and retained very strong compatibility with the existing base of Apple II software. The Apple IIe was extremely successful, soon selling at twice the volume of its predecessor.

In 1984, Apple released their first portable computer, the Apple IIc. The IIc was very similar to the IIe, but came in a compact case that included the most popular peripherals, such as a disk drive and serial card, built in. It also included an enhanced CPU (the 65c02) and mouse support. However, the public did not embrace the Apple IIc, partly because it was not expandable like the IIe and partly because people incorrectly equated the small size with a lack of power.

Because the Apple IIe continued to be Apple's best seller, Apple returned focus to it in 1985, releasing the Enhanced IIe. This computer featured the same enhanced CPU as the IIc, and also included improved support for 80-column text and lowercase characters. Then, in 1987, they spruced it up with a new keyboard and some other minor hardware changes. This final IIe, called the Extended Keyboard IIe or the Platinum IIe, is the computer that AppleWin emulates.

In 1986, Apple released one more Apple II, the IIgs. Although this computer maintained backwards compatibility with most II and IIe programs, it had a radically new architecture and feature set. It was a 16-bit computer, unlike the previous Apple II's which were all 8-bit. It featured new graphics modes which could display thousands of different colors on the screen at once. And it had an advanced new sound chip that could play fifteen different sounds at once. However, partly because it was poorly marketed and partly because the world had turned its attention to the IBM PC and Apple Macintosh, the IIgs never really took off.


Disks and Disk Images

Select one of the following topics:

  • Introduction to Disk Images
  • Loading Disk Images
  • Creating Disk Images
  • Transferring Disk Images
  • Copy Protected Disks
  • Disk Image Formats
  • Harddisk images


Introduction to Disk Images

Everyone who once used an Apple II and now uses an IBM-compatible PC has the same problem: How can you make the PC read Apple floppy disks? Unfortunately, without special hardware, you can't.

Floppy disks are analog devices, much like cassette tapes. For a computer to store digital data on a floppy disk, it must "encode" the data into an analog format. The Apple II used a method of encoding called Group Code Recording (GCR), while IBM-compatible PC's use the much more standard Modified Frequency Modulation (MFM) encoding. Since this is all done in hardware and cannot be bypassed, it is not possible for a PC program to "reprogram" the floppy drive in such a way that it could read Apple-formatted floppy diskettes.

Therefore, instead of reading and writing disks directly, AppleWin uses disk images. A disk image is a single file, which you can store on your hard drive or on a PC floppy diskette, which contains all of the data from an entire Apple diskette. AppleWin treats an image exactly as if it were a real floppy disk.


Loading Disk Images

AppleWin registers the following file types as "Disk Images": *.bin, *.do, *.dsk, *.nib, and *.po. Double-clicking a disk image in the Windows Explorer will automatically load and boot the disk. While older versions of AppleWin started a new instance of the emulator for every disk started in this manner, current versions of the emulator will simply replace the current disk if there is an instance of the emulator already running.

You may also drag and drop a disk image from an Explorer window to the AppleWin emulator window to load and boot the disk. Dropping the image exactly on one of the drive buttons will insert it only into this drive without booting. For example: drop "Pascal1.dsk" to drive 1 and "Pascal2.dsk" to drive 2, then click the the Run button to bring up UCSD Pascal.

AppleWin now allows you to open a disk as read-only. To do this, click the checkbox for "Open as Read Only" in the Select Disk Image dialog. This works like the physical write-protection mechanism on a real Apple //e floppy disk.

If a Disk Image name is to long to read in the Toolbar, simply pause the mouse cursor over a drive button to get a tool-tip with the full name.


Creating Disk Images

To create a new disk image, all you have to do is tell AppleWin to use an image file which doesn't already exist and the emulator will automatically create a new image file. Specifying a new disk image is like inserting a blank, unformatted floppy disk into a real drive. This means that the image must be formatted by emulator before it can be used. Specifically, this is what you'd do using DOS 3.3:

  1. Load a master DOS 3.3 disk image in drive 1 and boot the emulated Apple.
  2. Click on the Drive 1 toolbar button.
  3. Instead of selecting a disk image from the list, type in a name for a new disk image and press enter.
  4. Type in a program that you want DOS to run whenever this new disk is booted. A simple but useful program is:

    10 PRINT CHR$(4);"CATALOG"

  5. Type "INIT HELLO" to initialize (format) the disk image.

You now have a working disk image, which you can use to save documents or other information. If you want to fill this image with data from a real floppy disk that you have, then you need to "transfer" the disk's data. See the Transferring Disk Images topic for more information.

Please note that not all disk image types supported by AppleWin can be created in this manner. Since there is no way to detect the image type from the image itself, it is determined by the given file extension only. Three extensions are allowed: (.DSK, .DO, .NIB). The first two create a "DOS Order Image" and then latter creates a "Nibble Image". If the extension is completely omitted, ".DSK" will be chosen by default. For more information, see Disk Image Formats.


Transferring Disk Images

Serial Line Transfers:

The most common method of transferring disk images is through a serial line. To do this, you must connect your Apple to your PC with a serial line and null modem, then run one program on the Apple which reads data off the disk and sends it out over the serial line, and another program on the PC which collects data from the serial line and saves it to a disk image file. This system can be difficult to set up initially, but once it is working it is very fast and convenient.

There are a number of files on ftp://public.asimov.net/pub/apple_II/ which contain programs and tips to help you transfer disks in this manner. One noteworthy program is Apple Disk Transfer (adt120.zip), which can simplify the setup process by automatically installing itself on your Apple through a serial line.

Modem Transfers:

If you have a modem and terminal program on both your Apple and PC, you can take advantage of that to transfer disks with very little initial setup. Here's what you do:

  1. Run ShrinkIt! on the Apple to compress a disk image into a single archive file.
  2. Transfer that file over the modem to your PC.
  3. Run Nulib on the PC to uncompress the archive file. Nulib is available from ftp://public.asimov.net/pub/apple_II/.

Transferring Through 3.5" Disks:

One final way to transfer disk images is to copy the data onto a 3.5" disk, and then use a Macintosh to transfer the data from the 3.5" disk into a PC readable format. The advantage of this method is that it does not require a serial card or modem. However, it does involve a number of steps:

  1. Run dsk2file on an Apple IIgs. This will read an entire 5 1/4" disk and save it as a single file on a 3.5" ProDOS disk.
  2. Take the 3.5" disk to a Macintosh and copy the file using Apple File Exchange or the ProDOS File System Extension.
  3. Format a high density 3.5" disk on a PC.
  4. Take this 3.5" disk to the Macintosh and write the image file to it using Apple File Exchange or PC Exchange.


Copy Protected Disks

The process of transferring disk images is complicated by the fact that much of the software published for the Apple II was copy protected.

Software publishers have always looked for ways to prevent people from making unauthorized copies of their software. Today, when you buy a game, it might ask you for a word from a random page of the manual, to ensure that you have purchased the game (complete with manual) and not just copied the disk. Back in the days of the Apple II, publishers were much more direct: they simply tried to make it physically impossible to copy the disk.

Unlike the PC, the Apple II had to perform much of its disk encoding in software. If programmers wanted to get tricky, they could bypass the operating system and do their own encoding, possibly changing the size of the sectors on the disk or the way in which the sectors were identified or stored. This prevented standard operating systems like DOS, along with their standard copying utilities, from accessing the disk.

However, programs which were copy protected in this manner could still be copied with more sophisticated "nibble copiers", which copied each track on the disk bit for bit, rather than copying a sector at a time. Similarly, to get a program like this to run under AppleWin, all you need to do is make a nibble image of the disk.

After nibble copiers became prevalent on the Apple, some software publishers developed tricky new ways of creating disks that even nibble copiers could not copy. It is unlikely that such a disk could be successfully transferred into a disk image.


Disk Image Formats

Disk images can be in a number of different formats, depending on how they were created.

DOS Order Images:

DOS order disk images contain the data from each sector, stored in the same order that DOS 3.3 numbers sectors. If you run a DOS program on the Apple which reads in sectors one by one and then transfers them over a serial line to the PC, you will get a DOS order disk image.

Apple floppy disks contained 35 tracks with 16 sectors per track, for a total of 560 sectors. Each of these sectors contained 256 bytes of information, for a total of 143,360 bytes per disk. Therefore, DOS order disk images are always at least 143,360 bytes long. Sometimes on the Internet you will see a disk image that is 143,488 or 143,616 bytes long; this is probably a DOS order image with extra header information before or after the image. In most cases, AppleWin can automatically detect this and handle it.

ProDOS Order Images:

ProDOS order disk images are very similar to DOS order images, except that they contain the sectors in the order that ProDOS numbers them. If you compress a disk with Shrinkit on an Apple, then transfer it over a modem and uncompress it on the PC, you will get a ProDOS order disk image.

Since ProDOS order disk images contain the same information as DOS order disk images, simply in a different order, they are also about 143,360 bytes long. When you use a disk image of this size, AppleWin attempts to automatically detect whether it is in DOS order or ProDOS order by examining the contents of the disk. If the disk was formatted with a standard operating system such as DOS or ProDOS, AppleWin will successfully detect the format. Otherwise, it will revert to DOS order, which is by far the most common format. To force ProDOS order, give the file an extension of ".PO".

Nibble Images :

Nibble images contain all of the data on a disk; not just the data in sectors but also the sector headers and synchronization areas, all stored in the same encoded format that would be recorded on a real disk's surface. At 232,960 bytes, nibble images are bigger than other images, but they can be useful for making images of copy protected software.


Transferring Disk Images

Harddisk Images

Overview:

A harddisk interface card can be plugged in to slot-7 via the AppleWin Configuration tab labelled Disk. Just check enable harddisk in slot 7.

There is provision to connect two harddisks to this card. This is done by using .hdv files on your PC. Each harddisk can have a maximum capacity of 32MB.

On booting, the Apple will always attempt to autoboot from slot-7 first. If the harddisk card is unplugged (not enabled) then the Apple will then attempt to boot from slot-6 (with the Disk][ interface card in it). To boot a floppy disk with the harddisk card enabled, you can issue PR#6 from an AppleSoft prompt.

You can download sample .hdv images from Asimov (eg. ftp://public.asimov.net/pub/apple_II/images/utility/misc/hardpc.zip).

Warnings:

  • Unchecking enable harddisk in slot 7 whilst the Apple is running will physically unplugging the harddisk card. This can lead to a corrupt .hdv image if the Apple is writing to the harddisk when it is unplugged!
  • Equally, exiting AppleWin can have the same affect.
  • The harddisk state is not currently saved in the save-state image.
  • Copy][+ v7.1 locks up when trying to calculate how many free blocks are available when running a catalog. This is a bug in Copy][+ which is fixed in later versions.


Using the Toolbar

Help | F1 -- Help: Displays the help file that you are currently reading.
Run | F2 -- Run/Reboot: Starts the emulated machine if it is not currently running, or reboots it if it is currently running.
Drive 1: | F3 -- Drive 1: Selects a disk image file for drive 1.
Drive 2: | F4 -- Drive 2: Selects a disk image file for drive 2.
Swap Disks | F5 -- Swap Disks: Swap the disks in drives 1 and 2.
Toggle Window / Fullscreen | F6 -- Window/Full Screen: Toggle between Windowed and Full Screen video mode.
Debug | F7 -- Debug: Displays the actual assembly language instructions that the emulated machine is executing.
Configure | F8 -- Configure: Allows you to customize the emulated machine, and the way the Apple's input and output devices are mapped onto your PC's input and output devices.


Using the Keyboard

The Apple //e keyboard was very similar to the PC keyboard, and most keys correspond directly between the two keyboards. However, there were a few keys on the Apple //e that are not on the PC; these are described below:

Reset:
On the Apple //e, you could usually press Control+Reset to interrupt a running program. With the Apple //e Emulator, you may emulate this key sequence with Ctrl+Break.

Open Apple:
The Open Apple key was first introduced in the Apple //e, and was later renamed to the Apple key. It was similar to Ctrl and Alt on a PC, in that it was used in conjunction with other keys. This key is emulated with the PC's left Alt key, which is in the same position as the Open Apple key on the original //e.

Solid Apple:
The Solid Apple key was introduced on the Apple //e and later renamed to the Option key. This key is emulated with the PC's right Alt key, which is in the same position as the Solid Apple key on the original //e.

Numeric Keypad:
The numeric keypad, introduced on the Extended Keyboard //e, is emulated through the PC's numeric keypad. To enable this feature, turn on Num Lock and make sure the joystick emulation is configured to use something other than the keyboard.

Pause:
Pressing the PC's Pause key will pause emulation. Press Pause again to resume emulation.

Scroll Lock:
Holding down the PC's Scroll Lock key temporarily sets the emulation to full speed (i.e. unthrottled).
NOTE: The status of the PC's Scroll Lock LED is meaningless. The emulator will only run full-speed while the Scroll Lock key is pressed down.

Function Keys F1-F8:
These PC function keys correspond to buttons on the toolbar.

Function Key F9:
This PC function key will cycle through AppleWin's display modes: monochrome, color (normal), color (text optimized) and color (TV emulation). This shortcut allows you to switch display modes without going through the configuration dialog.

Function Key F10 (or Ctrl+left mouse button):
This PC function key will stop emulating an Apple joystick with the PC's mouse.

Function Keys F11-F12:
These PC function keys correspond to saving/loading a save-state file.


Save-state Files

Overview:

The complete1 Apple //e state can be saved to a PC file at any time. This can be useful for continuity across AppleWin sessions or to help with games that don't have a save option.

This is controlled by the AppleWin Configuration tab labelled Save State.

Details:

The entire Apple //e state is saved to a file (.aws). This includes Disk][ (even during r/w operation) and Mockingboards.

1 Currently the harddisk state is not persisted to the .aws file.

Note: Only the file names of the disk images are stored in the .aws (not the full path). This allows you to move your disk image around or distribute them. If AppleWin can't locate the disk image(s), then it will prompt for the new location.

For the file format of the .aws file, see the source file: AW_Structs.h

Configuration: Save State:

From the Save State page:

Save state file name
This is the current save state file which is used for all save state operations.

Save state on exit
Checking this means the Apple's state is automatically saved when you quit AppleWin. Additionally the Apple's state is automatically restored from this file when you re-start AppleWin.

Save State / F11
Save to a save-state file.

Load State / F12
Load from a save-state file.


Quick Start

Video & Sound

Video:

AppleWin can display Apple video in a variety of modes. The display can also be run in a standard window or full-screen.

Monochrome:

This mode emulates a monochrome monitor. You can choose your monochrome color from AppleWin Configuration.

Color (standard):

This mode emulates a standard color monitor.

Color (text optimized):

This mode does a bit of image processing to make text more readable on the hires screen.

Color (TV emulation):

This mode emulates how colors bleed into one another on a TV.

On the hires screen, alternating horizontal lines of color are bled together to form new colors like grey, purple, pink, yellow and aquamarine. This effect was used in commercial games like Karateka and many hires adventures (eg. Mindshadow).

Sound:

AppleWin emulates both the internal speaker (using the PC speaker or sound card) and also the Mockingboard sound card (using a PC sound card).

Use the AppleWin Configuration tab labelled Sound.

If you are using a sound card, then use at least DirectX-9.

Speaker:

You can select PC speaker or sound card:

  • PC speaker: This is not recommended as the quality is poor. It is not usable on Windows 2000 or XP.
  • Sound card: Recommended

Mockingboard:

When the Mockingboards are enabled, the cards are physically plugged into slots 4 and 5 of the Apple //e.

Each Mockingboard is a type 'C': 2x AY8910 (3-channel sound generator) & 1x SSI263 (speech chip)
Each AY8910 is fully emulated (tone, noise & envelope).
Each SY6522 (that controls an AY8910) can generate precise timer interrupts or phoneme-complete interrupts.
Emulation of the SSI263 is basic at the moment and only plays back phonemes at a fixed rate without any support for inflection or filters.

There are a number of games and demos that support Mockingboard, eg:

  • Adventure Construction Set
  • Lady Tut (Mockingboard version)
  • Mockingboard Software (Sweet Micro Systems)
  • Music Construction Set
  • Night Flight
  • Popeye
  • Rescue Raiders v1.3 (Speech only)
  • Skyfox
  • Spy Strikes Back
  • Ultima III (Mockingboard version)
  • Ultima IV
  • Ultima V
  • Willy Byte
  • Zaxxon (Mockingboard version)


AppleWin Configuration

Select one of the following topics:

  • Configuration Settings
  • Input Settings
  • Sound Settings
  • Save-State Settings
  • Disk/Drive Settings


Configuration Settings

Configuration settings Computer:
This describes the mode of emulation. You have the option of emulating the predecessor of the Apple //e, the Apple ][+. Besides running with a different Apple system ROM, some differences are discussed below.
  • Apple ][+ : 64K machine, no lower-case, no 80-column, 6502 CPU
  • Apple //e : 128K machine, lower-case, 80-column, 65C02 CPU
Video:
AppleWin can display Apple video in a variety of modes. The display can also be run in a standard window or full-screen. This option describes the type of video emulation to be used for the emulator. Some differences might be discussed below.
  • Monochrome : This mode emulates a monochrome monitor. You can choose your monochrome color from the Monochrome Color button described below.
  • Color (standard) : This mode emulates a standard color monitor.
  • Color (text optimized) : This mode does a bit of image processing to make text more readable on the hires screen.
  • Color (TV emulation) : This mode emulates how colors would bleed into one another on a TV. On the hires screen, alternating horizontal lines of color are bled together to form new colors like grey, purple, pink, yellow and aquamarine. This effect was used in commercial games like Karateka and many hires adventures (eg. Mindshadow).
Serial Port:
This option will remap the emulated Apple's serial port to your PC's serial port.

Monochrome Color:
This is the color to use when you choose a monochrome video mode.

Emulation Speed Control:
This option let's you control the processor speed of the emulated system. You may choose to use an authentic speed (matching the speed of the original processor from the system) or you can underclock or overclock the emulated processor speed from half-speed to as fast as your PC can emulate.

Benchmark Emulator:
This will run a benchmark test that will show how fast your PC can emulate an Apple //e system with this emulator. In order to run the benchmark, the emulated machine must be reset and you will lose any unsaved work. You will be prompted before you continue this action. The results given are:
  • Pure Video FPS
  • Pure CPU MHz
  • Expected average video game performance (in FPS)


Input Settings

Input settings Joystick Control:
These options allow you to configure up to two joysticks attached to the emulated Apple //e system.
  • Joystick 1/2: Choose the emulation method for joysticks 1 and 2.
  • X/Y-trim: These controls add a trim value to the joystick X/Y offsets when the joystick is centered. Normally central position is X=127, Y=127 so this adds the trim value for PC joysticks & keyboard (centering). If you are using an analog PC joystick, then you should leave these values at 0.
Paste from clipboard:
Pressing this button will allow you to paste text from the Windows' clipboard into the emulated Apple //e.


Sound Settings

Sound settings Sound:
This option allows you to choose how sound is output for the system. Your choices are:
  • Disabled
  • PC Speaker (direct)
  • PC Speaker (translated)
  • Sound Card (recommended)
Volume Control:
These slider controls allow you to control the sound levels of the built-in Apple //e speaker and/or an optional Mockingboard or Phasor speaker.

Mockingboard/Phasor Control:
These options allow you to either enable a pair of Mockingboard sound cards in slots 4 and 5, or enable a Phasor sound card in slot 4, or simply disable any external sound card for the emulated system.


Save State Settings

Save State settings

Save State File Name:
This is the file name to use for save-state files. The default directory is the same as where your AppleWin.exe program is stored.

Save State on Exit:
Checking this box will automatically save the current state of the emulator upon exit. The state will be saved to the file specified above (SaveState.aws by default).

Save State:
Press this button to save the current state of the emulator to the file specified. You can also save the system state during emulation by pressing the F11 key.

Load State:
Press this button to load the specified state file into the emulator. You can also load the system state during emulation by pressing the F12 key.


Disk Settings

Disk settings

Floppy Controller Settings:

Disk Access Speed:
Here you can choose the speed at which the system can access an emulated floppy disk drive. By default, you would want "Enhanced Speed" so that data can be accessed as fast as possible. However, it is also possible that certain programs might depend on the "Authentic Speed" to function properly. This is the speed at which the real hardware would access data from your drives.

Select Disk 1/2:
These buttons allow you to select floppy disk images (.dsk files) to 'insert' into the emulated floppy drives 1 and 2. This can also be done during emulation by using the toolbar or using the F3/F4 keys. Diskettes can be swapped by pressing F5 during emulation.

Harddisk Controller Settings:

Enable harddisk in slot 7:
A harddisk interface card can be plugged in to slot-7 by checking this box. You can connect two harddisks to this card by selecting .hdv files on your PC. Each harddisk can have a maximum capacity of 32MB.

On booting, the Apple will always attempt to autoboot from slot-7 first. If the harddisk card is unplugged (not enabled) the Apple will then attempt to boot from slot-6 (this has the Disk][ floppy interface card in it). To boot a floppy disk with the harddisk card enabled, you can issue PR#6 from an AppleSoft prompt.

You can download sample .hdv images from Asimov (eg. ftp://public.asimov.net/pub/apple_II/images/utility/misc/hardpc.zip).

Select HDD1/HDD2:
These buttons allow you to select harddisk images (.hdv files) to connect to the emulated hard drive controller.

Harddisk warnings:
  • Unchecking enable harddisk in slot 7 while the emulator is running would be like physically unplugging the harddisk card on an Apple that is powered on. This can lead to a corrupt .hdv image if the Apple is writing to the harddisk when it is unplugged!
  • Also, exiting AppleWin while writing to the harddisk can have the same effect.
  • The harddisk state is currently not saved in the save-state image.
  • Copy][+ v7.1 locks up when trying to calculate how many free blocks are available when running a catalog. This is a bug in Copy][+ which is fixed in later versions.


Using the Debugger

AppleWin includes a complete symbolic debugger which you can use to examine the internal workings of Apple programs. If you're interested in writing Apple II assembly language programs or modifying existing ones, you'll find the debugger to be an invaluable aid.

For more information, select one of the following topics:

  • The Debugger Screen
  • Debugger Commands


The Debugger Screen

The debugger screen


Debugger Commands

Select a command:

BC | Breakpoint Clear
BD | Breakpoint Disable
BE | Breakpoint Enable
BP | Breakpoint Set
BW | Black and White
COL | Color
G | Go
I | Input
KEY | Feed Keystroke
MD | Memory Dump
MDC | Code Dump
ME | Memory Enter
MF | Memory Fill
O | Output
R | Set Register
Rf | Reset Flag
Sf | Set Flag
T | Trace
ZAP | Remove Instruction


Debugger Commands

Breakpoint Clear

Syntax:

BC list

BC *

Description:

Permanently removes one or more breakpoints by number, or all breakpoints if the wildcard (*) is used.

Example:

To remove breakpoints one and two, type:

BC 1 2

Breakpoint Disable

Syntax:

BD list

BD *

Description:

Temporarily disables one or more breakpoints by number, or all breakpoints if the wildcard (*) is used.

Example:

To temporarily disable breakpoints one and two, type:

BD 1 2

Breakpoint Enable

Syntax:

BE list

BE *

Description:

Enables one or more breakpoints which had previously been disabled with the Breakpoint Disable (BD) command.

Examples:

To enable breakpoints one and two, type:

BE 1 2

To enable all breakpoints, type:

BE *

Breakpoint Set

Syntax:

BP

BP address

BP addressLlength

Description:

Sets a breakpoint on the given address or range of addresses. If the breakpoint is on a memory location, it will be triggered if the instruction at that location is about to be executed, or if the memory location is read or written to. If the breakpoint is on an I/O port, it will be triggered if the port is accessed.

After setting a breakpoint, use the Go (G) command to start running the emulator in stepping mode. Breakpoint functionality is available only in stepping mode, not in normal running mode.

Examples:

To set a breakpoint at the current execution address (the address contained in the PC register) type:

BP

To set a breakpoint at address $BF00, the ProDOS Machine Language Interface, type:

BP BF00

To set a breakpoint on I/O ports $C0E0-$C0EF, trapping all disk I/O on slot 6, type:

BP C0E0L10

Black and White

Syntax:

BW

Description:

Changes the debugger screen to black and white mode.

Color

Syntax:

COL

Description:

Changes the debugger screen to color mode.

Go

Syntax:

G

G address

Description:

Starts running the emulator in stepping mode. Stepping mode is slower than the normal running mode, but it allows execution to be interrupted by a triggered breakpoint, the escape key, or execution reaching the address given in the Go command.

Example:

To continue execution until the program counter reaches $C27D, the address of WAITKEY1, type:

G C27D

Input

Syntax:

I address

Description:

Simulates reading the specified I/O port.

Example:

To simulate a read of port $C083, switching the banked memory at $D000 from ROM to RAM, type:

I C083

Feed Keystroke

Syntax:

KEY value

Description:

Simulates pressing a key. The given value is passed to the next program that reads the keyboard data port at $C00X.

Example:

To simulate pressing the Return key, type:

KEY 8D

Memory Dump

Syntax:

MD address

Description:

Displays the contents of memory starting at the specified address, in hexadecimal notation.

Example:

To display memory at $BF00, type:

MD BF00

Code Dump

Syntax:

MDC address

Description:

Displays disassembled code starting at the specified address.

Example:

To display code starting at $F832, type:

MDC F832

Memory Enter

Syntax:

ME address value(s)

Description:

Writes the given values to memory locations starting at the specified address.

Example:

To write $A9 to memory location $FBE4 and $0A to memory location $FBE5, type:

ME FBE4 A9 0A

Memory Fill

Syntax:

MF addressLlength value

Description:

Fills a range of memory locations with the given value.

Example:

To fill memory locations $FBE4 through $FBEE with the value $EA, type:

MF FBE4L0B EA

Output

Syntax:

O address value

Description:

Writes the specified value to the given I/O port. If value is not specified, a value of zero is assumed.

Example:

To write $FF to I/O port $C070, type:

O C070 FF

Set Register

Syntax:

R register=value

where register is:

A | Accumulator
X | X index
Y | Y index
PC | Program counter
SP | Stack pointer

Description:

Sets the specified register in the emulated CPU to the given value. The value is adjusted if necessary to fit the valid range of values for the specified register.

Examples:

To set the value in the accumulator to $80, type:

R A=80

To set the program counter to $FA62, type:

R PC=FA62

Reset Flag

Syntax:

Rf

where f is:

N | Sign flag
V | Overflow flag
R | Reserved flag
B | Break flag
D | Decimal flag
I | Interrupt flag
Z | Zero flag
C | Carry flag

Description:

Clears the specified processor status flag.

Example:

To clear the carry flag, type:

RC

Set Flag

Syntax:

Sf

where f is:

N | Sign flag
V | Overflow flag
R | Reserved flag
B | Break flag
D | Decimal flag
I | Interrupt flag
Z | Zero flag
C | Carry flag

Description:

Sets the specified processor status flag.

Example:

To set the decimal flag, type:

SD

Trace

Syntax:

T

T count

Description:

Executes one or more instructions at the current program counter (PC) location.

Example:

To execute five assembly language instructions, type:

T 5

Remove Instruction

Syntax:

ZAP

Description:

Removes the current instruction (the instruction to which PC points) by replacing it with one or more NOP instructions.


Resources

Select one of the following categories:

  • Internet Newsgroups
  • Internet FTP Sites
  • Contacting the Author


Internet Newsgroups

comp.emulators.apple2
This newsgroup is an excellent source of information about Apple II emulation, and the best place to post questions, requests, and suggestions.

comp.emulators.announce
If you are only interested in hearing announcements of new emulator products and new versions of AppleWin and other emulators, you may want to subscribe to this newsgroup instead of comp.emulators.apple2. This newsgroup is also a good place to look for answers to frequently asked questions.

comp.sys.apple2
This newsgroup is for general discussion and questions about the Apple II series of computers.

comp.sys.apple2.programmer
This newsgroup is a good source of information about programming the Apple II series of computers.


Internet FTP Sites

Before transferring a program or disk image through FTP, make sure to configure your FTP client for binary transfer mode. With most FTP clients you can do this by simply typing the word "binary".

ftp://public.asimov.net/pub/apple_II/
This site is the largest Apple II emulation site, and the official release point for new versions of AppleWin. Under the /pub/apple_II directory, you will find disk images, utilities for making your own disk images, and Apple emulators for other computers and operating systems.


Contacting the Author

To contact the author of this program, email:
Tom Charlesworth (tomcharlesworth@blueyonder.co.uk)

To contact the author of this help file, email:
Brian Broker (brian_broker@yahoo.com)