Table of Contents

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

AppleWin team
Acknowledgements

Select one of the following categories:
  • Quick Start
  • Historical Information
  • Disks and Disk Images
  • Using the Toolbar
  • Using the Keyboard
  • Save-state Files
  • Command line
  • Sound
  • Clock
  • Super Serial card
  • Uthernet network card
  • AppleWin Configuration
  • Using the Debugger
  • Resources
  • Appendix


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)

Sheldon Simms (2x windowed mode & NTSC emulation)

Oliver Schmidt (Consulting)


Acknowledgements

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

Brian Broker: This HTML / CHM help file

Thomas Stahl: TV emulation mode (up to v1.25.0.4)

Greg Hedger: SSI263 phoneme samples

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

VICE team: TFE, Z80, MC6821 PIA emulation modules (http://vice-emu.sourceforge.net/index.html#developers)
- 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.com/)

Andrea Odetti: numerous pull-requests

Iván Izaguirre: Taiwanese Copam Base64A Apple II clone

Arnaud C: debugger suggestions and help with 6502/6522/video timing issues

Cyril Lambin: RGB card/monitor rendering, debugger improvements


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
  • Hard Disk 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 registers1 the following file types as "Disk Images": *.do, *.dsk, *.nib, *.po and *.woz. Double-clicking a disk image in 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 (and reboot) 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 too long to read in the Toolbar, simply pause the mouse cursor over a drive button to get a tool-tip with the full name.

Under the vertical Toolbar, are 2 LEDs, one for each floppy disk drive. The colors indicate drive status:

  • Black: drive is off
  • Green: drive is reading
  • Red: drive is writing
  • Orange: drive is reading (and floppy is write-protected)

    By default the Disk II Controller card has the 16-sector firmware (as used by DOS 3.3 and ProDOS). But if a WOZ image that internally identifies as 13-sector format (eg. DOS 3.2) is put into drive 1, then from the start-up/logo screen (or the next reset), the Disk II Controller card's firmware will automatically be switched to the old 13-sector firmware, allowing the disk to boot. And it will automatically switch back if a non-13-sector WOZ (or any non-WOZ) image is put into drive 1 and the machine is reset.
    NB. There is no support for this feature for non-WOZ images.

    1 To register the file types in Windows Vista, Windows 7 and Windows 10, you will need to run AppleWin with elevated privileges. This only needs to be done once. Right click the AppleWin.exe icon and select 'Run as Administrator'.


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. Four extensions are allowed: (.DSK, .DO, .NIB, .WOZ). The first two create a "DOS Order Image", .NIB creates a "Nibble Image" and .WOZ creates an empty .WOZ 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) - https://github.com/david-schmidt/adt - 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. Such a disk can only be transferred onto a WOZ disk image using the AppleSauce hardware & software.


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.

2mg Images:

2mg (or 2img) images are a wrapper around DOS, ProDOS or Nibble images. They contain extra meta-data describing for example, DOS volume number and write-protection.

WOZ Images:

The WOZ Disk Image format is an offshoot of the Applesauce project. Capturing highly accurate bit data is of no use if you don't have a container to hold the data. The WOZ format was designed to be able to contain every possible Apple ][ disk structure and layout. It can be so accurate that even copy protected software can't tell that it isn't an original disk.

Compressed Images :

All of the above can optionally be either gzip'ed or zipped. If a zip archive contains multiple files, then AppleWin only supports using the first file. For best results with hard disk images, uncompress first, as writing back to the image requires a full image re-compression after every block write. Examples of typical extensions are:

  • .gz, .dsk.gz, .nib.gz, .2mg.gz, .woz.gz
  • .zip, .dsk.zip, .nib.zip, .2mg.zip, .woz.zip


Hard Disk Images

Overview:

A hard disk controller (or interface) card can be plugged in to slot 7 via the AppleWin Configuration tab labelled Disk. Just check Enable hard disk controller in slot 7.

There is provision to connect two hard disks to this card. This is done by using .hdv or 800KB .2mg files on your PC. Each hard disk can have a maximum capacity of 32MB.

NB. The hard disk controller supports both fixed-disk types (up to 32MB) and 3.5" floppy types (800KB).

On booting, the Apple will always attempt to autoboot from slot 7 first. If the hard disk 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 hard disk card enabled, either hold down the Open-Apple key during an Apple II restart or issue PR#6 from an AppleSoft prompt.

Warnings:

  • Unchecking Enable hard disk controller in slot 7 whilst the Apple is running will physically unplugging the hard disk card. This can lead to a corrupt .hdv image if the Apple is writing to the hard disk when it is unplugged!
  • Equally, exiting AppleWin can have the same affect.
  • 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 or Ctrl+Break to simulate Ctrl+Reset.)
Drive 1: | F3 -- Drive 1: Selects a disk image file for drive 1. Use the right mouse button for a context menu to "Eject", "Read / Write", "Read only" or "Send to CiderPress".
Drive 2: | F4 -- Drive 2: Selects a disk image file for drive 2. Use the right mouse button for a context menu to "Eject", "Read / Write", "Read only" or "Send to CiderPress".
Swap Disks | F5 -- Swap Disks: Swap the disks in drives 1 and 2.
Toggle Window / Fullscreen | F6 -- Window Size/Full Screen: Toggle between windowed and full screen video modes. (Use Ctrl+F6 to toggle between 1x and 2x window sizes.)
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+F2 or 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 (or Alt Gr 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.

Caps Lock:
On start-up, AppleWin always begins with the Apple II's Caps Lock enabled, regardless of the current state of the PC's Caps Lock key.

  • Assuming Caps Lock is off, when you press the PC's Caps Lock key the first time, this will enable the PC's Caps Lock. AppleWin will see this but remain in the Caps Lock enabled state.
  • Now pressing the PC's Caps Lock key a second time, AppleWin will disable Caps Lock and allow lower-case to be used.
  • Subsequent toggling of the PC's Caps Lock key will continue to be tracked and replicated by AppleWin.
Of course, for lower-case you must be emulating a //e, Enhanced //e or cloned //e (so not a II or II+).

Also in AppleWin's UI, there is a little icon in the bottom right of the window which shows either 'A' or 'a' to reflect the current state of the emulated Apple II's Caps Lock.

Scroll Lock:
Scroll Lock key can be configured to toggle normal/full-speed mode, or only enable full-speed when pressed. See Input for configuring how Scroll Lock behaves. NOTE: The status of the PC's Scroll Lock LED is meaningless.

Ctrl+0, Ctrl+1, Ctrl+3:
Hotkeys to change emulation speed:

  • Ctrl-0 Toggles between custom speed and Full-Speed
  • Ctrl-1 Sets 1 MHz
  • Ctrl-3 Sets Full-Speed

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.

Ctrl+PrintScrn:
Copy the text screen (auto detect 40/80 columns) to the clipboard.

Alt+Enter:
Default: Toggle between windowed and full screen video modes. (NB. Will conflict with emulation and prevent Open Apple + Enter from being readable. Use the Command Line switch to allow Open Apple + Enter to be readable.)

Ctrl+Left Mouse Button:
This will show the Windows mouse cursor when emulating an Apple joystick with the PC's mouse or using a Mouse card.

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

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

Function Key F6 + Ctrl:
This PC function key combo toggles between 1x and 2x window sizes.

Function Key F9:
This PC function key will cycle through AppleWin's display modes: monochrome (custom), Color Monitor, B&W TV, Color TV, 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 F10:
In //e or Enhanced //e emulation mode it will emulate the rocker switch for European video ROM selection. Use the Command Line switch to use an alternate European video ROM file.
In Pravets 8A emulation mode it servers as Caps Lock.

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.

The state can optionally be automatically saved on AppleWin exit, and (automatically) restored on AppleWin restart.

This is all controlled by the AppleWin Configuration tab labeled Advanced.

Details:

The entire Apple //e state is saved to a human-readable (.yaml) file.

1 The following are persisted to the file:

  • Apple model: ][, ][+, //e, Enhanced //e or clone (eg. Pravets)
  • Apple ]['s slot-0 language card: 16K Language Card, Saturn 64K or Saturn 128K
  • Apple //e's auxiliary card: 80 Column, Extended 80 Column or RamWorks III
  • Disk][ (even during r/w operation)
  • Hard disk (even during r/w operation)
  • Mockingboard
  • Phasor
  • Mouse card
  • CP/M SoftCard
  • Parallel Printer card
  • Super Serial card
  • No-Slot clock
The following are not yet persisted to the file:
  • Uthernet card
  • SAM card
  • Using The Freeze's F8 ROM
  • Alternate F8 ROM
  • Alternate ROM
  • Alternate video ROM

Note: Only the file names of the disk images are stored in the .yaml file (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.

NB. Loading of the old v1 file format (.aws file) is no longer supported. Use AppleWin 1.27.13 to load it at the AppleWin start-up/logo screen, then immediately save it (and it'll be saved in the v2 format).


Command line

AppleWin can be driven from the command line as follows:

-conf <pathname>
Use an INI file for configuration instead of the Registry.

-current-dir <path>
This is guaranteed to be processed after all the image loading switches (eg. -d1, -h1, etc).
Use this switch if you have a mix of (eg) -d1 and -h1 loading images from different folders, and you want to guarantee the current dir.

-d1 <pathname>
Start with a floppy disk in slot 6 drive-1 (and auto power-on the Apple II).
NB. -s6d1 has the meaning same as -d1.

-d2 <pathname>
Start with a floppy disk in slot 6 drive-2.
NB. -s6d2 has the meaning same as -d2.

-s5d1 <pathname>
Start with a floppy disk in slot 5 drive-1 (must be used with '-s5 diskii').

-s5d2 <pathname>
Start with a floppy disk in slot 5 drive-2 (must be used with '-s5 diskii').

-h1 <pathname>
Start with hard disk 1 plugged-in (and auto power-on the Apple II). NB. Hard disk controller card gets enabled.

-h2 <pathname>
Start with hard disk 2 plugged-in. NB. Hard disk controller card gets enabled.

NB. For -d1,-d2,-s5d1,-s5d2,-h1,-h2, if pathname is "", then the disk is ejected or the harddisk is unplugged.

-model <apple2|apple2p|apple2jp|apple2e|apple2ee>
Select the machine model: Apple II, Apple II+, Apple II J-Plus, Apple //e, Enhanced Apple //e.

-clock-multiplier <value>
Where value is between 0.5 and 3.9, and is a base-clock multiplier, roughly mapping to 0.5MHz - 3.9MHz

-s0 <saturn|saturn64|saturn128>
Insert a Saturn 64K or Saturn 128K card into slot 0 in the Apple II or II+ machines (or similar clone).
Where -s0 saturn is an alias for -s0 saturn128.

-s0 <languagecard|lc>
Insert an Apple 16K Language Card into slot 0 in the original Apple II and use the F8 auto-start ROM.
NB. The Apple II+ already defaults to having a Language Card, so this switch is not required.

-s1 empty
Remove the printer card from slot 1.

-s2 empty
Remove the SSC card from slot 2.

-s3 empty
Remove the Uthernet card from slot 3.

-s5 diskii
Insert a 2nd Disk II controller card into slot 5.

-s6 empty
Remove the Disk II controller card from slot 6.

-s7 empty
Remove the hard disk controller card from slot 7.
Useful to allow a floppy disk to boot from slot 6, drive 1. Use in combination with -d1.

-s7-empty-on-exit
Remove the hard disk controller card from slot 7 on AppleWin exit.

-no-nsc
Remove the No-Slot clock (NSC).

-r <number of pages>
Emulate a RamWorks III card with 1 to 127 pages (each page is 64K, giving a max of 8MB) in the auxiliary slot in an Apple //e machine.

-load-state <savestate>
Load a save-state file (and auto power-on the Apple II).
NB. This takes precedent over the -d1, -d2, -s#d#, -h1, -h2, s0-7, -model and -r switches.

-f
Start in full-screen mode

-fs-height=<best|nnnn>
Use to select a better resolution for full-screen mode.
  • best: picks the highest resolution where the height is an integer multiple of (192*2)
  • nnnn: select a specific resolution with height=nnnn pixels
NB. This changes the display resolution (and restores on exit).

-rom <file>
Use custom 12K ROM (at $D000) for Apple II machine, or 16K ROM (at $C000) for Apple //e machine.

-f8rom <file>
Use custom 2K ROM for any Apple II machine at [$F800..$FFFF]. <file> must be 2048 bytes long.

-videorom <file>
Use an alternate custom 2K video ROM for Apple II or II+ machines (but not clones).
Use an alternate European or custom 4K, 8K or 16K (top 8K only) video ROM for the original or Enhanced //e (but not clones).

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

-no-printscreen-key
Prevent the PrintScreen key from being registered

-no-hook-system-key
Prevent certain system key combinations from being hooked (to prevent the emulator from trapping ALT+ESC, ALT+SPACE, ALT+TAB and CTRL+ESC). This means that the equivalent Open Apple+<key> combinations won't work within the emulator.
NB. This switch takes precedence over -hook-alt-tab and -hook-altgr-control.

-no-hook-alt
Prevent the left and right ALT keys from being hooked (eg. to prevent emulation of Open/Solid Apple keys via the ALT keys).

-hook-alt-tab
By default the emulator doesn't hook ALT+TAB. Use this to allow Open Apple+TAB to be readable by the emulated machine.

-hook-altgr-control
By default the emulator doesn't suppress AltGr's (Right Alt's) fake LEFT CONTROL. Use this to suppress this fake LEFT CONTROL to allow Solid Apple+CTRL+<key> to be readable by the emulated machine.
NB. Suppressing this fake LEFT CONTROL seems to prevent international keyboards from being able to type certain keys.

-altgr-sends-wmchar
Use this switch to allow Solid Apple (AltGr) to be used in combination with regular keys.
When AltGr is pressed, Windows only sends a WM_CHAR message for (eg) international key codes; and so by default the emulator doesn't explicitly send a WM_CHAR message for regular keys when AltGr is being pressed.
NB. Using this switch may prevent international keyboards from being able to type certain keys.

-left-alt-control-buttons
Use Left Control & Left Alt for Open Apple & Solid Apple keys respectively.
Caveat: Left Control + F2 will do the //e Ctrl+Open Apple+RESET (as Left Control is now both Ctrl and Open Apple!). A workaround is just to use the Right Control key.

-right-alt-control-buttons
Use Right Alt (AltGr) & Right Control for Open Apple & Solid Apple keys respectively.
Caveat: Right Control + F2 will do the //e self test (as Right Control is now both Ctrl and Solid Apple!). A workaround is just to use the Left Control key.

-swap-buttons
Swap the Windows keys used for Open Apple & Solid Apple keys.

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

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

-memclear <n>
Where n is [0..7]:
  • 0 Initialize memory to zero
  • 1 Initialize memory to random values
  • 2 Initialize memory to 4 byte pattern: FF FF 00 00
  • 3 Initialize memory to even pages FF, odd pages 00
  • 4 Initialize memory to first half page 00, last half page FF
  • 5 Initialize memory to first half page FF, last half page 00
  • 6 Initialize memory to byte offset of that page (current memory address low byte) i.e. 00:00 01 02 03 ... for page $20
  • 7 Initialize memory to page address (current memory address high byte) i.e. 00:20 20 20 20 ... for page $20
-modem
Shorthand for passing -dcd
Use with GBBS Pro (or any other BBS package). See the GBBS Pro 2.2 book from Call-A.P.P.L.E.

-dcd
For the SSC's 6551's Status register's DCD bit, use this switch to force AppleWin to use the state of the MS_RLSD_ON bit from GetCommModemStatus().

-alt-enter=<toggle-full-screen|open-apple-enter>
Define the behavior of Alt+Enter:
  • Either: Toggle between windowed and full screen video modes (default).
  • Or: Allow the emulated Apple II to read the Enter key state when Alt (Open Apple key) is pressed.
-rgb-card-type <apple|sl7|eve|feline>
  • apple is Apple's Extended 80-Column Text/AppleColor Adaptor Card (default).
  • sl7 is Video-7's RGB-SL7 card.
    • NB. Both these apple/sl7 cards support an extra foreground/background hi-res mode that can be triggered by AN3 switching, resulting in corrupt color graphics! See troubleshooting.
  • eve/feline are Le Chat Mauve variants.
Use in conjunction with the 'Color (RGB Card/Monitor)' video mode.

-rgb-card-foreground <n>
-rgb-card-background <n>
Where n is [0..15]. Defaults are foreground=15(White) and background=0(Black).
The only supported DIPSW colors are: Black=0, Blue=6, Orange=9, Green=12, White=15
NB. Only supported by '-rgb-card-type <apple|sl7>'.
Use in conjunction with the 'Color (RGB Card/Monitor)' video mode.

-rgb-card-invert-bit7
Force the RGB card to invert bit7 in MIX mode. Enables the correct rendering for Dragon Wars.
Use in conjunction with the 'Color (RGB Card/Monitor)' video mode.

-50hz
Support 50Hz(PAL) video refresh rate and PAL 1.016MHz base CPU clock.

-60hz
Support 60Hz(NTSC) video refresh rate and NTSC 1.020MHz base CPU clock (default).

-power-on
Force a power-on.
Use to auto power-on when not using -d1, -h1 or -load-state.

Debug arguments:

-l or -log
Enable logging. Creates an AppleWin.log file.

-m
Disable DirectSound support.

-no-printscreen-dlg
Suppress the warning message-box if AppleWin fails to capture the PrintScreen key.

-screenshot-and-exit
For testing. Use in combination with -load-state.


Sound

Sound:

AppleWin emulates the internal speaker, the Mockingboard (or Phasor) sound card and also the SAM card; using a PC sound card.

Use the AppleWin Configuration tab labelled Sound.

If you want to use a sound card then use at least DirectX 9.

Speaker:

You can now only emulate this with a sound card.

Mockingboard:

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

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 physically plugged into slot 4 of the Apple II.

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
  • Bejeweled (with SSI263 speech)
  • Berzap! (with SSI263 speech)
  • Broadsides
  • Crimewave (Votrax speech)
  • Crypt of Medea (Votrax speech)
  • Cybernoid Music Disk
  • French Touch demos, eg. (NOT SO) Cheap Tunes, Plasmagoria, Raster Bars + many others
  • Lady Tut (Mockingboard version)
  • Mockingboard software (Sweet Micro Systems)
  • Music Construction Set
  • Night Flight
  • One on one (Mockingboard version)
  • Phasor software (Applied Engineering)
  • Popeye
  • Rescue Raiders v1.3 (SSI263 speech only)
  • Silent Service
  • Skyfox
  • Spy Strikes Back (Votrax speech)
  • Ultima III (Mockingboard version)
  • Ultima IV
  • Ultima V
  • Willy Byte in the Digital Dimension
  • Zaxxon (Mockingboard version)

SAM:

SAM (Software Automatic Mouth) is an 8-bit DAC card than can be enabled in slot 5.


Clock

Clock:

AppleWin emulates a No-Slot clock (aka NSC).

This is a chip (a Dallas SmartWatch DS1216) that sits under one of the 28-pin ROM chips in the Apple II.
No hardware configuration is required: this chip is always present (unless -no-nsc is used), but won't interfere with emulation when not in use.

It requires a software driver to be installed (for DOS and ProDOS). This driver then emulates the Thunderclock card.

Here's a summary of NSC/ROM chip locations and which drivers work:

  • "CD" ROM socket: C000-DFFF (internal) ROM space - all drivers work
  • "EF" ROM socket: E000-FFFF ROM space - never seen any drivers use this space
  • "CF" ROM socket: C000-FFFF (internal) ROM space - all drivers work
  • Slot ROM socket: Cs00-CsFF (slot) ROM space - NS.CLOCK.SYSTEM works

Here are the drivers and ROM pages they check:

  • ProDOS "SWU.SYSTEM" - internal C3
  • ProDOS "NS.CLOCK.SYSTEM" - internal C3 C8 / external C1-C7
  • GEOS "NoSlot Clock" - internal C8

NOTE: For ProDOS, the load order of drivers is important:

Some .SYSTEM drivers will not chain-load the next driver.
NS.CLOCK.SYSTEM does, so ensure this is the first one ProDOS finds, whereas ZIP.SYSTEM doesn't so put this at the end of the chain.


Super Serial Card

Super Serial Card:

AppleWin emulates a Super Serial Card (aka SSC) in slot-2, with the jumper block in the MODEM position.

The SSC can be configured to communicate externally either via the host PC's COM serial port or TCP port 1977.

See the Configuration tab's 'Serial Port' menu to select a COM serial port or the TCP port.

The SSC currently has these hardcoded DIP switch settings:

  • DIP SW1:
    • Baud rate = 9600
    • Mode = CIC (ie. SSC's Communication Mode)
  • DIP SW2:
    • 1 stop-bit
    • 8-bit byte size
    • No parity
    • Linefeed off
    • Interrupts enabled

Notes:

  • The SSC emulation supports both Rx and Tx interrupts (for both COM and TCP modes), RTS/CTS, DSR/DTR, and the undocumented 115200 baud rate.
  • For the TCP mode it doesn't matter what baud rate, stop-bit, byte size and parity are set to.
    • It always uses an unthrottled data-rate of 8-bit bytes (no stop-bit, no parity).
    • When there's an active TCP connection, then the 6551's Status register has DCD,DSR bits clear (active low), and DIPSW2 has CTS bit clear (active low). When there's no TCP connection, then all these bits are set (inactive).
  • The TCP mode can expose buggy Rx interrupt handling code where the 6551's Status register is read more than once in the Interrupt Service Routine (ISR).
    • Details: TCP mode doesn't throttle the serial data-rate, so after reading the Status register (to clear the Rx interrupt) the Rx interrupt may get asserted immediately if there is more data in the TCP receive buffer, resulting in a missed interrupt (and therefore missed Rx data).
  • The 6551's Command register's DSR (bit0) must be set, to enable interrupts (Rx, Tx) along with the respective Rx and/or Tx bits (bit3:1). This is part of the 6551 specification, but (DSR bit) has only been enforced by AppleWin since 1.27.4.

Unsupported features are:

  • Can't configure the DIP switches (not a problem, since most functions can be set in software).
  • 6551 ACIA Command register: Echo mode(bit4=1) and Transmit BRK (bit3:2=3).
  • 6551 ACIA Control register: external clock (bit4=0).
  • 6551 ACIA baud rates: 50, 75, 109.92, 134.58, 150 all map to 110 baud.
  • 6551 ACIA baud rate: 1800 maps to 2400 baud.
  • 6551 ACIA baud rate: 3600 maps to 4800 baud.
  • 6551 ACIA baud rate: 7200 maps to 9600 baud.
  • 6551 ACIA Status register's error bits: overrun, framing and parity (these are all hardcoded to 0).
  • 6551 ACIA Status register's DCD bit (Data Carrier Detect). This is just set the same as DSR.
    • NB. For COM mode, use command line -dcd to force AppleWin to use the state of the MS_RLSD_ON bit from GetCommModemStatus().
  • NMOS 6551 ACIA CTS bug: transmission of an already-started frame will stop immediately when CTS is taken false, the byte will be lost, and the TxD line will go to marking.
    • NB. The CMOS 6551's will finish the frame, so assume that AppleWin emulates a CMOS 6551.
  • AppleWin's 6502/65C02 emulation doesn't emulate the false read for STA $C088,X (where X=$20).
    • Don't do this to write to the 6551's Transmit register.
    • On AppleWin this is fine, but on real hardware (in full duplex mode) you may falsely read (and clear) the 6551's Receive register.
    • Instead (like the SSC's firmware) do this: STA $BFFF,Y (where Y=$A9).

Using TCP mode with the Apple // Game Server:

The TCP interface to the SSC can be used by the Apple // Game Server (AGS).
For details see the notes that comes with AGS, but in summary:
  • 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.


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://vice-emu.sourceforge.net/index.html#developers

Details:

To enable ethernet support in AppleWin you must first download and install Npcap (or WinPcap).

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

Npcap: https://nmap.org/npcap/#download or Wireshark: https://www.wireshark.org (or WinPcap: https://www.winpcap.org/install/default.htm)

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 than one interface you may need to select them in turn in order to get the text description for each interface vs what Npcap likes to use for a reference. Select Ok. and then close AppleWin.

Note: Wireless does not work with WinPcap (but see WiFi Workaround).

Note: Due to a current limitation you must exit AppleWin and re-run AppleWin for an 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


WiFi workaround

Overview:

A (heavyweight) workaround for the WiFi issue.

Details:

Installing a virtualization solution like the (free) VMware Workstation Player provides a virtual ethernet card. Then installing WinPcap inside the virtual machine allows access to the internet via WiFi from AppleWin.

VMware allows you to configure the virtual ethernet card in two ways:

  • Bridged, this means that the virtual Uthernet card becomes visible with its MAC address in the WiFi net and that an Apple II DHCP client gets its address from the usual DHCP server (typically a WAN router).
  • NAT, this means that the virtual Uthernet card is part of a virtual network with three participants:
    • A virtual Ethernet card added by VMware to the "outside" (aka host) Windows.
    • The virtual Ethernet card used by the "inside" (aka guest) Windows.
    • The virtual Uthernet card.

    That virtual network has its own IP address range and has its own DHCP server (being part of VMware). An Apple II DHCP client gets its address from that DHCP server.

Another positive aspect of that "emulation inside vitualization" approach is that the "inside" (aka guest) Windows always has just one single network interface: that virtual ethernet card mentioned above. And that interface has always the same name (even when switching between Bridged and NAT) so one never has to fiddle with network setting of the emulators using WinPcap.


AppleWin Configuration

Select one of the following topics:

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


Configuration Settings

Configuration settings Model:
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 ][ : 48K non-autostarting, Integer BASIC, no lower-case, no 80-column, 6502 CPU
  • Apple ][+ : 64K autostarting, Applesoft BASIC version of the Apple ][
  • Apple ][ J-Plus : 64K autostarting, Applesoft BASIC, Japanese 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)
Confirm reboot:
Show "Confirm reboot" message box when F2 is pressed.

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. The differences are discussed below.
  • Monochrome (custom) : This mode emulates a monochrome monitor.
    You can choose your monochrome color from the Monochrome Color button described below.
  • Color (Composite Idealized) : This mode emulates an idealized composite color monitor.
    Text is sharp like a white monochrome monitor. Color graphics has only 16 colors (with no blurring or ringing). This is the only mode that supports vertical blend.
  • Color (RGB Card/Monitor) : This mode emulates a standard RGB card and monitor.
    Text is sharp like a white monochrome monitor. Color graphics has only 16 colors (with no blurring or ringing). Double hi-res is 140x192 chunky pixels (or software selectable as: B&W or mixed Color/B&W). From the command line you can specify the RGB card, the default is the Extended 80-Column Text/AppleColor Adaptor Card. Some double hi-res titles may have compatibility issues. See troubleshooting.
  • Color (Composite Monitor) : This mode emulates a standard NTSC (or PAL) color monitor.
    Text is sharp, but contains color artifacts. Color graphics has visible alternating color and black pixels.
  • Color TV : This mode emulates an NTSC color TV.
    All text and color graphics modes are blurry and have visible ringing.
  • B&W TV : This mode emulates an NTSC black and white TV.
  • Monochrome (Amber/Green/White) : Monochrome with specified color.
Monochrome Color:
This is the color to use when you choose a monochrome video mode.

50% Scan lines:
Only draw alternate scanline (for better monitor authenticity).

Vertical blend:
When video mode is 'Color (Composite Idealized)' then vertically blend the hi-res screen.

Full-Screen: Show drive/keyboard status:
When in full-screen mode, show floppy (activity and track) and harddisk status (activity); keyboard caps-lock status and if emulation is paused.

Serial Port:
This option will remap the emulated Apple's serial port to your PC's serial port (or TCP port 1977).
See Super Serial Card for more details.

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

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.

50Hz video:
When checked, this option will run the emulated machine with a 50Hz(PAL) video refresh rate. The default is unchecked, for 60Hz(NTSC).

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 (video update)
  • Pure CPU MHz (full-speed)
  • 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.
  • Allow cursor keys to be read from keyboard: Applicable only in 'Keyboard (cursors)' mode.
  • NB.
    • Be aware that 'cursor-up' = CTRL+K, and 'cursor-down' = CTRL+J.
    • When cursor keys are used for joystick emulation and are allowed to be read from the keyboard, then some games won't work correctly (eg. Lode Runner).
    • When cursor keys are blocked from being read from the keyboard, then simple command-line cursor editing in AppleSoft won't work.
  • Swap 0/1: Swap buttons 0 and 1.
  • Auto-fire (all 3 buttons): For each button pressed, the button's state will be toggled when read.
  • Keyboard auto-centering: When keys used for joystick emulation are released then the joystick will return to the central position.
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 4 or 5:
  • Emulates a CP/M card, complete with full Z80 emulation.
  • Available when Mockingboard or Phasor isn't in slot 4 or 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
  • 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.

SAM:
SAM (Software Automatic Mouth) is an 8-bit DAC card than can be enabled in slot 5.


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.

Disk 1/2 drop-down menus:
These menus 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. You can also eject images from this menu.

Hard disk Controller Settings:

Enable hard disk controller in slot 7:
A hard disk controller (or interface) card can be plugged in to slot 7 by checking this box. See Hard disk Images for more details.

Swap:
Swap the hard disk images.
WARNING! If done during image access this could result in undefined behavior (eg. Apple II program crash) or data corruption on the image.

HDD 1/2 drop-down menus:
These menus allow you to select hard disk images (eg. .hdv files) to connect to the emulated hard disk controller card. You can also unplug images from this menu.

Path to CiderPress:
Use this to specify where CiderPress is installed.
The right mouse 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.yaml 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; TK3000 is a Brazilian //e clone; Base 64A is a Taiwanese Apple II clone.

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 and exiting the Debugger
  • Debugger Screen Layout
  • Scrolling
  • Registers
  • Flags
  • Execution
  • Memory
    • Viewing Memory
    • Searching Memory
    • Changing Memory
  • Symbols
  • Calculator
  • Windows
  • Breakpoints
  • Bookmarks
  • 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.

Exiting the Debugger

In general, press F7 to exit the debugger.
NB. If you have breakpoints set then you will exit the debugger in 'stepping' mode.

Other ways to exit the debugger and force 'stepping' mode are:

Command | Run at normal speed? | Run at full speed? | Video quality | Sound quality
G | yes | only if disk active, etc | precise | precise
GG | no | always | periodic | muted

Finally to exit 'stepping' and return to the debugger, use F7, the Pause key or the Debugger toolbar button.


AppleWin Debugger Tutorial

Debugger Screen Layout

This section gives an overview of the debugger's screen layout.

Here's a typical debugger view (with annotations describing the parts):

Soft-switches

This encodes information about the video and MMU soft-switches.

The first 5 rows describe the current video settings and can be interpreted as follows:

  • 50: $C050 - GR /TEXT (inverse indicates which is active)
  • 52: $C052 - FULL/MIX (inverse indicates which is active)
  • 54: $C054 - PAGE 1/2 (inverse indicates which is active)
  • 56: $C056 - LO/HIRES (inverse indicates which is active)
  • 5E: $C05E - DHGR/HGR (inverse indicates which is active)

The next 6 rows describe the current MMU settings and can be interpreted as follows:

  • 00: $C000 - 80Sto0/1 (inverse indicates state of 80STORE)
  • 02: $C002-C005: Rm/xWm/x (NB. 'R' is blue and 'W' is red for readability)
    • Rm Read from main mem for $0200-$BFFF; Use OUT C002 to enable
    • Rx Read from aux mem for $0200-$BFFF; Use OUT C003 to enable
    • Wm Write to main mem for $0200-$BFFF; Use OUT C004 to enable
    • Wx Write to aux mem for $0200-$BFFF; Use OUT C005 to enable
  • 0C: $C00C - Col40/80 (inverse indicates state of 80COL)
  • 0E: $C00E - ASC/MOUS (inverse indicates state of ALTCHARSET)
  • 80: $C080-C087: B2/M R/W (Language Card Bank2)
    • A red 'x' if ALTZP (and Alt Language Card) is set by a write to $C009.
  • 88: $C088-C08F: B1/M rNN (Language Card Bank1 and RamWorks 64K bank number)
    • 'B2' or 'B1' is inverse when that LC bank is enabled.
    • If 'M' is inverse: ROM is active for reading.
    • If 'M' is not inverse: LC2 or LC1 RAM is active.
    • If 'W' is inverse: RAM is write enabled.
    • If 'W' is not inverse: RAM is write protected.
    • 'rNN' will appear if a RamWorks 64K bank is active.
    • 'sNN' will appear if a Saturn 16K bank is active.


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 in the Processor Status Register ('P'). Cleared flags will show up with a normal background. Set flags will show with an inverse background.

Notes:

  • Shift+Left mouse button can be used to toggle the state of individual flags.

  • 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] GG [StopAddress] | Resume execution until PC = StopAddress.
G [StopAddress] [SkipAddress,Length] GG [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 and then G.

NB. The GG command resumes execution in full-speed. See Exiting the Debugger.

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

When a programmer writes an assembly language program instead of directly referring to a memory address over and over again they use a symbolic name instead. For example, instead of always directly hard-coding $C000 everywhere to read the keyboard they would instead write:

                       ORG $300
                       KEYBOARD EQU $C000
300:AD 00 C0 .1        LDA KEYBOARD
303:10 FB              BPL .1
305:8D 00 04           STA $0400
306:60                 RTS

Let's try this out in the debugger. Make sure AppleWin is running. Press F2 (to reboot), then Ctrl-F2 (to break), and F7 (to enter the debugger.) If you don't want to type in the following hex code, you can select it, copy it (Ctrl-C), and paste it into the Debugger console (Ctrl-V).

300:AD 00 C0 10 FB 8D 00 04 60
300L

Press F7 to exit the debugger, then type:

HOME:CALL 768

Press Enter. The emulated computer will wait for your to press a key and then echo it in the top left.

When debugging assembly programs since you typically don't have the source file availabe you can tell the debugger how to interpret a memory address as a variable name or symbol. A symbol is the symbolic name and the address assigned to it.

AppleWin supports loading of the assemblers ACME, and Merlin's symbol tables -- a collection of symbols, one per line, organized and collectively called a symbol table. The semi-colon is a comment-till-end-of-line. The file format per line is: ADDRESS SYMBOL

e.g.

; IO Map
C000 KEYBOARD

There are 9 symbol tables to help organize "modules"; each symbol table individually can be turned off/on independently.

 MAIN    APPLE2E.SYM
 BASIC   A2_BASIC.SYM
 ASM     A2_ASM.SYM
 User1   A2_USER1.SYM
 User2   A2_USER2.SYM
 Src1    A2_SRC1.SYM
 Src2    A2_SRC2.SYM
 DOS33   A2_DOS33.SYM
 PRODOS  A2_PRODOS.SYM

On startup the debugger reads 3 symbol tables by default: Main, Basic, User1.

Looking up symbols is easy. If you can't remember an address of a symbol, or the reversse -- can't remember the symbol for an address -- you can use the following symbol commands: (#### referes to either a hex address or a symbolic name)

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 | Reloads the User Symbol Table: A2_USER1.SYM
SYMUSER CLEAR | Clears the User Symbol Table from RAM.
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.
MEB symbol ## | Set memory (at the symbol Address) to the 8-Bit (byte) Value.
MEW 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 Symbol Home ($FC58).
SYM LIFE = 300 | Define a new user symbol, called “Life” at Address $0300.
MEB LIFE 64 | Set 8-Bit variable (@ $0300)“Life” to 100 (decimal).
MEW LIFE 3E8 | Set 16-Bit variable (@ $0300)“Life” to $3E8 = 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 the 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.

BPMR address[,len]

Add Breakpoint trigger when memory is read by 6502.

BPMW address[,len]

Add Breakpoint trigger when memory is written 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

Bookmarks

Bookmarks allow you to "tag" an address and consequently jump back to them.
They appear as a number with a circle around them between where address and opcodes are listed (where the : separator is).

Notes:

  • Set a bookmark at the current disassembly cursor, use Ctrl-Shift-#, ie:
    • NB. Ctrl-Shift-0 can't be used, as it's not recognised by Windows
    • Ctrl-Shift-1 set bookmark 1
    • Ctrl-Shift-2 set bookmark 2
    • ...
    • Ctrl-Shift-9 set bookmark 9

  • To jump to an existing bookmark, if it exists, press Ctrl-#, ie:
    • Ctrl-0 to jump to bookmark 0
    • Ctrl-1 to jump to bookmark 1
    • Ctrl-2 to jump to bookmark 2
    • ...
    • Ctrl-9 to jump to bookmark 9

  • NB.
    • Bookmarks can appear in any order that you set - not just contiguous.
    • An address can only have ONE bookmark assigned to it. If you try setting a new bookmark over an existing one, the old one will become free for use.

Commands to manipulate bookmarks:

Command | Description
help bookmarks | Lists all bookmark related commands
help bma | Lists specific help about the bma command
bma <address|label> | Add a bookmark at an address or label
bmc # | Clear a specific bookmarks, for example 'bmc 1' clears bookmark 1
bmc * | Clears all bookmarks
bml | Lists all boommarks
bmsave | Not implemented yet


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. NB. When AppleWin initially starts-up, it will attempt to auto-run 'DebuggerAutoRun.txt' (located in the same folder as AppleWin.exe).

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

https://archive.org/details/softwarelibrary_apple/
This site contains a number of collections of Apple II software. Including:

  • https://archive.org/details/wozaday/
    This is an ever expanding collection of Apple II images in WOZ format.
  • https://archive.org/details/softwarelibrary_apple_woz/
    Another collection of Apple II images in WOZ format.


Contacting the Developers

To contact the project administrators, post a question to the GitHub link below.

Bug reports / feature requests should be submitted here:
https://github.com/AppleWin/AppleWin/issues/new


Appendix

  • Full-speed mode
  • Troubleshooting


Full-speed mode

Overview:

Emulation can be run in full-speed (aka unthrottled) mode.

Details:

This can be enabled manually or automatically in a variety of ways:

  • Permanently enabled by the AppleWin Configuration tab's 'Emulation Speed Control', and setting 'Custom Speed (in MHz)' to 'Fastest'.
  • Scroll Lock key: can be configured to toggle normal/full-speed mode, or only enable full-speed when pressed.
    • See Input for configuring how Scroll Lock behaves.
  • Ctrl-0 & Ctrl-3: can be used to toggle custom/full-speed mode, or set full-speed mode respectively.
    • See Using the Keyboard for more information.
  • When 'Disk access speed' is set to 'Enhanced Speed' (the default), then whenever the Disk][ drive motor is on, the emulator will automatically switch to full-speed (and when the motor is switched off, then the emulator will automatically revert to what the 'Emulation Speed Control' has been set to).
    • See Disk for configuring 'Disk access speed'.
  • From the built-in debugger, single-stepping via the 'gg' command.

Limitations and things to bear in mind:

  • Full-speed mode favours speed over video accuracy:
    • The Apple II's video is only updated periodically (once a wall-clock 60Hz frame) instead of each opcode.
    • Split-mode video (eg. French Touch demos) won't render correctly.
  • All sound (speaker, Mockingboard, etc) is muted.
  • One of your PC's CPU cores will run at 100%.
    • EG. Simply boot the Apple II (or //e) without a disk in drive-1.


Troubleshooting

Here is a list of issues and possible solutions:

Uthernet network card not working.
  • There are problems when running with certain firewalls (eg. ZoneAlarm).
    • See the Uthernet network card section for details.
AppleWin doesn't startup.
  • It could be being blocked by your anti-virus software. There is a known problem with Constant Guard Protection Suite.
    • From your anti-virus software, unblock AppleWin to allow it to run.
When using a non-US (or UK) keyboard, certain keys can't be typed.
  • AltGr (or right Alt) needs to be used to type certain keys, eg:
    • '@' is AltGr+2 (for a Canadian-French keyboard).
    • '[' is AltGr+é (for an Italian keyboard).
  • Some games or productivity software have an action based on the Open Apple (Alt) or Solid Apple (AltGr) keys, eg:
    • Lode Runner uses CTRL+@ to increase the lives.
    • AppleLogo // and AppleWorks 5.1 have problems when using an Italian keyboard.
  • This dual function for AltGr (to both type a key and emulate Solid Apple) can cause problems such that the key (eg. '@') can never be typed.
  • The workaround is to use the `-no-hook-alt` command line switch and configure Joystick 1 = "Keyboard (numpad)"; and then use the '0' and '.' keys for Open/Solid Apple.
No Apple II speaker sound, but Mockingboard sound is working!
  • Check the Volume Control for the Speaker, under the Configuration->Sound tab.
  • Try installing the Realtek-specific audio driver supplied by ASUS (as opposed to the default Win10 driver).
Color (RGB Card/Monitor) and title compatibility issues:
  • Dragon Wars: double hi-res bit7 needs inverting, so use the -rgb-card-invert-bit7 command line switch.
  • Renegade: switches to 160x192 mode at the title screen and then B&W (at the title screen) after game play.
  • Apple's AppleColor card or Video7's RGB-SL7 card: corruption for titles/demos that accidentally switch to foreground/background hi-res mode, eg. French Touch DIGIDREAM demo.