Altirra Help: Introduction

Altirra Help
Introduction

This help file is the documentation for Altirra, an emulator that simulates the hardware of the Atari 8-bit computer systems, including the Atari 800, 800XL, and 130XE computers.


Altirra Help: Introduction

Introduction
Contents
  • 1. System requirements
    • 1.1. Why does Altirra require a 1GHz processor to emulate a 1.79MHz machine?
    • 1.2. How fast should I expect Altirra to run?
    • 1.3. Would multiple CPU cores help?
  • 2. For first timers
    • 2.1. What's that beeping sound I hear sometimes when a game is loading?
    • 2.2. Okay, what about the grinding sound when I don't have a disk set?
  • 3. Hardware support
    • 3.1. Does Altirra support the Atari 2600 or 7800?
  • 4. Input
    • 4.1. How come key presses don't always seem to register in the emulator?
    • 4.2. How come Shift+2 doesn't work like it does on the Atari?
    • 4.3. How do I type Ctrl+Esc and Ctrl+Shift+Esc?
    • 4.4. How come Ctrl+Shift+0 doesn't work in Windows Vista/7?
    • 4.5. How do I make the arrow keys work?
  • 5. Display
    • 5.1. Why do the colors seem subdued in PAL programs?
    • 5.2. How come when I run in VBXE mode, palette changes don't take place immediately and I see color mismatches in programs?
    • 5.3. Why can't I use a palette file (*.pal, *.act)?
    • 5.4. Why is PAL mode a little jittery?
  • 6. Sound
    • 6.1. The sound seems a bit crackly. How do I fix this?
    • 6.2. How do I reduce the delay between inputs and the sound?
  • 7. Emulation options
    • 7.1. Why can't I choose PAL mode when 5200 hardware mode is selected?
    • 7.2. How come the BASIC option is inverted after I switched to custom OS firmware?
  • 8. Other
    • 8.1. Can I use a physical Atari disk drive over a serial or USB adapter with Altirra?

System requirements

Why does Altirra require a 1GHz processor to emulate a 1.79MHz machine?

Yeah, that does seem a bit inefficient, doesn't it?

Altirra uses a precise but slow way to emulate the Atari hardware: it emulates hardware on a per-cycle basis. This is required to properly sequence memory accesses between ANTIC and the 6502 CPU. Event queues are used whenever possible to reduce the load, particularly with GTIA and POKEY, but there are still patterns of memory writes to hardware registers that will force frequent synchronization.

In the past, emulators have made some compromises like atomically executing 6502 instructions and only firing POKEY interrupts on a scan line basis. This was required for good performance on older machines and is still required on some embedded platforms, but doing this introduces slight emulation inaccuracies. Altirra deliberately uses slower algorithms in order to do more precise emulation.

Further optimizations are always possible, but in general it takes a lot of cycles on a sequential CPU to precisely emulate parallel hardware.

How fast should I expect Altirra to run?

On a 2.5GHz Core 2 Duo, I get from about 300-950 fps in NTSC (500-1500%) in turbo/warp mode. On a 1.6GHz Atom, it's more about 150-300 fps (250-500%).

You can generally expect the emulation to run in real-time, so it's more of a question of how fast it can run in turbo. After all, load times are probably the least interesting part of the Atari experience to emulate.

Would multiple CPU cores help?

No. To take advantage of multiple cores, you need to have multiple workloads that are relatively decoupled so the cores can work separately. Precision cycle-level emulation is the exact opposite case where everything is tightly coupled together.

It is possible to offload tasks that aren't in the critical path and aren't visible to programs running in emulation, such as the latter parts of audio and video generation. Unfortunately, these aren't very time-consuming with the Atari hardware, so there isn't much to offload.

For first timers

What's that beeping sound I hear sometimes when a game is loading?

That's the Atari disk load sound. Specifically, the serial I/O (SIO) routines in the Atari OS normally set up the POKEY chip to play audible tones when reading data from the floppy disk drive. You don't often hear it in emulators because either the emulator doesn't emulate it or the emulator is accelerating the disk load (SIO patch). If you are hearing it in Altirra, it means that the disk load is unaccelerated.

Okay, what about the grinding sound when I don't have a disk set?

That's the OS polling for non-disk devices. Just wait a couple of seconds, or enable the "fast boot" firmware option.

Hardware support

Does Altirra support the Atari 2600 or 7800?

No, these are completely different architectures to the 800/5200 lineage. Fundamentally, the 2600 uses a CPU-driven display, while the 800/5200 are primarily playfield DMA driven and the 7800 uses a line-buffered renderer.

The 5200 SuperSystem did support a 2600 adapter, but it was essentially a 2600 mounted on an expansion board that used a video bypass on the 5200.

Input

How come key presses don't always seem to register in the emulator?

Sometimes programs periodically check for a key being held down instead of trapping the key press interrupt. By default, the keyboard mappings are set up in Altirra so that typing a character on the host PC pushes one character into the emulation. This prevents the emulated OS from duplicating or dropping keys, even at warp speed. It also allows the emulator to queue keys so you can type faster than you could on a real Atari. However, it sometimes means that the emulated key presses are too quick for the program to see.

Under Input > Keyboard, you can change the keyboard mode from cooked mode to raw mode so that the emulation sees the keys being held down.

How come Shift+2 doesn't work like it does on the Atari?

Altirra maps the keyboard by symbol when possible so that characters you type on the host PC match the ones produced in the emulation. You typed an @ (Shift+2 on the host), but the Atari has " in that spot instead. The upside is that you don't have to deal with having the Break key next to the Backspace key like on the original keyboard.

How do I type Ctrl+Esc and Ctrl+Shift+Esc?

As you've probably discovered, these are reserved keys in Windows. Use Ctrl+\ and Ctrl+Shift+\ instead.

How come Ctrl+Shift+0 doesn't work in Windows Vista/7?

By default, Windows Vista/7 assign Ctrl+Shift+digit keyboard shortcuts for switching keyboard layouts. To disable this shortcut:

  • Open Control Panel.
  • Select Region and Language.
  • Select the Keyboards and Languages tab.
  • Click Change Keyboards.
  • Select the Advanced Key Settings tab.
  • Click Change Key Sequence.
  • Under Switch Keyboard Layout, select Not Assigned.

How do I make the arrow keys work?

If you have an input map enabled that maps the arrow keys to a controller, the emulation won't see the arrow keys as such, as they'll be shunted to the controller. There are two ways to fix this: either disable the input map, or hold down Alt when pressing the arrow keys to bypass the input map.

Display

Why do the colors seem subdued in PAL programs?

Some PAL programs (demos) make use of screens that have alternating grayscale and color lines to simulate higher color depth output. These screens make use of the vertical blurring done by PAL TV sets to carry chroma into the grayscale lines. Displaying these screens without that blurring effect results in lost saturation, which fortunately can be recovered by enabling PAL artifacting in the emulator.

How come when I run in VBXE mode, palette changes don't take place immediately and I see color mismatches in programs?

Unlike the regular GTIA, Video Board XE (VBXE) allows the program to modify the 256 color Atari palette. Altirra copies its palette into VBXE palette 0 on startup, but afterward it can't update it because some colors may have been modified. Mismatches occur when programs only modify part of the palette and rely on the exact colors provided in palette 0 (which is a bit risky, since they are only ever loaded on cold boot and not on warm reset).

Why can't I use a palette file (*.pal, *.act)?

The graphics code requires knowledge of the upstream luma and chroma signals in order to properly handle some video output modes, particularly artifacting modes. That is why the Adjust Colors dialog exposes the parameters used to generate the palette instead of the palette colors themselves.

Why is PAL mode a little jittery?

PAL displays use a 50Hz refresh rate, while computer displays often run at 60Hz or higher. Displaying PAL video on a 60Hz display results in a tiny jerk 10 times a second (60Hz - 50Hz = 10Hz). If you can set your host PC to use a 50Hz display, this effect will mostly go away.

The reason it doesn't entirely go away is that the Atari actually produces a video signal that deviates a little bit from the standards and has a frame rate that's slightly slower than it should be.

Sound

The sound seems a bit crackly. How do I fix this?

If your video card is unable to keep up or the CPU is loaded, the sound can break up because the emulator can't keep the sound card fed consistently. Increase the latency in System > Audio > Options to fix this.

How do I reduce the delay between inputs and the sound?

This is the opposite problem of too much latency — decrease the latency in System > Audio > Options. You can also switch to DirectSound mode, as that usually enables lower latency than waveOut mode, particularly on Windows Vista and Windows 7.

Emulation options

Why can't I choose PAL mode when 5200 hardware mode is selected?

A PAL version of the 5200 SuperSystem was never made. All manufactured consoles were NTSC.

How come the BASIC option is inverted after I switched to custom OS firmware?

The official XL/XE OS is set up so that by default it boots with BASIC enabled, and you have to hold down OPTION on boot to turn it off. That's annoying, since a lot of the good software doesn't use BASIC and needs OPTION held down, so custom OSes frequently have this swapped around. Unfortunately, Altirra doesn't know which convention the custom OS uses, so you have to flip the option around if the OS works that way.

Other

Can I use a physical Atari disk drive over a serial or USB adapter with Altirra?

No, this is not currently supported. The best way to use such hardware is to use another program to image the entire disk through the drive, then mount that disk image in Altirra.

It is possible for an emulator to directly use a disk drive in this manner, but the timing is critical enough that it isn't a good idea, at least in Windows. The main reason is that while a PC is fast enough to emulate an Atari, it isn't necessarily fast enough to support the stable timing and low latency needed to use a live drive during emulation.

For instance, the Atari SIO specification states that the computer must negate the command line within 650-950 microseconds of transmitting the last bit of the command frame, and begin transmission of a data frame 1.0-1.8 milliseconds after receiving the last bit of an ACK byte from the peripheral. This timing is even more critical if a protected disk is being read, as slight timing variations can cause the wrong sector to be read and the game to crash. In contrast, a single call to Present() to draw a frame on screen can delay the emulator by up to 16.7 milliseconds when vsync is enabled.


Altirra Help: Getting started

Getting started
  • 1. Software to run
  • 2. Loading the image
    • 2.1. Tape images
    • 2.2. BASIC programs
  • 3. Hooking up actual kernel ROM images
  • 4. Tweaking options
    • 4.1. Hardware / Firmware
    • 4.2. BASIC
    • 4.3. PAL vs. NTSC

Software to run

First, you need software to run on the emulation. This can be in the form of:

  • Disk images (ATR, DCM, XFD).
  • Tape images (CAS, WAV).
  • Cartridge ROM images (BIN, CAR, ROM).
  • Executable images (OBX, EXE, XEX).
  • BASIC programs (BAS).

Make sure any images you have are actually meant to run on an 8-bit Atari. 16/32-bit programs written for the Atari ST will not work. A COM/EXE program written for DOS definitely won't work.

Loading the image

Almost all images can be booted easily through the File > Boot Image... command on the menu. This clears any existing mounted images, mounts the desired image, and then cold-reboots the emulation. This is usually all you need for disk images, cartridges, and executables.

Tape images

For tape images, you will need to determine whether the program on the tape is a machine language program or a BASIC program. If it is a machine language program, enable the System > Cassette > Auto-boot on startup option. This causes the emulator to hold the START button on power-up to request a boot off cassette tape.

BASIC programs

Running a BASIC program that is supplied directly as a BAS file — and not a disk image — takes a bit more work. In order to run the program, rename it to an 8.3 compatible filename (i.e. MYPROGRM.BAS), and then assign the directory holding that file to the virtual H: device through System > Hard disk. Then, enable System > Firmware > BASIC, cold reset the emulation, and type the following:

load "H:MYPROGRM.BAS"
run

Hooking up actual kernel ROM images

By default, Altirra uses its internal high-level emulation (HLE) kernel. This provides a reasonable level of compatibility with software, but BASIC is not included and some software will not work properly. For maximum compatibility, you will need to use real Atari ROM images. These are not included with Altirra and must be obtained elsewhere, but if you have them, place them in the Altirra program directory with the following names:

ROM | Filename
Atari 800 kernel ROM (revision A) | ATARIOSA.ROM
Atari 800 kernel ROM (revision B) | ATARIOSB.ROM
Atari XL/XE kernel ROM | ATARIXL.ROM
Atari BASIC ROM | ATARIBAS.ROM
Atari 5200 kernel ROM | ATARI5200.ROM

You do not need all of these ROM images; Altirra will use the ones that are available.

Tweaking options

Hardware / Firmware

Typically, you will want to run with 800XL hardware and 600/800XL firmware for best compatibility. Some programs will require older 800 hardware and OS-B firmware to work.

BASIC

The simple rule for enabling BASIC is: enable it only for BASIC programs. Many games written in machine language will crash if BASIC is enabled. There are a few machine language programs that do require BASIC to be enabled, but they are rare.

PAL vs. NTSC

The Atari 800 was originally an NTSC-based machine, and much of the early commercial software was written with this in mind. Later software, however, was mostly written in Europe and thus targeted PAL machines.

If software intended for NTSC is run on PAL, it will typically run about 16% too slowly. If software intended for PAL is run on an NTSC machine, however, not only may it run 20% too quickly, but it may also crash due to the shorter frame time. Therefore, PAL is the safer option, as it is very rare for NTSC software to be incompatible with PAL. However, choose NTSC when appropriate for a more authentic experience with software intended to run with that standard.


Altirra Help: Keyboard mapping

Keyboard mapping

Atari Keys

When possible, Atari keys are mapped to the host keys that generate the same characters. For instance, Shift+2 on a US English keyboard layout generates an @ key press in the emulated system, even though Shift+2 generates a double quote (") on the Atari keyboard. Here are the less obvious mappings:

Atari key | Host key
Start | F2
Select | F3
Option | F4
System Reset (Warm Reset) | F5
Power (Cold Reset) | Shift+F5
Help | F6
Break | Pause
Shift+< (Clear) | Home
Shift+> (Insert Line) | Shift+Insert
Ctrl+> (Insert Character) | Insert
Shift+Backspace (Delete Line) | Shift+Delete
Ctrl+Backspace (Delete Character) | Delete
Fuji / Invert | End or `
Ctrl+Esc | Ctrl+\
Ctrl+Shift+Esc | Ctrl+Shift+\
Ctrl+- | Up Arrow*
Ctrl+= | Down Arrow*
Ctrl++ | Left Arrow*
Ctrl+* | Right Arrow*
  • The Options / Keyboard... dialog allows configuration of the arrow key handling and can be set to either require or not require use of the Ctrl modifier key. Also, holding the Alt key will allow the arrow keys on the host to issue keyboard input even if those keys are already mapped to an input controller.

Host Keys

These are the mappings from host keys to emulator functions:

Host key | Function
Alt+Shift+C | Copy frame to clipboard
Alt+Shift+V | Paste text
Ctrl+\ | Ctrl+Esc
Ctrl+Shift+\ | Ctrl+Shift+Esc
Alt+Enter | Toggle full-screen mode
F1 | Warp speed
Ctrl+F1 | Toggle filter mode
F2 | Start
F3 | Select
F4 | Option
F5 | System Reset (Warm Reset)
Shift+F5 | Power (Cold Reset)
F6 | Help
F8 | Run / Break
F9 | Toggle Breakpoint
F10 | Step Over
F11 | Step Into
Pause | Break
Home | Shift+< (Clear)
Insert | Ctrl+> (Insert Character)
Shift+Insert | Shift+> (Insert Line)
Delete | Ctrl+Backspace (Delete Character)
Shift+Delete | Shift+Backspace (Delete Line)
End or ` | Fuji / Invert
Up Arrow* | Ctrl+-
Down Arrow* | Ctrl+=
Left Arrow* | Ctrl++
Right Arrow* | Ctrl+*
Right Alt (AltGr) | Release mouse capture


Altirra Help: Configuring input

Configuring input
  • 1. Using input maps
  • 2. Managing input maps
    • 2.1. Selecting existing input maps
    • 2.2. Creating a new input map
    • 2.3. Renaming an input map
    • 2.4. Adding input maps to the menu
  • 3. Editing input maps
    • 3.1. Structure of an input map
    • 3.2. Adding and managing controllers
    • 3.3. Mapping input to a controller
    • 3.4. Quickly remapping inputs
    • 3.5. Reusing buttons with flags
  • 4. Special topics
    • 4.1. Analog controllers
    • 4.2. Mice

Using input maps

An input map is used in Altirra to define a connection between input devices on the host and emulated controllers. Altirra comes with several of these predefined, which can be selected from the Input menu. For instance, the Arrow keys -> Joystick (port 1) map connects the arrow keys on the keyboard to an emulated joystick.

By default, Altirra only allows one input map to be enabled per port, and automatically disables any other input map targeting that port. You can explicitly enable multiple input maps to the same port through the Input Maps dialog.

The arrow keys are commonly mapped to controllers, but occasionally a game will require use of both a game controller and the arrow keys on the Atari keyboard. You can bypass the input maps and force the arrows to be interpreted as keyboard presses by holding down the Alt key when pressing the arrow keys.

Managing input maps

To edit or create new input maps, use the Input Maps dialog.

Selecting existing input maps

The checkboxes beside each input map show which ones are enabled for use. Click on the checkboxes to toggle individual input maps on and off. You can have many input maps enabled at the same time.

Creating a new input map

There are three ways to create a new input map. You can start from scratch by clicking the Add button, or you can select an existing map and copy it with the Clone button. Finally, you can select a built-in preset to use as a template using the Preset button.

Renaming an input map

To rename an input map, select it and then click once on its name, which will then become editable. Type the new name and press Enter.

Adding input maps to the menu

Any input map that is created will automatically show up in the Port submenus in the Input menu for any controllers that target those ports, using the name created for it.

Editing input maps

Select an input map and then Edit to bring up the Edit Input Map dialog. This allows you to edit the input map itself.

Structure of an input map

An input map consists of a series of controllers, which in turn have mappings between that controller and host input. The controller is the device seen by the program running under emulation, and represents a device that would have been used with a real Atari.

Adding and managing controllers

To add an emulated controller, click the Add Controller button. You can also select an existing controller and then Edit to change an existing controller. The Port selection on the Add/Edit Controller dialog determines which of the controller ports on the Atari the controller is connected to; for joysticks, port 1 is used for the main player and other players use port 2 and up. For paddles, each port supports a pair of paddles, where the first paddle is paddle A.

There are also two additional virtual controllers you can select. One is the Console controller, which represents extra functions on the Atari keyboard and in the emulator itself, like the Start button and the power switch (cold reset). The second is Input State, which allows the input map to modify itself (see below).

When adding a new controller, the "add default mappings" option specifies whether to pre-populate the controller with mapping entries appropriate for that controller. This is handy for quickly binding a controller where no fancy mappings are needed.

Mapping input to a controller

Once a controller has been created, host inputs must be mapped to it. If "add default mappings" was checked when the controller was added, there will already be blank entries present and these can simply be edited; otherwise, new ones can be added with the Add Mapping... button. The Target entry on the mapping refers to an aspect of the emulated controller, like the trigger button on a joystick, while the Source entry determines which button or input on the host activates that target.

When using a game controller connected to the host PC, you can press a button or axis on the game controller to automatically select that input as the source for the mapping.

The Mode and Speed parameters allow the mapping to be customized, particularly when connecting digital inputs. Such mappings can be altered to support auto-fire or to move an analog axis with varying speed.

Mappings may share targets and sources. If two mappings share a source, that input will activate both mappings: a host button can both push forward and press the trigger on an emulated joystick. Similarly, if two mappings have the same target, either of them can be used to activate it. This is useful for either mapping multiple buttons on a host game controller to the same function, or to activate the same function with multiple modes, e.g. joystick button with and without auto-fire.

Quickly remapping inputs

You can quickly remap a series of inputs by using the Rebind button. This will bring up a sub-dialog where pressing any key on the keyboard or a button on a game controller will bind that input to the current mapping's target and then proceed to the next mapping. This will continue with subsequent mappings until all remaining mappings are rebound or the Stop button is clicked. This is generally a much faster way of setting up mappings.

Reusing buttons with flags

A button on a host controller can be overloaded with more than one function through flags. Every input map has two binary flags that can either be set or unset, and those flags can in turn enable or disable controllers on the input map. This lets the input map have multiple modes without requiring too many extra buttons.

Flags are controlled by adding input mappings to a controller of type Input State, and binding inputs to the Flag 1 or Flag 2 targets. The mode can either be Default, in which case the flag is only set while the button is down, or Toggle, in which case it alternates states on each press of the button. These flags can then be interpreted by controllers that are flag-sensitive, as determined by the Condition checkboxes on the Add/Edit Controller Mapping dialog; each controller can either require a flag to be off, on, or ignore that flag entirely. Using one flag gives two modes on the input map, and both can be combined to give four modes.

Special topics

Analog controllers

Several of the controllers used with the Atari computer and 5200 SuperSystem are analog, meaning that they have variable position. This includes paddles and the 5200 joystick. The most straightforward way to map such a controller is to bind it to an analog controller on the host PC, such as the analog stick on a game controller. However, it is sometimes useful to bind analog axes to other input types.

For games that do not require fine positioning, the analog controller can be bound to digital inputs:

5200 Controller (port 1):
    Up -> Joy POV Up
    Down -> Joy POV Down
    Left -> Joy POV Left
    Right -> Joy POV Right

This maps the nine positions on the D-pad of a PC game controller to the center and eight extremes of the 5200 analog joystick. This works fine for games that use relative motion, where pushing the stick in a direction moves a character in that direction. In other games that use absolute positioning, such as 5200 Missile Command and 5200 Gorf, the position of the stick determines the position of the cursor or player, and the above mapping only gives nine positions on screen. In that case, relative mapping should be used instead:

5200 Controller (port 1):
    Up -> Joy POV Up (Relative 5)
    Down -> Joy POV Down (Relative 5)
    Left -> Joy POV Left (Relative 5)
    Right -> Joy POV Right (Relative 5)

This causes the various directions on the D-pad to gradually move the joystick in a particular direction. Note that the stick does not auto-center when mapped this way — when no buttons are pressed on the D-pad, the emulated 5200 joystick will remain in its current position.

Mice

A mouse has no absolute position and simply reports motion. This means that it has no limits and no center position. As such, binding to or from a mouse is more limited than for the other input types. In particular, you cannot bind a mouse to an analog axis and get analog inputs. You can, however, get digital inputs from the mouse, and get analog impulses for an emulated mouse.


Altirra Help: On-screen indicators

On-screen indicators

A series of on-screen indicators can appear at the bottom of the display window to indicate I/O activity.

The indicators are as follows:

Modem status (Connected to 192.168.0.1:8000)
Displays outgoing addresses and state when dialing out and incoming addresses and state when receiving connections. Addresses are displayed in raw IPv4 or IPv6 format.
Cassette tape position (00:00:00)
Appears when a cassette tape image is mounted and the cassette tape is moving. A "C" is also displayed before the timestamp when cassette SIO acceleration is occurring.
PCLink activity (PCL:R/W)
Displayed when the PCLink device is activated.
Recording length (R02:00:00)
Shows how long a video or audio recording session has run.
IDE read/write indicator (W1000000)
Indicates "R" for read or "W" for write activity to the IDE hard disk and the logical block address (LBA) of the accessed sector.
Flash write indicator (F)
An "F" is displayed whenever writes occur to cartridge or peripheral flash memory.
Floppy drive LEDs (1-15)
Appear on a floppy drive access. By default the drive number is displayed; this can be changed to the sector number in the menu under System > Disk.


Altirra Help: Portable mode

Portable mode

Altirra can be run in portable mode to ease transport of working setup between host machines. In portable mode, Altirra stores settings in an .ini file instead of in the Windows Registry, allowing both the emulator and the emulator configuration to be placed on a removable storage device.

To switch to portable mode, either start Altirra with the /portable switch, or create Altirra.ini directly. Altirra automatically switches to portable mode whenever the INI file is present, so once this file is created, there is no need to continue specifying /portable.

Limitations of portable mode

For the most part, portable mode acts substantially the same as the regular Registry-based mode. However, there are slight differences in some corner cases. The main difference is that if multiple instances of Altirra are started and exited at the same time, they may hit a locking conflict on the Altirra.ini file, resulting in one of the instances being unable to load or save settings. A warning will be displayed on startup if the emulator is unable to load settings in portable mode. Launching multiple copies in portable mode that frequently is a rare corner case, but it can be easily worked around by using multiple installations of Altirra, each with their own INI file.


Altirra Help: Using the debugger

Using the debugger

Altirra includes a powerful debugger for diagnosing programs that are not working properly or that are under development.

Contents
  • 1. Switching to debugger mode
  • 2. Using the command line
  • 3. Execution control
  • 4. Setting breakpoints

Switching to debugger mode

To switch to debugger mode, select Debug > Enable Debugger from the menu. This will change the window layout to the default for debugging, which you can then modify by dragging panes or opening new ones from the Debug > Windows menu. Debug mode and normal mode have separate window layouts, which are saved independently.

Using the command line

In debug mode, various panes are available to display the state of the CPU, of memory, and of emulation. However, the main port for interacting with the debugger is the Output pane, which contains both a log window and a command line at the bottom. While some of the debugger commands can be used through the GUI, all of them are available through the command line, and thus mastering the command line is important for debugging proficiency.

All commands are of the form:

command-name [optional arguments]

To execute a command, type it in the command line and hit Enter. The command will be echoed in the log, along with any results. The command line supports history and allows past commands to be repeated using the up and down arrow keys.

The .help command gives a list of available commands. You can also specify a command name, i.e. .help s, in order to get help on a specific command.

Execution control

In order to execute commands, however, simulator execution should be halted. This can be done by Run/Break (F8) or by Break (Ctrl+Break). Once execution has been halted, the title bar will change to indicate that the simulator is stopped and all of the debug panes will be updated with the current emulation status. No changes will occur to emulation until a command is given.

The t (trace) command allows the emulation to be single-stepped under debugger control. The trace command runs the simulator until the CPU has completed executing an instruction, after which it is halted again and the current execution state is reported. If an interrupt occurs, the simulator will step into the interrupt handler routine.

For cases where a particular execution path is being followed, the s (step) command is useful. It acts like the trace command except that any interrupt handler or subroutine call is stepped through automatically. If the simulator has already stepped into a subroutine, the gr (go until return) command will execute instructions until the subroutine is complete.

While it is possible to debug a program using the t, s, and gr commands in the command line, these commands are so frequently used that they have shortcuts: Step Into (F11), Step Over (F10), and Step Out (Shift+F11).

The go (g) command resumes execution. Its analogous GUI command is Run/Break (F8).

Setting breakpoints

Breakpoints allow the simulator to automatically break into the debugger when a specific condition is reached, permitting much faster debugging than just manually stepping the program since the program runs at full speed while the debugger waits for a breakpoint to fire. A common approach is to use breakpoints to detect an particular condition and then single-step the program around the area of interest.

The most common type of breakpoint is a PC breakpoint. These are set with the bp (breakpoint) command, and listed or cleared with the bl (breakpoint list) and bc (breakpoint clear) commands, and cause the simulator to break into the debugger when the CPU PC register equals certain values. There is no limit to the number of PC breakpoints that can be set, and breakpoints persist until cleared. Since PC breakpoints are also a frequently used feature, they can be toggled in the GUI by selecting an instruction in the Disassembly view and pressing the F9 key. The Disassembly view shows a red background on any instruction on which a breakpoint is set.

Unlike traditional on-machine debuggers which may insert BRK instructions into the instruction stream to implement breakpoints, breakpoints in Altirra work by address matching. Memory is never modified by a breakpoint, and they can be placed even in ROM or on hardware registers. Execution timing is also unaffected by breakpoints.

Altirra also supports memory access breakpoints, which allow detection of reads or writes to a particular address. These are set and cleared using the ba (break on access) command. Memory range breakpoints can also be set, which trip whenever any location within the memory range is accessed.


Altirra Help: Source-level debugging

Source-level debugging

While it is possible to debug a program via disassembly, doing so is an arduous task, particularly with large programs. Altirra supports both symbolic and source level debugging to make it easier to debug.

Contents
  • 1. Generating and hooking up symbols
  • 2. Generating symbols with specific toolchains
  • 3. Debugging at listing or source level

Generating and hooking up symbols

In order for Altirra to provide an enhanced view of the program, there must be symbols available for objects in memory. Symbols indicate label addresses and source line positions to the debugger, allowing the debugger to match addresses and disassembly from the simulator with the source code of the program. Altirra includes symbols for the hardware and OS page zero and page two/three databases, but symbols must be provided for any additional programs that are loaded.

There are several types of symbols:

Labels
Matches addresses in memory to label names in the program source. When labels are loaded, Altirra displays label names instead of raw addresses in disassembly, and commands which take addresses can also take label names.
Listing
Displays a list of all instructions in the program along with source code lines, along with their generated addresses and opcodes. This permits a limited form of source code debugging, where execution can be traced through the listing. Listings are produced by assemblers.
Source/line information
Matches addresses of instructions in the program with source code lines. This allows full source-level debugging, where tracing and breakpoint control can occur directly in source code.

Files containing symbols can be loaded and unloaded manually using the .loadsym and .unloadsym commands. When booting an executable using the Boot Image command, Altirra will automatically load any symbol files that have the same name and path as the executable and one of the extensions .lst, .lab, or .lbl.

Generating symbols with specific toolchains

In order to generate symbols, appropriate options have to be set on the assembler or compiler generating the program:

MADS 1.9.x (assembler)
Use -t to generate labels and -l to generate a listing. Full label translation, listing-level, and source-level debugging are possible with this assembler.
XASM 3.0.x (assembler)
Use /t to generate labels and /l to generate a listing. Full label translation, listing-level, and source-level debugging are possible with this assembler.
ATasm 1.07 (assembler)
Use -l:program.lab to generate labels; only label translation is supported. Source-level debugging is not possible with ATasm since it does not output source line information in its listing.

Debugging at listing or source level

A program can be debugged at listing level through the Debug > Open Source File... command. This opens a source code view window with the contents of the listing file. Any lines that are detected to correspond to instructions are displayed with a white background, and other lines have a gray background. When broken into the debugger, the current line is shown in amber, and any breakpoints in red. The Step Into (F11), Step Out (Shift+F11), Step Over (F10), and Toggle Breakpoint (F9) commands work in the source code window. In addition, the Go command has an F5 shortcut in source windows.

When source/line information is available, the Open Source File command can also be used with the original source code files. Again, lines with a white background indicate that source information has been hooked up correctly and that stepping and breakpoints can occur on source lines. In addition, you can jump between source code and disassembly through Go to Source Code and Go to Disassembly commands on the context menus of the source and disassembly views. Unlike in disassembly and listing views, the stepping commands step by a source line in the source view.


Altirra Help: Addresses and expressions

Addresses and expressions

Many debugger commands take addresses or expressions as arguments.

Contents
  • 1. Addresses
    • 1.1. Extended addressing
  • 2. Expressions
    • 2.1. Constants
    • 2.2. Grouping
    • 2.3. Arithmetic operators
    • 2.4. Relational and logical operators
    • 2.5. Bitwise operators
    • 2.6. Low and high byte operators
    • 2.7. Memory access operators
    • 2.8. CPU register operators
    • 2.9. ANTIC register operators
    • 2.10. Breakpoint context operators
  • 3. Length expressions

Addresses

Simple addresses can be either specified in default base, as set by the .base command, or in hex using a $ prefix. The default base is mixed, which selects hex for simple addresses and decimal for numbers in expressions.

Extended addressing

For commands that support extended addressing, 24-bit and alternate memory space addresses can be used.

24-bit addresses can be specified in bank+offset form using a : to separate the bank and offset, e.g. $01:0000. A $ prefix selects hex for both the bank and the offset together.

The n: prefix selects ANTIC address space, v: selects VBXE memory, x: selects PORTB-based extended RAM, and r: selects primary RAM.

Expressions

Constants

Constants may be specified in the default base, base 16 (hex), or base 2 (binary). Hex numbers are preceeded by $ and binary numbers by %. In mixed base mode, expressions beyond a simple address use decimal constants.

A : may be used to select an alternate address space or a banked 24-bit address.

Grouping

Parentheses () are used to group subexpressions. They do not request memory indirection in the debugger as they do in 6502 assembly language.

Grouping parentheses can also be used to force expression evaluation instead of address evaluation.

Arithmetic operators

The +, -, *, /, and % operators perform arithmetic addition, subtraction, multiplication, division, and modulus, respectively. All arithmetic is performed according to 32-bit, two's complement signed integer rules.

Relational and logical operators

<, <=, >, >=, =, and != binary operators compare two values, evaluating to 0 for false and 1 for true. Note that unlike C-inspired programming languages, the equality operator is a single = and not ==.

and and or perform logical AND or OR combination and evaluate to 1 if both arguments and/or non-zero and 0 otherwise.

The unary ! operator does logical inversion, evaluating to 1 if the argument is zero and 0 otherwise.

Bitwise operators

&, |, and ^ are bitwise AND, OR, and XOR operators. ~ is bitwise inversion.

Low and high byte operators

< and > are unary operators that return the low and high bytes of a 16-bit argument. They operate similarly to the low and high byte prefixes used in 6502 assembly language.

Memory access operators

The db, dsb, and dw unary operators read an unsigned byte, signed byte, and unsigned word from memory given an address.

CPU register operators

The pc, x, y, s, and p operators return the values of the corresponding CPU registers. In 65C816 mode, the low bytes of the A, X, Y, and S registers are returned.

ANTIC register operators

hpos and vpos return the horizontal and vertical beam positions.

Breakpoint context operators

The read and write operators refer to the current memory read or write address and are used in the address tests of a memory breakpoint. They are only valid within a breakpoint condition expression.

In a breakpoint filter expression or when executing commands from a breakpoint action, the address operator returns the memory access address and the value operator returns the value read or written to memory.

Length expressions

Commands that operate on a memory range take a length parameter which begins with L, which indicates the length of the range in bytes:

f 4000 L1000 00 01 02 03
f $1600 L($a00+x) 00 01 02 03

The form L> can also be used to set the length based on an inclusive end address rather than a byte count:

f 4000 L>4FFF 00 01 02 03

Note that this takes priority over the high-byte expression operator. Parentheses can be used to force the operator:

f pagetable L(>bytes) 00 01 02 03


Altirra Help: Diagnostics

Diagnostics

Altirra's debugger allows for non-intrusive trace and assert statements to be added to assembly code.

Contents
  • 1. Prerequisites
  • 2. Trace statements
  • 3. Assertions
  • 4. Gotchas

Prerequisites

You must be using the MADS assembler and have the listing file loaded into the debugger as a symbols file for trace and assert statements to work.

Trace statements

A trace statement is a comment with the following form:

;##TRACE "format-string"arguments...

This expands to the .printf command and therefore the format string and arguments are of the same form. For instance, this will print out the current display list vector address:

;##TRACE "Display list address = $%04X" dw(vdslst)

The output of a trace statement goes to the debugger's Output window.

Assertions

An assertion statement declares that a condition should be true at a point in execution and stops execution if that turns out to be false:

;##ASSERT dw(adress) >= $0400

These are used to catch broken assumptions in code. A failed assertion will stop execution in the debugger with an "assertion failed" message.

Gotchas

Trace statements and assertions execute in the debugger context and not in 6502 code, so they are "free" and do not impact timing or any register or memory state. Therefore, unlike real hardware, they can be inserted in time critical code such as a DLI handler.

However, it is important to know that these statements are implemented as conditional breakpoints with an on-hit command. One important implication is that they are bound to the following instruction, so attempting to separate it with a label will not work:

    ;This trace statement will actually execute on each loop iteration.
    ;##TRACE "Initial loop value: %d" y
loop:
    sta    (adress),y
    dey
    bpl    loop

The second issue to be aware of is that as breakpoints they are immune to any modification from the simulation. This means that any attempt to self-modify or overlay code will be ignored by the statements, and if two routines are assembled into the same region and swapped dynamically, their diagnostics will overlap.

Finally, because trace statements and assertion statements are comments and are detected by parsing the assembler listing, they are not subject to code generation switching and will activate even if they are in a .if 0 block or other construct that would normally disable a block of code. They are affected by enabling and disabling of listing output, however (OPT L- and OPT L+).


Altirra Help: Options

Options

Altirra has a number of options that can be used to customize the emulated Atari hardware.

Contents
  • 1. View
    • 1.1. Filter Mode
    • 1.2. Stretch Mode
    • 1.3. Overscan Mode
    • 1.4. Vertical Sync
    • 1.5. Show FPS
  • 2. Hardware options
    • 2.1. 800
    • 2.2. 800XL
    • 2.3. 5200
  • 3. Firmware options
    • 3.1. Default
    • 3.2. 800 (OS-A)
    • 3.3. 800 (OS-B)
    • 3.4. 600XL/800XL
    • 3.5. Other OS
    • 3.6. HLE Kernel
    • 3.7. LLE Kernel
    • 3.8. 5200
    • 3.9. 5200 LLE
  • 4. Memory size options
    • 4.1. 16K
    • 4.2. 48K
    • 4.3. 52K
    • 4.4. 64K (XL)
    • 4.5. 128K (130XE)
    • 4.6. 320K
    • 4.7. 576K
    • 4.8. 1088K
  • 5. Video options
    • 5.1. NTSC
    • 5.2. PAL
    • 5.3. SECAM
    • 5.4. Frame blending
    • 5.5. Interlace
    • 5.6. VBXE
    • 5.7. Use VBXE memory for expansion
    • 5.8. Use $D7xx for VBXE registers
    • 5.9. NTSC artifacting (standard)
    • 5.10. NTSC artifacting (high)
    • 5.11. PAL artifacting
    • 5.12. Enhanced text output (hardware intercept)
  • 6. Disk options
    • 6.1. SIO patch
    • 6.2. SIO override detection
    • 6.3. Burst (standard)
    • 6.4. Burst (polled / SDX compatible)
    • 6.5. Accurate sector timing
    • 6.6. Show sector counter
  • 7. Cassette options
    • 7.1. SIO patch
    • 7.2. Auto-boot on startup
    • 7.3. Load data as audio
  • 8. CPU options
    • 8.1. Record instruction history
    • 8.2. Track code paths
    • 8.3. Stop on BRK instruction
    • 8.4. Enable illegal instructions
    • 8.5. CPU model > 6502C
    • 8.6. CPU model > 65C02
    • 8.7. CPU model > 65C816
  • 9. Audio options
    • 9.1. Stereo
    • 9.2. Non-linear mixing
  • 10. Misc options
    • 10.1. Warp speed
    • 10.2. Pause when inactive
    • 10.3. Accelerated floating point
    • 10.4. Printer
    • 10.5. R-Time 8

View

Filter Mode

Selects the interpolation mode for the display. Point gives the sharpest display, but can give artifacts depending on the scaling factor. Bilinear generates a smoother display. Bicubic generates an even higher quality display, but can be slow on some video cards.

Filter modes are not available unless a Direct3D 9 video card is available; if Altirra is running in DirectDraw or GDI mode, filtering is controlled by the OS or video card driver.

Stretch Mode

Controls how the display is stretched to fit the screen. Fit to Window just stretches, regardless of how it distorts; Preserve Aspect Ratio attempts to match the aspect ratio that would be seen on a properly adjusted TV set. Square Pixels always assumes square pixels instead, which is mostly the same for PAL, but noticeably different for NTSC. Integral Square Pixels is similar, but also ensures that the scaling factor is always an integer, which prevents distortion in Point filter mode.

Overscan Mode

Selects how much of the display is visible. Normal only shows the maximum visible playfield region; Extended shows additional border regions that are visible on some TV sets. Full expands the display to cover the entire video signal, even horizontal and vertical blank regions.

The Extended PAL Height option enables viewing of additional scan lines above and below the normal picture area. This is only useful when running software that explicitly uses a special trick to display more than the 240 scan lines normally allowed by ANTIC.

Vertical Sync

Lock the display to the vertical sync period, thus reducing the amount of tearing seen on screen.

Show FPS

Display the current emulator performance in frames per second in the window caption. This can introduce occasional glitching into the video output.

Hardware options

800

Enables the base Atari 800 hardware.

800XL

Enables Atari 800XL/130XE hardware features.

5200

Enables Atari 5200 SuperSystem hardware features.

Firmware options

Default

Chooses either the OS-B ROM for 800 hardware or the XL ROM for 800XL hardware if available; otherwise, defaults to the built-in HLE kernel.

800 (OS-A)

Selects the OS-A version of the Atari 800 firmware. You must have ATARIOSA.ROM for this to work.

800 (OS-B)

Selects the OS-B version of the Atari 800 firmware. You must have ATARIOSB.ROM for this to work.

600XL/800XL

Selects the Atari 800XL firmware. You must have ATARIXL.ROM for this to work.

Other OS

Loads OTHEROS.ROM as firmware, if present. This firmware must be for the XL series (16K).

HLE Kernel

Selects the internal high level emulation (HLE) kernel, which executes kernel calls in native code. No firmware is required. This is the next best mode to use when no real kernel ROM is available.

LLE Kernel

Selects the internal low level emulation (LLE) kernel, which is a replacement kernel in pure 6502 code. No firmware is required. This mode is partially complete and will boot some software. Enabling the disk SIO patch is recommended.

5200

Selects the Atari 5200 SuperSystem firmware. You must have ATARI5200.ROM for this to work.

5200 LLE

Selects the internal 5200 low level emulation (LLE) kernel, which is a replacement kernel in pure 6502 code. No firmware image is required. This is the default for 5200 mode if the ATARI5200.ROM image is absent.

Memory size options

16K

Standard Atari 400/600XL/5200 configuration with RAM from 0000-3FFF. The range from C000-CFFF is unconnected.

48K

Standard Atari 800 configuration with RAM from 0000-BFFF. The range from C000-CFFF is unconnected.

52K

Extended Atari 800 configuration with RAM from 0000-CFFF.

64K (XL)

Standard Atari 800XL configuration with RAM from 0000-FFFF, with the upper 14K swappable with Kernel ROM via PORTB.

128K (130XE)

Atari 130XE configuration with main ROM from 0000-FFFF and external RAM bank switched via a window at 4000-7FFF. This mode supports ANTIC bank switching.

320K

Extended Atari 800/800XL configuration with an additional 12 banks of memory. This mode supports ANTIC bank switching.

576K

Extended Atari 800/800XL configuration with an additional 28 banks of memory. This mode does not support either ANTIC bank switching or enabling BASIC.

1088K

Extended Atari 800/800XL configuration with an additional 60 banks of memory. In addition to disabling ANTIC banking and BASIC, this mode also takes an additional bit in PORTB.

Video options

NTSC

Selects NTSC ANTIC/GTIA operation, including aspect ratio and a 60Hz refresh rate. This is the configuration used by the original 8-bit Ataris and is recommended for most commercial software.

PAL

Selects PAL ANTIC/GTIA operation, including aspect ratio and a 50Hz refresh rate. This is recommended for demos since many are written in Europe.

SECAM

Selects PAL ANTIC operation with a SECAM GTIA (FGTIA), including aspect ratio and a 50Hz refresh rate. This is used for verifying compatibility against SECAM systems, which have a couple of quirks in GTIA mode 9 rendering and in cartridge sensing.

Frame blending

Averages adjacent frames together to reduce flickering with programs that use alternating frames to multiplex sprites or increase apparent frame buffer depth.

Interlace

Enables display of interlaced fields (480 scan lines) instead of the standard 240 scan lines. This is only useful when running software that supports interlaced display.

VBXE

Enables Video Board XE (VBXE) emulation. This is an internally installed module with 512K of VRAM and a custom FPGA core that greatly expands the video capabilities of the 8-bit Atari. The FX 1.20 core is emulated.

Use VBXE memory for expansion

When VBXE emulation is also enabled, this option causes extended memory mapped through the PIA (most expansion modes) to overlap memory used by VBXE. This matches the extended memory emulation done by the FX1.20r core. If disabled, the memories are separate as with the FX1.20a core.

Use $D7xx for VBXE registers

Locates the VBXE registers at $D7xx instead of $D6xx. This is sometimes done on actual hardware to avoid conflicts with Parallel Bus Interface (PBI) devices.

NTSC artifacting (standard)

Enables emulation of false colors from alternating high resolution pixels with NTSC video encoding. This is necessary to see colors in some games that use artifacting, such as Choplifter and Pitstop II.

NTSC artifacting (high)

Emulates NTSC artifacts by simulating the NTSC decoding process. This produces artifacts that are more realistic. However, the picture is also blurrier due to NTSC limitations.

PAL artifacting

Enables emulation of false colors from chroma blending in the delay line of a PAL video decoder. This gives more accurate color output in programs that alternate color and grayscale lines to increase the effective color depth.

Enhanced text output (hardware intercept)

Replaces the standard emulated video display with a text screen using native Windows fonts. This disables emulation of most Atari video features and only supports basic text modes, but produces a higher quality text display.

Disk options

SIO patch

Intercepts and accelerates disk I/O calls to the serial input/output (SIO) and disk (DSKIN) routines in the kernel. This tremendously speeds up disk access in the emulated programs.

Some demos or protected apps may not be compatible with the SIO patch, however.

SIO override detection

Enables detection for custom OS or PBI device firmware that override disk drive accesses. When this option is enabled, SIO patch based acceleration does not activate for a drive after reset until that disk drive has received a command. If firmware is intercepting accesses to the disk, this will prevent the hook from activating. This allows some disks to be handled by firmware while others use SIO patch acceleration.

Activating this option will disable the nonexistent disk acceleration of the Fast Boot option.

Burst (standard)

When enabled, the disk drive sends data across the SIO bus as fast as the program can accept it. This is useful for speeding up disk loads for programs that use custom SIO routines. It will, however, cause the foreground task in the Atari to run very slowly during the transfer. This mode is compatible with the ROM kernel, Atari DOS, and most programs and games.

Burst (polled / SDX compatible)

Uses a burst mode to accelerate disk transfers for programs that drive the SIO bus in a polling loop instead of by interrupts, particularly SpartaDOS X.

Accurate sector timing

Causes the emulator to simulate rotational delays caused by sector position and seek delays (step and head settling time). This results in a slower disk load, but is sometimes necessary to load protected disks.

When disabled or when the SIO patch is enabled, Altirra still attempts to track disk rotation for protected disks. This means that CPU timing is not preserved, but rotational position is still noted.

Show sector counter

Displays the current sector being read or written instead of the unit number in the on-screen indicator.

Cassette options

SIO patch

Intercepts and accelerates cassette I/O calls to the serial input/output (SIO) routine in the kernel. This greatly speeds up cassette loads.

Auto-boot on startup

Automatically holds down START during system startup and then hits a key to initiate a cassette tape load. This only works with cassette tapes that have a machine language program; BASIC tapes must be loaded via CLOAD at the BASIC prompt instead.

Load data as audio

Converts the data from a .CAS tape image into raw audio data so it plays through the speaker.

CPU options

The first three options should not be used unless you are debugging code in the interactive debugger, as they will slow down execution or cause debug breaks in code that may be executing normally.

Record instruction history

Causes the CPU to record a trace record for every instruction executed.

Track code paths

Enables tracking of all memory where instructions are executed and which instructions are branch or call targets.

Stop on BRK instruction

Causes the debugger to stop when a breakpoint (BRK) instruction is executed. This often indicates that the Atari has crashed.

Enable illegal instructions

Allows execution of undocumented NMOS 6502 instructions, which are used by some programs. This only works in 6502C mode.

CPU model > 6502C

Selects the base NMOS 6502C as the CPU model. This is the CPU type used by all official Atari models.

CPU model > 65C02

Selects the CMOS 65C02 as the CPU model, which contains some extra instructions. This is occasionally used as a homebrew upgrade option. It may introduce some compatibility problems with games.

CPU model > 65C816

Selects the 16-bit 65C816 as the CPU model, which contains many more instructions and a new 16-bit native mode. This is used in some homebrew and commercial accelerators to both increase speed and memory address space.

In Altirra, the 65C816 processor still runs at 1.79MHz. However, 24-bit addressing is supported, and there is an additional 192K of memory in banks $01-03.

Audio options

Stereo

Enables a second POKEY. Addresses in the D2xx range with bit 4 clear address the left channel, and addresses with bit 4 set address the right channel. The IRQ and serial facilities of the second POKEY are active but unconnected.

Non-linear mixing

Emulates the effective mixing curve of the hardware, which causes the output of two voices to be lower than the sum of their volume levels. This is needed for some effects and also causes some compression of the output.

Misc options

Warp speed

Disables the speed limiter and audio sync, and runs the emulator as fast as possible.

Pause when inactive

When set, causes Altirra to pause emulation when its window goes inactive. Use this to prevent the emulated Atari from using CPU time when in the background.

Accelerated floating point

Intercepts known entry points in the floating point library with native math routines. This accelerates Atari decimal math to a large degree, particularly speeding up Atari Basic.

The emulated FP library is higher accuracy than the real library due to better rounding and use of native math routines, so it will produce slightly different results.

Printer

Enables printer emulation. When enabled, any output sent to the OS P: device goes to the printer pane instead, where it can be viewed or copied out.

R-Time 8

Enables emulation for the R-Time 8 cartridge, which reflects the real system time.


Altirra Help: MyIDE emulation

MyIDE emulation
  • 1. Setting up hardware emulation
    • 1.1. Hard drive capacity
    • 1.2. I/O region
    • 1.3. Device speed
  • 2. Software support
    • 2.1. Disk-based driver
    • 2.2. Flash-based driver
    • 2.3. Custom OS kernel ROM

Setting up hardware emulation

Both the internal and cartridge varieties of the MyIDE interface are supported. To enable MyIDE emulation, select System > Hard disk... from the menu, and specify an image file to use for the emulated hard drive in the MyIDE section.

Hard drive capacity

The capacity of the emulated IDE hard drive is specified in megabytes. Note that the space available to the Atari is generally less, since only 128 or 256 bytes per sector are used. This means that only one-quarter to one-half of the drive capacity is used. Regardless, the hard drive image file always contains the full 512 bytes per sector.

I/O region

Two I/O regions can be used for the IDE interface. Select $D5xx as the interface region for a cartridge-based interface, and $D1xx for an internal interface.

Device speed

The emulated device can run at either slow or fast speed. At fast speed the emulated device responds almost immediately to commands, simulating a solid state device. At slow speed, there is additional moderate delay in command completion, comparable to average access time for a traditional hard disk.

Software support

Altirra does not include software to make use of the emulated IDE drive. You can use the MyIDE firmware or software, however. Consult the documentation for the software for full details, but here are some starting tips:

Disk-based driver

Boot the MyIDE-OS loader disk and wait for the load to complete. Once MyIDE-OS has loaded, either use the Open Image... command to swap the disk in D1:, or eject the disk in Disk Images. Do not use Cold Reset (Shift+F1), as this will kick out the soft-loaded OS. Use Ctrl+Shift+\ on the host keyboard to send Ctrl+Shift+Esc to the emulation, which initiates a soft-cold-reset.

Flash-based driver

You will need to convert the cartridge flasher disk image to a cartridge image by mounting an empty 1Mbit cartridge and then booting the flasher disk. Do not mount a 1Mbit+IDE cartridge as this does not currently work with the flasher. Once the emulated cartridge has been flashed, save the cartridge as a headerless image and remount it in flash+IDE mapping mode. Use $D500-D51F as the I/O window for the IDE interface.

Custom OS kernel ROM

Rename the MyIDE OS image as otheros.rom in the Altirra program directory and switch the firmware mode to Other OS. Use $D500-D51F for the external interface or $D1xx for the internal interface.


Altirra Help: Ultimate1MB emulation

Ultimate1MB emulation
  • 1. Basic setup
    • 1.1. Hardware description
    • 1.2. Flashing the firmware
  • 2. Gotchas
    • 2.1. Entering the BIOS menu
    • 2.2. Inactive menu items
    • 2.3. PBI disk emulation
    • 2.4. SIDE SpartaDOS X cartridge
    • 2.5. Reflashing the firmware

Basic setup

Hardware description

Ultimate1MB is a hardware expansion that provides 1MB of memory, flashable BIOS/BASIC/GAME slots, SpartaDOS X, real-time clock, and SIDE parallel bus interface (PBI) disk emulation facilities.

Altirra emulates the U1MB with version 2 of the CPLD firmware, which includes PBI support.

Flashing the firmware

U1MB has 512KB of flash memory that must be loaded with an image containing both a BIOS and an OS. The BIOS is needed to initialize the U1MB hardware prior to handing control over to a conventional OS.

Altirra does not come with the U1MB firmware, which must be obtained separately. However, it does contain a recovery image with a minimal BIOS and OS that can be used to run the flasher disk to load the real hardware. Alternatively, if the image is available in raw image form it can be bound directly through the System | Firmware | ROM images menu item.

Gotchas

Entering the BIOS menu

The U1MB BIOS has a menu that is accessed by holding down the Help key while powering on or resetting the computer. In Altirra, it is easier to enter this mode if the keyboard mode is switched from cooked keys to raw keys.

Inactive menu items

When U1MB is enabled, the addressing for VBXE, SoundBoard, and Covox devices is controlled by the U1MB mapping hardware and needs to be set through the U1MB BIOS. Similarly, the memory sizing modes do not apply when U1MB is enabled as the U1MB hardware emulates various memory models under software control.

PBI disk emulation

When PBI disk emulation is enabled in the U1MB BIOS, the SIO Patch and Fast Boot options should be disabled or the SIO Override Detection mode should be turned on. Otherwise, the emulator can intercept disk accesses before the PBI BIOS does and prevent the PBI disk emulation from working.

SIDE SpartaDOS X cartridge

If a SIDE cartridge is used with U1MB, the SpartaDOS X (SDX) facility on the SIDE cartridge should be disabled. The reason is that the SIDE SDX and the U1MB SDX mapping registers overlap and this can cause difficulty in disabling SDX. A symptom of this conflict is that the PBI BIOS hangs on startup because it cannot unmap the SDX cartridge.

Reflashing the firmware

Altirra emulates the flash memory in the U1MB, so it is possible to reflash the U1MB to newer firmware in the same manner as on the real hardware. However, an important caveat that applies equally to the real and emulated hardware is that SIDE PBI support should be turned off in the U1MB BIOS prior to running the flasher. Otherwise, the flasher will fail by erasing the PBI BIOS and then calling into it via a disk read request, resulting in a crash and bricking the U1MB. Fortunately, under emulation this is simple to recover from.


Altirra Help: Serial port emulation

Serial port emulation

Altirra partially emulates the serial port side of the Atari 850 Interface Module, as well as a Hayes-compatible modem.

Contents
  • 1. R: handler
    • 1.1. Feature support
  • 2. Modem emulation
    • 2.1. Escaping to command mode
    • 2.2. Inbound calls
    • 2.3. Dialing out
    • 2.4. Terminating a call
    • 2.5. Stored profile
  • 3. Options
    • 3.1. Telnet emulation
    • 3.2. Automatic CR/LF conversion
    • 3.3. Extended baud rate support
    • 3.4. Connection speed
    • 3.5. Force DTE rate to match connection speed

R: handler

Access to the serial port is provided by means of the CIO R: device. This is provided by a high-level handler, so this does not result in a reduction of available memory as with the original 850 R: handler, nor is there a need to load the handler from disk.

There is currently no support for emulating the 850 device on the SIO bus.

Feature support

Units | R1-R4:
Block mode | Not supported
Continuous mode | Always enabled
Baud rates | All standard 850 rates emulated; Atari800 extended modes available by option
Data bits | 8 data bits only
Stop bits | Ignored
Input parity | Cleared, but not checked
Output parity | Supported
Control signals | Carrier detect (CRX) and Data Terminal Ready (DTR) supported
Input buffer | Default buffer (32 byte) and external buffer supported
Output buffer | Supported (32 byte)
Translation | All modes supported (light, heavy, none)
EOL-to-CR/LF | Supported

Modem emulation

Altirra emulates a Hayes-compatible modem in order to provide line control and answer/dial support. Supported commands are:

A/ | Repeat last command.
ATA | Answer incoming call. Reports NO CARRIER if there is currently no incoming connection.
ATB | Change communication standard (currently ignored).
ATD | Dial out.
ATE | Change command echo mode.
ATH | Hang up.
ATL | Change speaker loudness (currently ignored).
ATM | Change speaker mode (currently ignored).
ATO | Exit command mode and return to online mode.
ATP | Switch to pulse dialing.
ATQ | Enable or disable quiet response mode.
ATS/AT= | Set or query S-registers (S0, S2, S3, S4, S5).
ATT | Switch to tone dialing.
ATV | Enable or disable verbose response mode.
ATX | Change extended result codes mode (stored but ignored).
ATZ | Reset mode to default (power-up) state.
AT&C | Set carrier detect mode.
AT&D | Set DTR (Data Terminal Ready) handling.
AT&F | Reset to factory default settings.
AT&G | Select guard tone (stored but ignored).
AT&P | Select pulse dial make/break ratio (stored but ignored).
AT&T | Local analog loopback test (stored but ignored).
AT&V | Display current profile.
AT&W | Store current configuration.

The modem starts in command mode.

Escaping to command mode

In order to return to command mode after establishing a connection, the sequence +++ must be transmitted with the proper guard time before and after the sequence (time determined by S12). This can only be done from the local side; the sequence is ignored if sent from the remote side. The Time Independent Escape Sequence (TIES) is not supported, as it is not data transparent like the guarded sequence.

Inbound calls

Inbound connections are supported, if enabled. When the modem is idle and listening is enabled, an incoming connection is immediately accepted, but no transfers take place until the modem connection is enabled. The modem reports RING responses in this state, and will establish a full connection if either the ATA command is issued or the auto-answer register (S0) is set.

By default, both IPv4 and IPv6 connections are accepted if supported by the host. IPv6 connections can be disabled in serial port options. Only one connection can be active at a time.

Dialing out

The dial command (D) is used to connect across the network to a server using TCP/IP. The syntax for doing this is as follows:

ATDI hostname port

(This syntax is compatible with that used by the Atari800 emulator.)

For instance, to connect to a telnet server on the local machine, you could use atdi localhost 23 or atdi 127.0.0.1 23. If the host OS is IPv6 capable, you can also connect to IPv6 based addresses.

If a connection is successfully established, you will get a CONNECT banner as with a real phone line, and the modem will switch to the online state. If the connection fails, the modem will emit a NO ANSWER result code instead.

Outbound connections must be enabled in serial options for the Dial command to function. If outbound connections are disabled, any attempt to dial out will result in a NO DIALTONE response.

Terminating a call

If the server ends the connection gracefully, such as a web server ending transmission, the modem will drop the call with NO CARRIER once the remaining data in the connection has been read by the guest program.

If the connection drops less than gracefully, the modem will emit NO CARRIER immediately.

The connection can be terminated at any time by sending the ATH command.

Stored profile

The AT&W command allows writing to the stored profile, which is necessary to make the ATZ command work; some programs rely on being able to change the profile restored by a soft reset. However, there is no actual non-volatile storage on the modem; a cold reset of the simulation will reset both the active and stored profiles to factory default. This prevents stored profiles from persisting across a cold reset.

Options

Telnet emulation

Telnet emulation allows the emulated program to connect to a server that uses the Telnet protocol by escaping command bytes and processing incoming commands. This is necessary as some Telnet servers will not send any data until protocol options have been negotiated. For incoming connections, the Telnet emulation code will also attempt to disable local echo on the remote terminal. All requests to change options from the remote side are declined.

If Telnet emulation is disabled, then raw data is transferred in both directions without protocol translation. However, any translation modes requested on the R: device will still activate.

Automatic CR/LF conversion

The Telnet protocol requires that CR/LF be used as the line ending. While this is fine for text sent to the terminal, the LF is not usually expected on the incoming side. When this option is enabled, the network code will ensure that outgoing line endings are normalized to CR/LF and incoming line endings to CR only. This can fix problems with BBS software showing bogus keystrokes after a return due to the LF. The downside is that this translation prevents binary transfers from working correctly.

If an ATASCII EOL ($9B) is received from the remote side on an incoming connection, CR/LF translation is automatically disabled for that session. This allows full binary transparency for ATASCII connections.

Extended baud rate support

Enables support for extended baud rates, as supported by the Atari800 emulator. In this mode, the following alternate baud rates are available from XIO 36:

Encoding | Baud rate
0001 | 57600 baud
0011 | 115200 baud
AUX1 bit 6 = 1 | 230400 baud

Connection speed

By default, connections are reported as simply CONNECT. The connection speed option allows the connection speed to be set and to force that connection speed to appear in the response, e.g. CONNECT 2400. This is useful for software that checks the reported connection speed.

Force DTE rate to match connection speed

The baud rate set on the serial port controls the maximum data transfer rate in both directions; the network code buffers data both ways, but it is throttled according to the baud rate set on the R: device. If the terminal software running in emulation doesn't detect the connection rate properly on incoming calls, it can end up forcing a slow 300 baud connection. This option forces the modem to send and receive garbage until the correct baud rate is used, emulating the effect of baud rate mismatches in hardware and allowing detection routines that rely on that effect to work. When this is active, the character 'U' is sent in both directions until the correct baud rate is used.


Altirra Help: PCLink support

PCLink support

PCLink support allows a guest OS to access files and directories on the host machine through an SIO-based protocol.

Contents
  • 1. Configuring PCLink
  • 2. Accessing PCLink through CIO
  • 3. Accessing PCLink with SpartaDOS X
    • 3.1. Loading PCLINK.SYS
    • 3.2. Accessing files through PCLink
  • 4. Host file mapping
  • 5. SIO protocol
  • 6. References

Configuring PCLink

The menu item System > PCLink is used to configure PCLink support. The base path controls the root directory exposed to the guest OS; files and directories within this directory and in subdirectories made available.

The Allow write access option controls whether the guest OS is allowed to create or modify any files. If disabled, all write operations including file creation, modification, renaming, deletion and directory creation/removal are blocked.

The SIO patch and burst I/O transfer options under the Disk submenu also apply to PCLink, since the transfer mechanism is similar.

Accessing PCLink through CIO

Accessing the PCLink device requires special OS support; it cannot be accessed through CIO. This means that neither BASIC nor Atari DOS can normally access PCLink, and for those the H: device should be used instead.

Accessing PCLink with SpartaDOS X

To access the PCLink device with SpartaDOS X, you must be using at least version 4.43 and have the PCLINK.SYS device from the Toolkit disk.

Loading PCLINK.SYS

The PCLINK.SYS driver can be executed directly or loaded via a DEVICE PCLINK.SYS statement in CONFIG.SYS. When it loads, it should display a message like this:

  D1:PCLINK.SYS
  PCLink v0.3, dev. 6, SIO id $6F

  D1:

The /S flag can also be specified to the PCLINK.SYS driver to use the OS SIO routine instead of SpartaDOS X's SIO routine. This allows the SIO Patch option to work and permits much faster transfers.

Accessing files through PCLink

Once loaded, the PCLINK.SYS device exports a PCL: device to SpartaDOS X. Files can be copied from and to the device, and programs can be loaded from it.

Host file mapping

Since filenames are more restricted in Atari operating systems than on modern OSes, the filenames on the host must be mapped using more restricted rules. Whenever possible, files are mapped directly, but there are some limitations on the mapping:

  • Files that are 16MB (16,777,216 bytes) or larger cannot be seen or accessed.
  • Files whose names do not fit an 8.3 pattern or use characters other than A-Z, 0-9, or _ are inaccessible.
  • Filename mangling is used to avoid collisions with reserved DOS device names, such as LPT1 or COM1. These filenames are prefixed with ! on the host, i.e. !COM1.

SIO protocol

The PCLink device is accessed through SIO device $6F, using the DOS2DOS protocol. Unlike a disk image, this protocol exposes the host filesystem using a file and handle based paradigm instead as raw blocks. While documenting the whole protocol is beyond the scope of this help, here is a summary:

  • Three main SIO commands are supported: Put ($50), Read ($52), Status ($53).
  • The Put command is used to send command parameters.
  • The Read command is used to exchange command data or responses.
  • The Status command retrieves error codes and buffer sizes.
  • Supported function codes include:
    • init
    • read
    • write
    • seek
    • get file position
    • open file
    • close handle
    • get file length
    • find first file/directory
    • find next file/directory
    • change attributes
    • create directory
    • remove directory
    • change current directory
    • get current directory
    • get disk info

When the SIO patch is enabled, Altirra accelerates PCLink requests issued through the SIOV vector.

References

  • DOS2DOS protocol (external site, in Polish)


Altirra Help: Host device

Host device

The host device allows the programs using the OS character I/O (CIO) facilities to access files directly on the host file system. This is an easier way to exchange files with programs running under emulation than manipulating disk images.

Contents
  • 1. Setting up the host device
    • 1.1. Long filename encoding
    • 1.2. Burst I/O
  • 2. Accessing the host device
    • 2.1. End-of-line character translation
    • 2.2. File locking
    • 2.3. Subdirectory access
    • 2.4. Reserved host name handling
  • 3. Host device restrictions
    • 3.1. CIO access
    • 3.2. Supported special CIO commands
    • 3.3. Hook page requirement
    • 3.4. Device driver invocation

Setting up the host device

Use System > Host Device... in the menu to set up the host device.

Long filename encoding

The H: device follows DOS 2 rules for filenames, which restrict filenames to no more than 8.3. The filename encoding option allows access to files that have names which don't fit this rule by encoding the filenames within the 8.3 convention. For instance, the filename "(New disk)" is accessed as NEWDI_5M.

There is no support for long/short name tunneling with this feature, as it is intended only to allow access to files and not as a extension mechanism. All calls to create or rename a file from the emulation side will always result in the short name being used in the host filesystem, with any previous long filename lost.

Wildcards are resolved with the encoded filenames, i.e. the 8.3 filenames seen by the emulation.

Burst I/O

This option allows the host device driver to detect when CIO is doing a block read/write and accelerate the process by skipping the very slow per-byte calls that CIO normally does. This is similar to what Atari DOS does for its D: device. Disable this option if programs are receiving garbled data from GET CHARS commands.

Accessing the host device

The host device appears as an H: device in the CIO device table.

End-of-line character translation

By default, the H: device does not do any translations on read or written data. This is inconvenient for text files since the host-based text programs use a LF or CR/LF convention instead of the Atari's $9B end-of-line character. To deal with this, the host device maps H6: through H9: to the same paths as H1:-H4:, but accesses through the H6-H9: aliases do EOL conversion. On read, CR, LF, or CR/LF pairs are converted to ATASCII EOL characters, and on write, EOL is converted back to CR/LF.

All file sizes and file positions seen by the emulation are in the ATASCII version of the file stream and are consistent with GET/PUT commands.

File locking

The DOS locked file attribute is mapped to the read only attribute on the host: a read-only host file is reported as locked and the LOCK/UNLOCK FILE commands will change the host read-only status.

A different kind of locking results when the emulation opens a file: Altirra will hold an appropriate lock on the host file based on the access type. Files opened for read access will be opened with a read-only lock, and files opened for write or append status will have an exclusive lock. This has two effects, one being that it prevents other host applications from interfering with the file access, and another being that it prevents the emulation from simultaneously opening a file twice with conflicting access parameters. This also means that if the emulation tries to open a file with access flags that conflict with itself or another host application, the SDX Access Denied error code ($B0) is returned.

Subdirectory access

The H: device also allows for subdirectory access in a style similar to used by MyDOS and SpartaDOS. The directory separator may either be > or \. In addition, the special names . and .. refer to the current and parent directories from the current location.

Each of the four H: devices has also has a current directory associated with it, which is by default used to resolve relative paths. Use of a directory separator immediately after the device specifier, i.e. H:>FOO, forces resolution as an absolute path from the root regardless of the current directory. H6-H9: share the same current directory as H1-H5:.

Reserved host name handling

On Windows platforms, several base filenames are reserved for devices, including CON and LPT1. To prevent inadvertent access to these devices, any accesses from the emulation to paths with these names will be translated by the driver to use a $ prefix, resulting in a path component like $CON. This translation is bidirectional and is invisible to the emulation for both file and directory access.

If the host filesystem actually contains files named with reserved device names, as is possible with use of NT file path escaping (\\.\C:\COM1), these files will not be accessible to the emulation.

Host device restrictions

CIO access

Because H: is a CIO device, only programs and disk operating systems that use CIO to access devices will allow access to files on H:. DOS 2.0S uses CIO access and allows use of the H: device. MyDOS 4.5 and SpartaDOS 3.2 will also use H:, with some bugs related to wildcard handling.

On the other hand, SpartaDOS X does not and thus attempts to access H: will fail, as it will attempt to access D8: with its own routines. With SDX, the PCLink device should be used instead.

Supported special CIO commands

  • $20: Rename
  • $21: Delete
  • $23: Lock
  • $24: Unlock
  • $25: Point (seek)
  • $26: Note (tell)
  • $27: SDX Get File Length
  • $29: MyDOS Change Directory (chdir)
  • $2A: SDX Create Directory (mkdir)
  • $2B: SDX Remove Directory (rmdir)
  • $2C: SDX Change Directory (chdir)
  • $30: SDX Get Current Directory (getcwd)

Hook page requirement

The host device drivers requires a free page in hardware address space for the CIO device driver definition. The two pages that the host device driver can use are $D600 and $D700. If both of these pages are in use, the host device will not work. Note that this hook page can be shared with other emulated devices, like the printer.

Device driver invocation

The H: device driver has a real CIO device entry point table and real entry points that can be called from 6502 code. This includes both going through CIO and by directly accessing the entry points, as Atari Basic does for the PUT BYTE handler. However, the code at these entry points is not real as the device driver is virtual, and attempts to relocate or patch the device driver routines will fail.


Altirra Help: General issues

General issues
  • 1. PAL vs. NTSC
  • 2. Memory size

PAL vs. NTSC

The 8-bit Atari was originally created for the NTSC standard and later adapted for PAL. As such, much of commercial software was designed for NTSC. Productivity software will usually work fine on either setting, but many games will only run at their correct speed on NTSC hardware settings. These games will run correctly on PAL, but 16% too slowly.

Later software is the opposite, as much of the later and more advanced programs and games were developed in Europe on PAL hardware. Almost all demos are designed for PAL, as are the very late games that take advantage of expanded memory and push the hardware to its limits. These will run too fast or malfunction if run with NTSC timing.

Note that while almost all NTSC-designed software will run in PAL, some PAL software may malfunction in NTSC. This is usually due to the shorter vertical blank period. Screen corruption at the top of the frame is one common symptom, if the program doesn't lock up entirely.

Memory size

The typical choices here are 48K, 64K, and 320K. Very little software requires any other setting than these three.

48K was the maximum memory configuration for the original Atari 800 and is only possible in that hardware mode, as XL computers came with 64K minimum. In Altirra, selecting 48K is synonymous with switching to the 800 hardware configuration. This is generally only necessary when dealing with very old software that carelessly changes the PORTB register and accidentally swaps out the kernel ROM.

64K was the standard configuration for 800XL and 1200XL models. This memory size will support most later commercial software.

The 320K memory configuration encompasses most of the common expanded memory configurations, including the 128K of the 130XE as well as several third-party 256K expansions. This setting will run the majority of software making use of expanded memory.


Altirra Help: Program-specific issues

Program-specific issues

Some programs have bugs or are otherwise not well behaved and will malfunction in mysterious ways. This can be due to incompatibility with specific hardware or firmware configurations, timing sensitivities that manifest more or less often on emulators, or just plain bizarre bugs. This is a list of programs with known issues and under what conditions they break.

Note that there are often several versions of programs in the wild, which can display different behavior. In particular, versions that have been "frozen" and stored in a turbo-load configuration or mega-disk can act differently than the originals. Unless specified otherwise, the compatibility entries here are for the original versions.

Compatibility list

Category | Name | Issues
Applications | FoReM XL/XE/XE Pro |
 | Ice-T XE 2.72 | Major program bug
 | MicroCalc (cartridge) | Requires XL/XE OS
Demos | 1st Top Demo 1989 | Requires XL/XE OS
 | Cup of Tea | Minor program bug Requires XL/XE OS
 | Total Daze | Minor program bug
Disk Operating Systems | Atari DOS 2.5 | OS hackery
 | MyDOS | 65C816 incompatibility
 | SpartaDOS 3.2 |
 | SpartaDOS X |
Games | Alien Garden | GTIA incompatibility
 | Assault Force 3D | Requires special hardware
 | Berzerk | Minor program bug
 | Bounty Bob Strikes Back! | Expansion hardware incompatibility
 | Bubble Bobble (demo) |
 | Castle Wolfenstein | Requires writable disk
 | Choplifter (cartridge) | OS hackery
 | Cohen's Towers | Requires OS-B or 48K/64K memory
 | Crownland | Uses illegal instructions
 | DARG |
 | E.T. Phone Home! (cartridge) | Major program bug
 | Fort Apocalypse | Requires disk SIO patch off (timing)
 | Gruds in Space | Requires disk SIO patch off (timing)
 | Gyruss | 65C816 incompatibility
 | His Dark Majesty | Major program bug OS hackery
 | M.U.L.E. | Minor program bug
 | Mr. DO! | Requires disk SIO patch off (timing)
 | Parsec XL | Requires XL/XE OS
 | Preppie-II | Minor program bug
 | The Tail of Beta Lyrae | Requires writable disk
 | Transylvania | Requires disk SIO patch off (timing)
 | Twerps | Requires disk SIO patch off (timing)
 | Ultima I | Requires OS-B
 | Zebuland | Requires writable disk

Compatibility issues

Many types of compatibility issues are common enough to occur in multiple programs:

65C816 incompatibility

Program has compatibility issues with 65C816 CPUs.

Expansion hardware incompatibility

Program has compatibility issues with expansion hardware.

GTIA incompatibility

Program was designed for the earlier CTIA chip and has problems running on the newer GTIA graphics chip. The most common symptom is abnormal switching to GTIA graphics modes.

Major program bug

Issues are caused by a major bug specific to the program that also shows up on real hardware, such as a random crash. The rate of occurrence may be different in emulation, but in any case the crash is being faithfully emulated.

Minor program bug

Issues are caused by a minor bug specific to the program that also shows up on real hardware, such as audio glitches. The rate of occurrence may be different in emulation, but the minor bugs are being faithfully emulated.

OS hackery

Program does naughty things with OS code, such as copying only parts of it to RAM. This was not a recommended or supported programming practice by Atari, and can result in either failure on the HLE/LLE OSes or other custom OSes, or even failing to work on one of the standard OS-B or XL/XE OSes.

Requires disk SIO patch off (timing)

Some programs measure disk load timing to ensure that disk reads take an expected amount of time, usually to detect a copied disk. This is typically done through a timer called RTCLOK. These programs need to be run with the disk SIO patch feature disabled, as that would otherwise cause the disk load to happen too quickly. Particularly picky programs may also need accurate disk timing to be enabled.

Requires OS-B

Program requires the original 400/800 version B operating system to run ("OS-B"), which was the most common version of the OS prior to the XL/XE machines. This is usually because of dependencies on specific code or data locations that weren't guaranteed to be stable across OS versions. As a result, the program can fail if run under the HLE/LLE OSes or with another custom OS.

Requires special hardware

Program requires special hardware not usually used by other programs, such as a specific cartridge.

Requires writable disk

The program writes its current state to disk, so if the disk is write protected, it won't be able to keep track of progress and will act strangely or fail.

Requires XL/XE OS

Program requires the original XL/XE operating system to run. This is usually because of dependencies on specific code or data locations that weren't guaranteed to be stable across OS versions. As a result, the program can fail if run under the HLE/LLE OSes or with another custom OS.

Uses illegal instructions

Program uses "illegal" CPU instructions that weren't part of the official 6502 instruction set and cause weird behavior on the CPU chip. This prevents the program from running correctly on a 65C02 or 65C816 CPU.

Applications

FoReM XL/XE/XE Pro

FoReM relies on particular short response values for CONNECT messages from the modem. These were not standardized for higher baud rates. Altirra's emulated modem returns the Conexant code for 9600 baud (12), while FoReM by default expects the value returned by U.S. Robotics modems (13). Either lower the connection speed limit to 2400 baud or follow the directions in the FXL/FXE documentation to change the expected code.

The clock in FoReM XL/XE also tends to lose a couple of seconds per day because it is written to expect exactly 60 or 50 frames per second, whereas the actual Atari runs slightly slower than that (59.92 fps / 49.87 fps). A workaround is to adjust the emulator speed to 50/60Hz in Speed Options.

Ice-T XE 2.72

The keyboard click feature of this program has a bug: it calls directly into the OS K: handler's GET BYTE routine without going through CIO and without setting ICAX1Z. This causes the program to sometimes jam up endlessly transmitting the "j" character. Disabling the keyboard click and then waiting for the output buffer to drain fixes the problem.

This bug is fixed in Ice-T XE 2.73.

MicroCalc (cartridge)

Jumps directly into SIO at $E959 instead of using the SIOV vector, and so will fail unless the OS-B or XL/XE OS is used.

Demos

1st Top Demo 1989

Contains a direct jump into the XL/XE OS at $C0E2 and may fail with other OSes.

Cup of Tea

There is a bug in the IRQ handling that causes it to occasionally crash after playing the sample: it assumes that an IRQ cannot happen after it is shut off in IRQEN, but there is a one-cycle window where this can still occur.

This demo also contains a strange check for the low byte of the cold start vector (COLDSV) and forces a cold reboot if it doesn't match the address byte in the XL/XE OS, so it won't work with other OSes.

Total Daze

Due to a bug in the detection routine, this demo occasionally misdetects a single POKEY as dual POKEYs, resulting in garbled audio during the loading screen.

Disk Operating Systems

Atari DOS 2.5

Does an unsupported OS check by looking for a BCC opcode ($90) at address $EA9C in the OS ROM, and replaces the VSEROR vector if it is found. This can cause a failure with custom OSes.

MyDOS

Wraps absolute indexed addressing around the 64K address space, and thus does not work on a 65C816 CPU with 24-bit addressing.

The Load Binary command in the MyDOS menu uses a MyDOS-specific XIO call to load the binary instead of regular CIO read calls. This prevents Load Binary from working with the H: handler as the handler does not know how to handle MyDOS XIO calls.

There is also a bug in MyDOS that prevents wildcarded copies from working when using H: as the source: MyDOS passes the wrong flags when enumerating files from non-disk devices, causing the copy to fail. Specifically, it attempts to read a directory listing using an AUX1 mode of $04 (open file) instead of $06 (open directory).

SpartaDOS 3.2

While the emulator's H: device can be accessed by SpartaDOS 3, there is a bug in its COPY command that causes it to malfunction when copying from H: to a destination path:

D1:>COPY H:FILE.BIN D2:

This fails with 163 Illegal wildcard in name because COPY attempts to create a file called *.* on the destination drive. It works for copies from the regular D: device because there it issues a directory search to get the source name. The workaround is to specify a full destination filename:

D1:>COPY H:FILE.BIN D2:FILE.BIN

SpartaDOS X

SpartaDOS X uses a polling loop for SIO transfers, so regular burst I/O mode does not work with it. Use the burst (polled) mode instead.

The H: device is not supported at all by the SDX kernel, so specific drivers or tools must be used to copy to and from the emulator devices. PCLink is the recommended alternative for SDX 4.44 and above.

Games

Alien Garden

Erroneously trips GTIA video modes, resulting in colored garbage on screen during transitions.

Assault Force 3D

This game requires the SuperCharger 3D cartridge, which is used for hardware multiply/divide.

Berzerk

Some versions do not initialize SKCTL properly and therefore fail to play shot sounds.

Bounty Bob Strikes Back!

Some versions require exactly 64K of RAM to work.

Joystick control will not work if Ultimate1MB hardware is present. This is because BBSB! reads the joystick from a shadow of PORTA at $D3F0, which is blocked by the U1MB hardware.

Bubble Bobble (demo)

Some versions of this homebrew game copy the kernel into RAM, write over part of the SIO routine, and then invoke the corrupted SIO routine. This will only work in some emulators when SIO patch is enabled, bypassing the broken code; it does not work in Altirra because SIO hooks are not allowed to activate from code in RAM.

Castle Wolfenstein

This program writes to the disk during normal operation and requires read/write or virtual read/write mode to be selected.

Choplifter (cartridge)

Copies out OS ROM at addresses $E500-FEFF and $C500-CBFF, and so can fail with OSes other than the stock XL/XE OS.

Cohen's Towers

Program tries to clear PIA registers in the wrong order from within the extended memory window ($4000-7FFF), which means on a machine with 128K or more of memory it accidentally bank switches itself out of CPU address space and crashes. It works if it is running on a machine without extended memory banks (48K/64K) or on an OS that configures PIA port B for input (OS-B or LLE[OS-B]).

Crownland

Program will crash on horizontal scroll if illegal instructions are not enabled or if 65C02/65C816 CPU is selected.

DARG

The clock runs too quickly if accelerated floating-point is enabled.

E.T. Phone Home! (cartridge)

This cartridge has a protection check which requires the OS to boot within a certain amount of time. The XL/XE OS takes more time to initialize and can cause this check to fail on NTSC systems.

Fort Apocalypse

Unmodified versions of this game contain a RTCLOK check during the disk load and must be booted with the SIO patch disabled.

Gruds in Space

Unmodified versions of this game contain a RTCLOK check during the disk load and must be booted with the SIO patch disabled.

Gyruss

Wraps absolute indexed addressing around the 64K address space. This causes the game to malfunction if run on a 65C816 without memory at bank $01, by preventing it from expiring enemy explosions. It runs fine with either 16-bit addressing (bank $00 = bank $01) or with memory in that bank.

His Dark Majesty

Version 1.0 has a bug that can cause it to randomly crash due to infinite DLI interrupts if the opening animation is interrupted at certain times in the video frame. The workaround is to hit a key during the title screen instead. This bug is fixed in version 1.01.

This game will not work with some custom OSes due to copying out parts of the OS ROM for private use (the SIO routines, to be specific).

M.U.L.E.

The tiny sound glitches that occur when notes are played happen on a real Atari, too.

Mr. DO!

Unmodified versions should be run with the SIO patch disabled and with accurate disk timing enabled. The game may appear to load correctly, but will malfunction in certain game elements due to the silently failed timing check. Specifically, if a particular section of the boot process runs faster than a certain amount of time, the game will deliberately break itself and sprites will fall through to the bottom of the screen.

Parsec XL

Directly jumps into XL/XE OS at $C28A and may fail with other OSes.

Preppie-II

Has a hidden function in the game that skips levels if the buttons on paddle 4 and 5 (port 3) are pressed simultaneously. This is normally impossible on an XL/XE because there is no port 3, and although the OS mirrors port 1 to port 3 in the OS variables and the paddle buttons overlap with the joystick direction lines, it's impossible to trigger this with the joystick (it can't be both left and right). However, this can be triggered if a custom OS doesn't set PTRIG4/PTRIG5 properly.

The Tail of Beta Lyrae

Rewrites the disk to store a load counter, which is used to gradually reveal more game elements as the game is loaded more times. The game will work if the disk is write protected, but the new game elements will not appear if the counter is not already high enough.

Transylvania

Unmodified versions of this game contain a RTCLOK check during the disk load and must be booted with the SIO patch disabled.

Twerps

Unmodified versions of this game contain a RTCLOK check during the disk load and must be booted with the SIO patch disabled.

Ultima I

This game requires the OS-B kernel ROM to run. It fails on HLE or XL kernels because it has hardcoded references to keyboard translation tables in the OS-B ROM.

Zebuland

This program writes to the disk during normal operation and requires read/write or virtual read/write mode to be selected.


Altirra Help: Bugs to avoid in new programs

Bugs to avoid in new programs

There are some common errors which appear to be bugs in Altirra, but are actually bugs in the program that will manifest on real Atari hardware.

Contents
  • 1. POKEY
    • 1.1. Initialization mode
    • 1.2. Interrupt timing
    • 1.3. Asynchronous serial port clocking mode
    • 1.4. Disabling IRQs
  • 2. ANTIC
    • 2.1. Changing display lists
    • 2.2. WSYNC timing
  • 3. PIA
    • 3.1. Direction register vs. output register

POKEY

Initialization mode

Bits 0 and 1 of SKCTL control keyboard scan and debounce. They also activate POKEY initialization mode when both cleared, which resets all clocks within POKEY. Both bits should be set to 1 before attempting to play sound or transfer data on the SIO bus. Otherwise, timers using the 15KHz or 64KHz clocks will not run.

Interrupt timing

Some programs developed under emulators have been written with the assumption that 15KHz timer interrupts always occur at a specific position in the scan line. They do not; the scan line offset of the 15KHz clock is determined by when initialization mode (SKCTL bits 0-1) is ended. Manually enable and disable initialization mode if you need this interrupt to have specific timing.

Asynchronous serial port clocking mode

Bits 4-6 of SKCTL control the clocking mode used by the serial port. SIO normally changes this register to $13 during an SIO transfer, which enables asynchronous clocking for timer 4. This causes problems for audio playback if not reset, since asynchronous timing mode causes timer 4 to be locked when a byte is not being received. Resetting SKCTL to $03 before playing audio fixes the problem.

Disabling IRQs

Disabling an interrupt by writing to IRQEN while interrupts are unmasked on the 6502 does not guarantee that the interrupt will no longer occur. There is a one-cycle window after the write during which the recently disabled IRQ can still fire, which can lead to the interrupt being re-enabled if the IRQ routine does so. Masking interrupts with SEI prior to writing IRQEN safely avoids this problem.

ANTIC

Changing display lists

Display lists should only be changed during vertical blank or when display list DMA is turned off. Attempting to write DLISTL/DLISTH during the active region can cause ANTIC to read random data if the display list DMA cycle falls between the writes. When using the OS shadow registers SDLSTL/SDLSTH, the program must wait until vertical blank for the change to take effect before changing the display list itself. Failing in either case can cause ANTIC to read a display list instruction with the interrupt bit set, which can cause stray DLIs if enabled. This is often catastrophic in the case of a $C1 byte, which causes ANTIC to fire a DLI on every scan line within the active region, usually resulting in a program crash.

WSYNC timing

An STA WSYNC does not guarantee a completely stable position within the scan line. The exact cycle at which the CPU resumes execution can be up to three cycles different depending on the DMA timing on that scan line. One cycle is from possible playfield DMA at cycle 105, a second is from refresh DMA on cycle 105 or 106, and a third is from DMA on a cycle right after STA WSYNC. The third cycle of uncertainty can be eliminated by doing two STA WSYNCs in a row or by using INC WSYNC.

PIA

Direction register vs. output register

The data address for a PIA port serves as both the data direction register and the output register for a port, controlled by bit 2 of the control register. When changing memory banks, it is important to ensure that port B has all bits set to output, as the default is for all bits to be input bits. Failing to do this causes the writes to port B to be ignored as the output register will not be used for any output lines.


Altirra Help: License

License

Altirra - Atari 800/800XL/5200 emulator
Copyright (C) 2009-2010 Avery Lee

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

GNU General Public License

                    GNU GENERAL PUBLIC LICENSE
                       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Lesser General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

                    GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.

    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

  5. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

  7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

  10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

                            NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

                     END OF TERMS AND CONDITIONS

            How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) <year>  <name of author>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) year name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  <signature of Ty Coon>, 1 April 1989
  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Lesser General
Public License instead of this License.


Altirra Help: Emulation accuracy

Emulation accuracy
  • 1. Emulation goal
  • 2. Timing
  • 3. Known issues: CPU
  • 4. Known issues: ANTIC
  • 5. Known issues: GTIA
  • 6. Known issues: POKEY
  • 7. Known issues: PIA
  • 8. Known issues: Video Board XE (VBXE)

Emulation goal

It is impossible for a PC host to perfectly emulate all aspects of an Atari 8-bit computer without actually being that computer exactly. Therefore, for the purposes of grading emulation accuracy, we will define perfection as follows:

A perfect emulator is one in which a program running on the emulated architecture cannot distinguish the emulator from the real hardware.

This definition restricts evaluation criteria to only elements that are program-visible; it excludes elements such as analog audio/video output circuitry. Those elements are also important, but their quality is subjective and also varying even on real hardware. In contrast, the synchronous response of the hardware to executed program code is almost entirely deterministic and mostly well-defined.

In some cases, behavior on real hardware may vary. This includes the contents of system memory on power-on (particularly if the system has recently been turned off), and disk drive timing. In these cases, the emulated behavior should at least be possible, with ideal or better behavior being desirable.

Timing

Altirra strives for cycle-exact timing in all hardware emulation. This includes:

  • CPU memory read/write timing, including dummy instruction fetches and false read/write cycles.
  • ANTIC DMA timing. All DMA cycles, including display list, playfield, P/M graphics, and refresh DMA cycles, are spaced out in the scan line to match the hardware.
  • Mid-screen writes to all hardware registers.
  • POKEY interrupt and SIO disk transfer timing. POKEY timer interrupts fire with cycle accuracy, not scan line accuracy.

Timing on the host does necessarily vary, as the audio and video output cannot be produced with the exact timing used by the real Atari hardware. However, the emulation is stepped synchronously such that a program running under emulation does not see these timing variations.

Known issues: CPU

  • Missed DLIs are not enabled by default. On real hardware, NMIs from ANTIC are missed by the CPU if BRK or IRQ interrupt processing begins on exactly cycle 4 of a scan line where an NMI is supposed to take place. This must be enabled in CPU options in the emulator.
  • Reads from unmapped memory produce a constant value instead of the value on the floating data bus. Either behavior can occur on the real hardware depending on whether the model in question has pull-ups on the data bus.

Known issues: ANTIC

  • The invert/blink state is not correct on characters when vertical scrolling is used to replay buffered data on a character mode scan line.

Known issues: GTIA

  • Incorrect pixels may be shown during the transition when GTIA modes are switched mid-scanline with non-uniform bit patterns.

Known issues: POKEY

  • The phases of the 15KHz clock may not be correct if initialization mode is toggled off very briefly (less than 7 cycles).

Known issues: PIA

  • Not all PIA control line modes are implemented. (The only ones that are program visible are ones that affect the SIO motor or control lines, or cause interrupts.)

Known issues: Video Board XE (VBXE)

  • XDL, overlay and attribute DMA run on a per-scanline basis.
  • The blitter runs on a per scan line basis, and will not complete a blit until the end of a scan line. It does accumulate available cycles according to overlay and attribute map modes, and it does carry over unused cycles between blits in the same blit list.
  • The blitter reads blit list entries instantaneously. This means that the CPU cannot start a blit list and then overwrite the first entry before the blitter can read it, even though this is possible in rare circumstances (HR overlay, 8 pixel wide attribute tiles, executing code from a MEMAC window).
  • MEMAC accesses by the CPU do not slow down the blitter.
  • Attribute map collision is not supported.
  • Attribute map hires switching is not supported.
  • Palette 0 is initialized with the palette currently specified in System > Video > Adjust Colors instead of the laoo palette used by the VBXE hardware. This can result in color mismatches when software attempts to mix a custom palette with the cold start palette.