Table of Contents

Copyright © 1994-1996, Michael O'Brien
Copyright © 2001, Oliver Schmidt
Copyright © 2002-2005, Tom Charlesworth
Copyright © 2006-2011, Tom Charlesworth, Michael Pohoreski, Nick Westgate, Linards Ticmanis

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


AppleWin team

Tom Charlesworth (Project lead)

Michael Pohoreski (Debugger rewrite, Half Pixel Video support, Miscellaneous user interface enhancements)

Nick Westgate (Floating bus support, Parallel printer)

Linards Ticmanis (Illegal/undefined opcodes)

Glenn Jones (Uthernet card)

Stannev (Pravets - Bulgarian Apple][ clone)

Ken Wessen (porting CP/M support from Fábio Belavenuto's TK3000 //e emulator)


Acknowledgements

The team would like to thank the following people for their contributions:

Thomas Stahl: TV emulation mode

Chris Foxwell: SSI263 phoneme samples

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

VICE team: TFE, Z80, MC6821 PIA emulation modules (http://www.viceteam.org)
- In particular, Spiro Trikaliotis for TFE, whose code Glenn Jones adapted for Uthernet support

FUSE team: AY-3-8910 module (http://fuse-emulator.sourceforge.net)

Kyle Kim: Mouse card support based on code from Apple in PC

Fábio Belavenuto: TK3000 Brazilian //e clone (originally responsible for integrating Z80Em)

Bob Sander-Cederlof: Applesoft Symbols (http://www.txbobsc.com/scsc/scdocumentor/ S-C DocuMentor: Applesoft)

David Schmidt: Updates to this help file

Mike Harvey, Founder & Editor of Nibble Magazine: For providing us Apple fans the pleasure of eagerly awaiting each next month's issue to learn about the Apple! (http://www.nibblemagazine.net/)


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.

Common programs for doing this work are ADT and ADTPro:

  • Apple Disk Transfer (ADT) - http://adt.berlios.de - runs natively on Windows, but is limited to transferring 5-1/4" disks.
  • Apple Disk Transfer ProDOS (ADTPro) - http://adtpro.sourceforge.net/connectionsserial.html - requires Java, but is capable of transferring all disk types and sizes.

Audio Transfers:

Apples with audio (cassette) jacks can transfer disk images via those ports through audio jacks on a PC. This method is considerably slower than using a serial line, but may be used if the Apple in question lacks a serial port, for example. Common programs for doing this work are ADTPro and Arme Leute Apple Disk Transfer:

  • Apple Disk Transfer ProDOS (ADTPro) - http://adtpro.sourceforge.net/connectionsaudio.html
  • Arme Leute Apple Disk Transfer (Poor Man's ADT) - http://seb.riot.org/appleII/aladt.sml

Ethernet Transfers:

Apples with an A2RetroSystems Uthernet card can transfer disk images via ADTPro:
  • Apple Disk Transfer ProDOS (ADTPro) - http://adtpro.sourceforge.net/configethernet.html

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/utility/nulib.

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 (power-cycles) it if it is currently running. (Use Ctrl+F2 to simulate Ctrl+RESET.)
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.

Shift+Insert:
Paste text from Windows' clipboard. Text gets fed a character at a time to the Apple's keyboard hardware. The 'CR+LF' combination gets converted to CR.

PrintScrn:
Save Apple screen to bitmap. The file is saved to the last directory you opened a disk image from. The default resolution is 560x384. Use Shift+PrintScrn to save a 280x192 bitmap. The filename generated depends if you have a floppy inserted in drive-1 or not. If you do then files are named "{DiskFilename}_#.bmp" otherwise they are named "AppleWin_ScreenShot_#.bmp".

Shift+PrintScrn:
See above.

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

Function Key F2 + Ctrl:
This PC function key combo act like Ctrl+RESET (instead of power-cycle).

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

Function Key F9 + Ctrl + Shift:
This PC function key combo will toggle 50% scanline mode

Function Key F9 + Ctrl:
 This PC function key combo will cycle through AppleWin's character sets: original Apple II charsets and clones' char-sets. This shortcut allows you to override the default character sets of the Apple II model or clone.

Function Key F10 (or Ctrl+left mouse button):
This PC function key will stop emulating an Apple joystick with the PC's mouse.
In Pravets 8A emulation mode it servers as Caps Lock and Ctrl+F10 shall be used to 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 The following are not persisted to the .aws file:

  • Harddisk
  • Phasor
  • Uthernet card
  • Mouse card
  • CP/M SoftCard
  • Parallel Printer card

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


Quick Start

Sound

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.
Additionally the Votrax/SC-01 (predecessor to the SSI263) is emulated by remapping Votrax phonemes to the SSI263's.

Phasor:

When Phasor is enabled, the card is phyically plugged into slot 4 of the Apple //e.

Phasor is equivalent to 2 Mockingboards: so has 4x AY8910 & 1x SSI263.

There are a number of games and demos that support Mockingboard (or Phasor), eg:

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


Save-State Files

Uthernet network card

Overview:

The Uthernet network card coupled with the Contiki OS allows you to browse the internet on your Apple.

Acknowledgment:

Uthernet (TFE) support in Applewin was made possible by implementing the GPL source written by Spiro Trikaliotis for the Vice emulator - http://www.viceteam.org/

Details:

To enable Ethernet support in AppleWin you must first download and install WinPcap.

An Alternative to downloading WinPcap is to get the Ethereal package which includes WinPcap along with Ethereal network analyzer code. To use Ethereal to capture traffic (other then your own) you must be plugged into a shared hub vs a switch. If you plan on doing any network programming ethereal is a definite must have.

WinPcap: http://www.WinPcap.org/install/default.htm or Ethereal:

http://www.ethereal.com/download.html

After AppleWin starts, select the settings ICON and then select the Ethernet settings button.

Uthernet will be disabled. Select Uthernet from the list of available ethernet emulations (currently the only one).

Select the ethernet interface you want to work with. This must be a physical ethernet interface.

If you have more then one interface you may need to select them in turn in order to get the text description for each interface vs what WinPcap likes to use for a reference. Select Ok. and then close AppleWin. *Note:* Wireless does not work with WinPcap.

NOTE: Due to a current limitation you must exit AppleWin and re-run AppleWin for 'a' ethernet interface change to take effect.

In order to test the Ethernet emulation out you should grab a copy of Contiki for the Apple II here - http://www.a2retrosystems.com/downloads.htm

Grab the 80 Col. Primary Disk and Supplementary Disk images if using Apple //e emulation or the 40 Col versions if running Apple II+ emulation. You should also grab a copy of the Uthernet/Contiki getting started guide http://www.a2retrosystems.com/a2UtherManual.pdf

When you run AppleWin again, select the contiki80pri.dsk image. Boot AppleWin.

Once Contiki is loaded then press Enter to clear the welcome screen and press ESC for a menu.

Choose Directory Application and then select configuration edit program. Tab down to the Slot param and change it to '3'. The emulation only works in slot 3.

If you do not have DHCP support in your local Lan then setup your static IP address information here as well. Save and exit. If you have DHCP support in your local lan then press ESC and choose Directory Application again, and then select DHCP client.

Hit enter on request Address and you should see the IP information updated. Close the window and then press ESC again.

Select the web browser and hit Enter a couple of times. Adam Dunkels web site should show up if things are working properly.

Try a few other web sites if the first one isn't working in case it is temporarily down.

You may also need to configure/disable your firewall if you are having problems.

Troubleshooting:

If you have ZoneAlarm running then try disabling it inorder to access the web. if you are still having difficulty then you should refer to the VICE network support page for additional information - http://vicekb.trikaliotis.net/13-005.shtml


Save-State Files

Command line

AppleWin can be driven from the command line as follows:

-d1 <pathname>
Start with a disk in drive-1

-d2 <pathname>
Start with a disk in drive-2

-f
Start in full-screen mode

-r <number of pages>
Emulate a RAMworks III card with 1 to 127 pages (each page is 64K, giving a max of 8MB)

-f8rom <rom-file>
Use custom 2K ROM at [$F800..$FFFF]. <rom-file> must be 2048 bytes long

-printscreen
Enable the dialog box to display the last file saved to

-use-real-printer
Enables Advanced configuration control to allow dumping to a real printer

-noreg
Disable registration of file extensions (.bin/.do/.dsk/.nib/.po)

Debug arguments:

-l
Enable logging. Creates an AppleWin.log file

-m
Disable DirectSound support


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 predecessors of the Apple //e: the Apple ][ and Apple ][+. Besides running with a different Apple system ROM, some differences are discussed below.
  • Apple ][ : Non-autobooting, 64K machine, no lower-case, no 80-column, 6502 CPU
  • Apple ][+ : Autobooting version of the Apple ][
  • Apple //e : 128K machine, lower-case, 80-column, 6502 CPU
  • Enhanced Apple //e : 128K machine, lower-case, 80-column, 65C02 CPU
  • Clone (specific model selectable from Advanced page)
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 (custom) : This mode emulates a monochrome monitor. You can choose your monochrome color from the Monochrome Color button described below.
  • Monochrome (amber/green/white) : Monochrome with specified color.
  • 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).
  • 50% Scan line : Only draw alternate scanline (for better monitor authenticity).

Serial Port:
This option will remap the emulated Apple's serial port to your PC's serial port (or TCP port 1977). The Apple Super Serial Card (SSC) is emulated in slot-2.
The TCP interface to the Apple SSC can be used by the Apple // Game Server. For details see the notes that comes with AGS:

  • Boot the Apple II to AppleSoft (ie. power on and hit Ctrl-Reset) and type IN#2.
  • From a Windows DOS box, start AGS with "localhost 1977 apple2e". This will boot the emulated Apple II from AGS.
  • Nb. Only Enhanced Apple //e is working at the moment.

    Ethernet Settings...:
    This allows to choose which network interface card (NIC) you want to use with the Uthernet card.

    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.
Scroll Lock acts as toggle for full-speed CPU:
  • When checked, you can permanently enable full-speed CPU when Scroll Lock is on.
  • When unchecked, only when Scroll Lock is depressed will you get full-speed CPU.
Mouse interface in slot 4:
  • Disables joystick emulation with mouse.
  • Disables Mockingboard/Phasor in slot 4.
  • Show crosshairs in window's frame:
    • Configure whether you want crosshairs or not
  • Restrict mouse to Apple window:
    • Resticting is useful for paint applications
    • When unrestricted, the emulated mouse is fully integrated with the Window desktop: moving in and out of the AppleWin window will switch between Windows' and the Apple's mouse cursor.
    • NB. Even when unrestricted, you won't be able to move the mouse outside the Apple window for GEOS. This is not a bug.
    • Tip: Use Ctrl+Left Mouse Button to show the Windows mouse cursor (eg. essential for GEOS).
Microsoft CP/M SoftCard interface in slot 5:
  • Emulates a CP/M card, complete with full Z80 emulation.
  • Disables Mockingboard/Phasor in slot 5.
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.


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.
Path to CiderPress:
Use this to specify where CiderPress is installed.
The right button context menu on either of the drive icons allows you to open CiderPress with the image in the drive.


Advanced 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.

Clone:
If you have specified Computer as 'Clone' on the main Configuration page, then this drop-down menu can be used to specify the clone type.
NB. Pravets 82, 8M and 8A are Bulgarian Apple II clones.

Printer settings (Printer is emulated in slot 1)

Printer dump filename:
 Data sent to the printer is stored in a text file. Use this setting to select its location.

Dump to printer:
Use with caution! Enables dumping to a real printer. If disabled, the printout is stored only in printer.txt file in the AppleWin folder. It's recommended to use a printer compatible with the printer selected in the Apple II applications. With modern printers trying to print images will result in printing tens of pages of nonsense. Requires command line switch -use-real-printer.

Encoding conversion for clones:
Characters are encoded from the character set used in the real hardware to ASCII. For Pravets 8 this converts MIK to ASCII. Enabling this could cause problems when printing images.

Filter unprintable characters:
Some characters represent commands for the printer and shall not be printed. When saving them to the printer dump file they may appear as some strange symbols. (You will want to disable filtering when dumping to a real printer.)

Append to print-file:
When disabled, the previous print file is replaced (unless it has a different name) by the newly created print file. Otherwise the newly printed data is added to the existing print file. (You will want to disable appending when dumping to a real printer.)

Terminate printing after idle:
When printing is started, a printer file is created and it is closed either after the specified time expires, or when the emulator is reset. This setting is emulation speed dependent.

The Freeze's non-autostart F8 rom:
If you have specified Computer as 'Apple ][' or 'Apple ][+' on the main Configuration page, then you will be able to enable this setting. The Freeze F8 rom is a hacker's rom that replaces the normal 2K rom at $F800. Here's the original release note


Pravets Clones

Background:

In the 80's Bulgaria was the biggest computer manufacturer in this part of the world. Also - first in the world - for the proportion of manufactured computers per person in the country.

History:

IMKO 1 and IMKO 2 were the first models (circa 1980 and 1982); in 1983 IMKO 2 was renamed to Pravetz 82, because Todor Zhivkov (Bulgarian government and communist party leader at this time) was from Pravetz - a small town, near to Bulgaria's capital city, Sofia.

IMKO 1,2 and Pravetz 82 were almost identical clones of the Apple ][. Then the Pravetz factory built the Pravetz 8M (which was unique at the time) because of its 2 onboard CPU's - 6502 & Z80 (used as a built-in CP/M module). It also had 64 KB of RAM onboard (16 KB as built-in RAM expansion in slot 0).

In the following years they also built: Pravetz 8E, 8A, 8C and 8S - clones of Apple //e.
. 8E didn't have the Cyrillic font, unlike all other models, it had lowercase and capital Latin letters, like original Apple's.
. 8A have 2 additional basic commands, 8 bit code-pages, mini-assembler, allowed the use of hex codes in BASIC and some additional subroutines in the built-in ROM. Unfortunately, some important entry points of the monitor (ROM) program were changed, so it was not 100% compatible with older Apple (and Pravetz) models. This is easily corrected by changing some code (usually JMP in binary programs or CALL, POKE, PEEK in BASIC programs), but not very simple, especially for ordinary users.
. 8C was a stripped down version of 8A (so like the Apple //c) but its size wasn't smaller, like //c. It was without an auxiliary slot of 8A (Apple //e), instead it had 64 KB RAM built-in to its address space. It also had a CM630 CPU (6502 analogue), which had some bugs when used with the CP/M module. 8C also had a built-in RGB module for color monitor (slot 7) and of course the improved 80 column card of the Apple //e, like 8E and 8A.
. 8S was a further improved version of 8C with a possibility to change DRAM chips to 1 MB of memory. (It was possible to do this with Pravetz 8C and the expansion card of 8A: in order to have 1060 MB of memory.)

There were also other Pravetz models:
. 8D was a version of the Oric/Atmos - "D" means "Dom" - "Home" in Bulgarian.
Other models were 16 bit - IBM PC XT and AT clones:
. Pravetz 16, Pravetz 16, Pravetz 16A, Pravetz 16H, Pravetz 16T (with Nec V20 CPU)
. Pravetz 286 (286 CPU), Pravetz 386 (with 386 CPU) and Pravetz 486 - experimental, only a few were manufactured.

Thanks to Stanislav Georgiev for this information.


Advanced Settings

 =-------------------------------------=
=-> Freeze's F-8 ROM  A PPG release <-=
=-------------------------------------=
 The Freeze's F-8 ROM is a modified F-8
rom that has several added features.

-Old Monitor Reset
-Step and Trace modes
-Disassembly with ASCII
-Disassembly with Binary in #Mode
-Better sounding bell!

 These advanced features make Monitor
programming and Cracking much easier.

 There are two ways you can use this
program. Either load it into the RAM
Card using the FREEZE.INSTALL program.
The other way is to burn it onto a
2716 EPROM (Schematics later).

 The only thing that really need an
explanation is the disassembly. In the
disassembly, it displays the ASCII
value of the byte to the right. The
binary numbers on the far right are
displayed when an instruction on the
accumulator in immediate mode is
encountered.

2716 Schematics
===============

 I would suggest that you do these
modifications to a socket rather than
directly to the chip...

 First, cut off pins 21 and 18.
Connect pins 12 and 18
Connect pins 21 and 24
---------------------------------------


AppleWin Debugger Tutorial

By Michael Pohoreski.

Revision 3. Mar 12, 2006.

Table of Contents

  • Introduction
  • Entering the Debugger
  • Scrolling
  • Registers
  • Flags
  • Execution
  • Memory
    • Viewing Memory
    • Searching Memory
    • Changing Memory
  • Symbols
  • Calculator
  • Windows
  • Breakpoints
  • Configuration
    • Colors
    • Fonts
    • Scripts
    • Settings

Introduction

If you're new to the debugger, this tutorial will gently get you up to speed in becoming familiar with it.

If you're already familiar with the AppleWin Debugger, you'll be aware that it was probably lacking in features and ease of use. The new debugger has been given an over-haul for the new millennium with respect to aesthetics and functionality. As such, you'll probably want to read this tutorial to learn about the new features that will not only help you in debugging, but also save you time.

Let's get started on the tour!


AppleWin Debugger Tutorial

Entering the Debugger

Start AppleWin, and press F7 to enter the debugger.

The first thing you'll probably notice is the new syntax coloring in the disassembly view, and info panel. All the colors can be customized to your liking. See the Colors section for details.

Since the mini-console isn't the full width of the screen, you can toggle between the full-screen console with the tilde '~' key. This style of table will be used to designate which keys the debugger will recognize.

Key | Name | Effect
~ ñ` | Tilde Shift-Accent | Toggle full screen console (US keyboards)
ñ/ ñ@ | Shift Forward Slash Shift At | Toggle full screen console (European keyboards)

The debugger will print out a mini message at the bottom of the console when it is first started. Help is built-in for some of the commands (with more coming every release.) Most commands will display a help usage, if you simply type the command and press Enter.

This typeface, and color will be used to designate commands you can type into the debugger.

Input | Effect
HELP | Display Help for specific command.
? | Display Help Summary.
VERSION | Display both the AppleWin and Debugger Version.

Note: Please include both the AppleWin and Debugger version when reporting bugs about the Debugger. Sometimes a preview (Beta) version of the debugger is available before the next official AppleWin version is available. Older bugs (may already) be fixed in the new version. The version number will help both you and the developers to detect if you’re documenting a new bug, submitting an already existing bug, or re-submitting a bug that has already been fixed.


AppleWin Debugger Tutorial

Scrolling

In the disassembly view, the following keys & commands can be used:
(The classic Apple "monitor " disassemble command is also suported.)

Command | Effect
U #### | Start disassembly from Value or Address
####L | List (unassemble) from specified address.

Key | Name | Effect
á | Up Arrow | Scroll up one mnemonic line.
â | Down Arrow | Scroll down one mnemonic line.
ñá | Shift Up Arrow | Scroll up 1 byte.
ñâ | Shift-Down Arrow | Scroll down 1 byte.
PgUp | Page Up | Scroll up one screen.
PgDn | Page Down | Scroll down one screen.
ñPgUp | Shift-Page Up | Jump to prev. page boundary (256 byte).
ñPgDn | Shift-Page Down | Jump to next page boundary (256 byte).
^PgUp | Control-Page Up | Jump to prev. 4K boundary (4096 bytes).
^PgDn | Control-Page Down | Jump to next 4K boundary (4096 bytes).
Home | Home | Jump to start of memory ($0000).
End | End | Jump to middle of memory ($8000).
à | Right Arrow | Locate current 6502 instruction.
à| | Tab | Locate current 6502 instruction.


AppleWin Debugger Tutorial

Registers

The command line now recognizes 6502 Registers. Namely,

  • A, the Accumulator,

  • X, the 1st Index Register,

  • Y, the 2nd Index Register,

  • PC, the Program Counter,

  • S, the Stack Pointer, and

  • P, the Processor Status Register (Flags).

You can set a Register to a hex Value, Symbol, or Expression. (See the section Calculator for more examples of using expressions.) The syntax is:

Command | Effect
R r [=] #### | Set Register to (a byte) Value, Symbol, or Address, or Expression.
R A ## | Set Accumulator to (a byte) Value
R X ## | Set Register X to (a byte) Value
R Y ## | Set Register Y to (a byte) Value
R PC #### | Set PC to (a full 16-bit) Address (Value)
R S ## | Set Stack Register to (an 8-Bit) Offset
R P ## | Set Processor Status Register (flags) to (a byte) Value

Notes:

  • Since A refers to the Accumulator, you need to prefix the hex number A with either:
    i) a zero '0', or
    ii) the hash '#' symbol (same as 6502 immediate symbol.)

  • You can prefix a symbol with the dollar sign '$' to tell the parser it is a symbol Address instead of a Value.

  • If a symbol is not defined, the expression will be the corresponding hex Value, if possible.

  • Hex Values may be ambiguous, if their corresponding symbol is defined. To avoid confusion, don’t define symbols such as the popular $DEAD, $BEEF, $C0DE, $CAFE, etc. An example is given with A1.

Examples:

Input | Effect
R PC FA62 | Set Program Counter to Value $FA62 (RESET)
R PC RESET + 1 | Set Program Counter to Address $FA63 (RESET+1)
R X 2 | Set Register to Value 2
R Y 3 | Set Register to Value 3
R S 1FE | Set Stack Pointer to depth of one (Stack grows down from $01FF)
R S FF | Set Stack Pointer to top of stack (Empty)
R A 0A | Set Accumulator to hex Value 0A
R A #A | Set Accumulator to hex Value 0A
R X A | Set Register X to Accumulator’s Value
R A A1 | If the symbol A1 exists, sets Accumulator to the Address of the symbol A1 If the symbol A1 doesn't exist, sets Accumulator to the hex Value A1
R A $A1 | If the symbol A1 exists, sets the Accumulator to the Address of symbol A1 If the symbol A1 doesn't exist, sets Accumulator to the hex Value A1
R A #A1 | Sets Accumulator to the hex value A1


AppleWin Debugger Tutorial

Flags

Each flag can individually be set or cleared on the Processor Status Register ('P'). Cleared flags will show up with a normal background. Set flags will show with an inverse background.

Notes:

  • The legacy commands R? and S?, where? is a flag name (C,Z,I,D,B,R,V,N) has been left in.

Commands to set a flag:

Command | Description
SEC | Set Carry
SEZ | Set Zero
SEI | Set Interrupts Disabled
SED | Set Decimal (BCD) mode
SEB | Set Break
SER | Set Reserved (not used on 6502)
SEV | Set Overflow
SEN | Set Negative

Commands to clear a flag:

Command | Description
CLC | Clear Carry
CLZ | Clear Zero
CLI | Clear Interrupts Disabled
CLD | Clear Decimal (BCD) mode
CLB | Clear Break
CLR | Clear Reserved (not used on 6502)
CLV | Clear Overflow
CLN | Clear Negative


AppleWin Debugger Tutorial

Execution

As you scroll around, you will notice the cursor and other lines change colors. Normally the cursor line is shown with an inverse bar, that is with a white background. Other colors have these meanings:

Cursor Background | Effect
White | Address of cursor.
Yellow (Bright) | Cursor is on next 6502 instruction (At 6502 PC).
Yellow (Dim) | Line is next 6502 instruction (At 6502 PC).
Red (Bright) | Cursor is on active Breakpoint.

Press Right Arrow to locate the current 6502 instruction. If you Page Down, you can see that Branch Indicators are displayed on the right side of the disassembly window, designated by ‘5’ or ‘6’.

Press Right Arrow to again locate the current instruction. You will also notice immediate instructions have a character single quoted, after them, such as ‘I’ at $FA75.

Pressing Space, will Trace (into) an instruction. Sometimes you trace into a JSR (subroutine), and wish you hadn't. Pressing Shift-Space will "Step Out" - that is, run until the Program Counter (PC) is equal to the return address on the stack. Pressing Left Arrow will jump the cursor to the next instruction after the original call.

Notes:

  • Some code will place the arguments to the subroutine after the JSR instruction. The debugger is not able to detect this and "Step Out" correctly, so use caution, if the sub-routine plays with the stack.

  • The debugger is not able to detect if the top 2 bytes on the stack is a valid return address, so pay careful attention if the stack is modified!

Key | Name | Effect
§ | Space | Trace into instruction.
ñ§ | Shift-Space | Step out of subroutine.
^§ | Ctrl-Space | Trace over instruction.
^â | Ctrl-Down Arrow | Run until cursor.
^à | Ctrl-Right Arrow | Set PC to cursor.
ß | Left Arrow | Jump cursor to return address on stack.

Command | Description
G [StopAddress] | Resume execution until PC = StopAddress.
G [StopAddress] [SkipAddress,Length] | Resume execution until PC = StopAddress. Additionally, if the PC exits the range [SkipAddress,Length], execution will be halted.
####G | Alias for: R PC [=] address.

Input | Effect
R PC FA62 | Set Program Counter to Value $FA62 (RESET)
G C600 D000,3000 | Single-step until either PC = $C600, or PC <= $D000


AppleWin Debugger Tutorial

Memory

Viewing Memory

There are two mini-memory areas on the info panel. You can view memory in Hex, (normal 7-Bit) ASCII, or Apple (8-Bit) TEXT format.

Control characters are shown in yellow. The Apple uses something called 8-Bit (High-Bit) ASCII, in which the first 128 characters (normal ASCII) are also mapped onto the last 128 characters, but with a different background. (Technically, the first 64 characters are drawn inverse, the next 64 characters flashing, and the last 128 normally.) Some programs will store text in this extended Apple format, where a High-Bit character can be used as a flag to represent an end of word.

Here is a summary:

  • Normal ASCII (non-control characters) will show up in cyan; High-Bit text in white.

  • Apple TEXT (normal ASCII) will also display with an inverse background; High-Bit with a normal background.

Command | Effect
M1 #### | View mini-memory 1 in Hex at the Address
M2 #### | View mini-memory 2 in Hex at the Address
MA1 #### | View mini-memory 1 in ASCII at the Address
MA2 #### | View mini-memory 2 in ASCII at the Address
MT1 #### | View mini-memory 1 in “Apple Text” at the Address
MT2 #### | View mini-memory 1 in “Apple Text” at the Address
D #### | Alias for M1

Examples:

Input | Effect
MA1 D0D0 | View Applesoft Tokens (Low ASCII cyan, High ASCII white)
MT2 FF0A | View Apple message displayed when booted, showing Apple Model.
DATA | Switch to the Data Window to view memory. Most scrolling keys work.
CODE | Switch to the Code Window to view the disassembler.

Searching Memory

You can search memory for hex values. Wildcard support is also supported via the '?' wildcard operator, including nibble searching. A single '?' by itself, means match one byte of any value. A hex value with the high nibble or low nibble of '?' will mask off the corresponding nibble. (At the moment there is no way to refer to the list of results. A future version will support _# to reference search result's addresses.)

Searching memory for text is forthcoming in a future version of the debugger.

Command | Effect
SH #,len byte1 … | Search memory for 8-bit hex value(s).
SH #,len word1 … | Search memory for 16-bit value(s).

Examples:

Input | Effect
SH 800,8000 C030 | Search memory for speaker access.
SH 800,8000 AD ? C0 | Search memory for “ LDA $C0xx”.
SH 800,8000 3? C0 | Search memory for speaker access $C03x.
SH 800,8000 ?1 C0 | Search memory for soft-switch $C0x1.
L _1 | Disassemble from search result #1 address. Note: Not yet implemented!

Changing Memory

To change the Apple's memory, the classic "Apple Monitor" command to enter memory is recognized, as well as the "normal" debugger comamnd.

Command | Effect
####:byte1 … | Classic "Apple Monitor" command to enter byte(s). Alias for E.
E addr byte1 … | Set memory to the 8-Bit (byte) value(s).
EB symbol #### | Alias for E.
E8 symbol #### | Alias for E.
EW symbol #### | Set memory (at the symbol Address) to the 16-Bit (word) Value(s).
E16 symbol #### | Alias for EW.
NOP | Writes an “NOP” opcode (EA) at the current Program Counter (PC)
ZAP | Alias for NOP.

Examples:

Input | Effect
300:60 | Same as Applesoft Poke 768,96


AppleWin Debugger Tutorial

Symbols

AppleWin supports loading of ACME, and Merlin Symbol Tables. The default filename read into the Main Symbol Table is “APPLE2E.SYM”.

Looking up symbols is now easier. Can't remember an address of a symbol, or can't remember the symbol for an address? The new symbol commands makes it easy:

Command | Effect
SYM | Display the number of symbols in the Main, User, and Source symbol tables.
SYM #### | Look-up the Symbol or Address, and display which Symbol Table it is in.
SYMUSER LOAD | Loads the User Symbol Table.
SYMUSER CLEAR | Clears the User Symbol Table!
SYMMAIN #### | Look-up only in the Main symbol table.
SYMUSER #### | Look-up only in the User symbol table.
SYMSRC #### | Look-up only in the Source symbol table.
SYM name = #### | Add (or update) a symbol in the User table with the new Address.
SYM ! name | Remove a symbol from the User table.
E symbol ## | Set memory (at the symbol Address) to the 8-Bit (byte) Value.
EB symbol #### | Alias for E.
E8 symbol #### | Alias for E.
EW symbol #### | Set memory (at the symbol Address) to the 16-Bit (word) Value.
E16 symbol #### | Alias for EW.

Examples:

Input | Effect
SYM | Displays number of symbols in the Main, User, and Source tables.
SYMMAIN CLEAR | Clears the main symbol table!!
SYMMAIN LOAD APPLE2E.SYM | Reloads the main symbol table.
SYM FA62 | Look up the Address $FA62 (RESET).
SYM HOME | Look up the Address $FC58 (HOME).
SYM LIFE = 300 | Define a new user symbol, called “Life” at Address $0300.
E LIFE 64 | Set 8-Bit variable (@ $0300)“Life” to 100 (decimal).
EW LIFE 3E8 | Set 16-Bit variable (@ $0300)“Life” to 1000 (decimal).


AppleWin Debugger Tutorial

Calculator

There is a basic mini hex calculator built in. It can do Addition, Subtraction, Division, Modulus, bit-wise And, bit-wise Or, bit-wise Exclusive Or, and bit-wise Negation, with Values, Register and Symbols. It will display results in Hex, Binary, Decimal, and as a Character (single quoted.)

Op | Name | Effect
+ | Plus | Addition.
- | Minus | Subtraction.
% | Percent | Calculate remainder (modulus).
/ | Forward Slash | Calculate quotient.
& | Ampersand | Bit-wise AND.
| | Pipe | Bit-Wise (inclusive) OR.
^ | Caret | Bit-Wise (exclusive) OR, also called XOR.
! | Exclamation | Bit-Wise NOT.

Notes:

  • The unary bit-wise Negation operator, ‘!’ only effects the next immediate expression.

  • There is (currently) no multiplication operator, due to the asterisk ‘*’ being used for the wild card operator.

Input | Effect
CALC 9+1 | Calculate 9+1, in hex.
R A 1 | Set Accumulator to 1.
R X 2 | Set X to 2.
R Y 3 | Set Y to 3.
CALC A+X+Y | Calculate sum of registers.
CALC 1FF-S | Calculate Stack Depth.
CALC BRKV+1 | Calculate address of Break Vector + 1 (First byte is a jump instruction.)
CALC A+#A | Calculate Accumulator plus (decimal) 10.
CALC A+0A | Calculate Accumulator plus (decimal) 10.
CALC A+$0A | Calculate Accumulator plus (decimal) 10.
CALC 0A+0A | Calculate 10 + 10, in hex.
CALC $RESET+1 | Calculate Address of Reset + 1 (First opcode is one byte, CLD).
CALC !HOME | Calculate bit-wise NOT.
CALC X & Y | Calculate bit-wise AND of Register X , Register Y.
CALC X | Y | Calculate bit-wise OR of Register X , Register Y.
CALC X ^ Y | Calculate bit-wise XOR of Register X , Register Y.
CALC X / Y | Calculate division of Register X , Register Y.
CALC X % Y | Calculate remainder of Register X , Register Y.


AppleWin Debugger Tutorial

Windows

Due to the amount of information available, the debugger now features "windows." You can switch to th full screen console to read the help, or to the data window to view memory.

Command | Effect
WIN CONSOLE | Switch to the full screen console. Scrolling keys work.
CONSOLE | Alias
WIN CODE | Switch to the disassembly window.
CODE | Alias
WIN DATA | Switch to the Data window to view memory. Most scrolling keys work.
DATA | Alias

You can cycle between windows, using these keys:

Key | Name | Effect
^à | Ctrl-Tab | Cycle to next Window.
^ñà | Ctrl-Shift-Tab | Cycle to prev. Window


AppleWin Debugger Tutorial

Breakpoints

You now have a variety of options when specifying a breakpoint. Breakpoints can also be disabled, and later re-enabled. This lets ones set a bunch of breakpoints, and quickly re-activate them without having to re-enter the breakpoint logic.

Command

Effect

BPA r [op] value

Adds (conditional) Breakpoint.
Default operator is equal ‘=’
(In a future version, will dispatch to BPX, BPR, BPP, or BPIO.)

BPX
BPX expression
BPX address[,len]
BPX [op] symbol

Add Breakpoint trigger to stop executing when the PC is within the range of the Address, Symbol, or Expression. i.e. Range is: [addr,addr+len)
Default length is 1.
Default comparision operator is equal ‘=’

BP

Currently an Alias for BPX.
(In a future version, will also support Loading and Saving of breakpoints.)

BPM address[,len]

Add Breakpoint trigger when memory is accessed by 6502.

BPR reg [op] value

Add Breakpoint trigger when Register’s ‘reg’ value is compared to the Value.

BPD

Disable Breakpoint (grayed out).

BPE

Enable Breakpoint (colored red).

BPC #

Clear specified Breakpoint.
Note: The asterisk ‘*’ may be used to clear all breakpoints.

BPL

List Breakpoints.

BPIO

(In a future version, will add Breakpoint trigger on memory read or write.)

BPP

(In a future version, will add Breakpoint trigger on specific flag cleared or set.)

The general format for the conditional breakpoint is:

  • BPA register [operator] value.

You can use the following comparison operators:

Op | Name | Effect
= | Equal | Break when register is equal to value.
! | Not Equal | Break when register is not equal to value.
< | Less Than | Break when register is less than value.
> | Greater Than | Break when register is greater than value.

Breaking on any of the 6502 registers is fully supported:

Reg | Name | Effect
A | Accumulator | Break when Accumulator is triggered.
X | Register X | Break when Index X is triggered.
Y | Register Y | Break when Index Y is triggered.
PC | Program Counter | Break when PC is triggered.
S | Stack Pointer | Break when Stack Pointer is triggered.
P | Processor Status (flags) | Break when flags are triggered.

Notes:

  • BPP, Breaking on a specific flag (either set, or cleared) is forth-coming in a future version.

Examples:

Input | Effect
BPX < F000 | Add Breakpoint when PC < $FA62.
BPX PC < D000 | Add Breakpoint when PC < $ D000.
BPR A 0 | Adds Breakpoint when Accumulator is zero.
BPR A ! 0 | Adds Breakpoint when Accumulator is not zero.
BPR S < 1FF | Adds Breakpoint when Stack has had something pushed onto it.


AppleWin Debugger Tutorial

Configuration

Colors

The commands to change color schemes, and colors are:

Command

Effect

COLOR

Switch to color scheme.

MONO

Switch to monochrome scheme.

COLOR #

Displays the Red, Green, and Blue values for the specified color.

COLOR # # # #
COLOR # R G B

Sets the colors to the new Red, Green, and Blue values.
First # is the color.

Some people prefer monochrome (easier on the eyes, in full screen), so you may want to use that setting:

Examples:

Input | Effect
MONO | Switch to the monochrome scheme.
COLOR | Switch to the color scheme.
COLOR 0 10 20 40 | Sets the console background color to slate gray: RGB 10,20,40

Fonts

The font Type, and Spacing can be configured, to show more or less lines in the disassembly window.

Command | Effect
FONT MODE # | Set disassembler line spacing for the current font.
FONT “name” | Switch disassembler to new font.
FONT “name” # | Switch disassembler to new font with specified height (in pixels)

Examples:

Input | Effect
FONT MODE 0 | “Classic” Line Spacing. Shows the fewest amount of lines.
FONT MODE 1 | “Improved” Line Spacing. (Default)
FONT MODE 2 | “Minimal” Line Spacing. Shows the most amount of lines.
FONT “Arial” | Switch disassembler font to Arial.
FONT “Courier New” | Switch disassembler font to Courier New.

Scripts

You can run custom batch or script files that contain debugger commands. Scripts files do not echo their input; to print a string to the output console window, use the ECHO command.

Command | Effect
RUN filename | Runs the specified script filename; the filename may be quoted.
ECHO string | Echo the text to the debugger console. The string may optionally be quoted.

Examples:

Input | Effect
RUN “Test.txt” | Runs the script file called: “Test.txt”
ECHO “Hello World” | Prints the classic “Hello World” to the output console.

Settings

Coming in a future revision, you can save or load your debugger settings, either piece wise, or as a whole.

Command | Effect
CONFIG LOAD | Load (default) debugger configuration.
CONFIG LOAD “filename” | Load (named) debugger configuration
CONFIG SAVE | Save (default) debugger configuration.
CONFIG SAVE “filename” | Save (named) debugger configuration
COLOR LOAD “filename” | Load color configuration.
COLOR SAVE “filename” | Save color configuration
BP LOAD “filename” | Load breakpoint configuration.
BP SAVE “filename” | Save breakpoint configuration

Hope you enjoyed the tour!


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. New releases are also announced here.

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 Developers

To contact the project administrators, email:
Tom Charlesworth
Michael Pohoreski
Nick Westgate

Bug reports should be submitted here:
https://developer.berlios.de/bugs/?func=addbug&group_id=6117

Feature requests should be submitted here:
https://developer.berlios.de/feature/?func=addfeature&group_id=6117

To contact the author of this help file, email:
Brian Broker