Altirra simulates the hardware of the Atari 8-bit computer systems, including the Atari 800, 800XL, and 130XE computers.
Key | Debugger Function |
---|---|
F8 | Run / Break / Continue |
F9 | Toggle Breakpoint |
F10 | Step Over |
F11 | Step Into |
Shift+F11 | Step Out |
Atari key | Host key |
---|---|
Start | F2 |
Select | F3 |
Option | F4 |
System Reset (Warm Reset) | F5 |
Power (Cold Reset) | Shift+F5 |
Help | F6 |
Break | F7 or 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* |
Host Key | Function |
---|---|
Alt+Shift+V | Paste text |
Alt+Enter | Toggle full-screen mode |
F1 | Warp speed |
F2 | Start |
F3 | Select |
F4 | Option |
F5 | System Reset (Warm Reset) |
Shift+F5 | Power (Cold Reset) |
F6 | Help key (computer) |
F7 | Break key (computer) |
Ctrl+F7 | Toggles PAL mode |
Pause | Break key (computer) |
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 |
Alt+Shift+C | Copy frame to clipboard (??? does not work) |
Ctrl+F1 | Toggle filter mode (??? what does it do) |
Ctrl+\ | Ctrl+Esc |
Ctrl+Shift+\ | Ctrl+Shift+Esc |
More info in Help > Contents > Debugger
Command | Description |
---|---|
r | Displays registers |
r reg val | Loads val to reg |
.dumpdsm | Dump disassembly to a file |
.writemem | Write a block of memory to a file |
Syntax: .writemem <path> <xaddress> <length> Example: .writemem c:\temp\test.txt 9000 4096 Remarks: The address may use extended memory syntax, i.e. v:4000 for VBXE memory.
Links:
Information below comes from a post in the forum AtariAge (September 10th, 2013).
Source: https://atariage.com/forums/topic/216515-debugging-using-altirra/
Assemble/run setup
6502 debugging (immediate)
6502 debugging (deferred)
6502 optimization
Audio
BASIC
Character I/O (CIO)
Disk I/O / SIO
Graphics
Expansion hardware
The following information comes from the website http://downloads.atari-home.de/Scene_Demos/r/rgba/Altirra/README.html
Getting started
By default, Altirra uses an internal kernel ROM which partially supports basic Atari kernel services, such as interrupts, display, and disk I/O. If you have cartridge or disk images already, you can use them with the emulator as-is, and some of them may work. There are also freely available demo images on the Internet you can obtain which were written by people around the world to stretch and demonstrate the power of the Atari hardware, and which you can view with the emulator if you have not seen an Atari in action before.
To load a disk, simply use the File > Boot Disk/Program… option, and select the disk image. The most common disk images are in .ATR format. If they are compressed in a .zip archive, you must extract them with a separate utility first.
Most games are compatible with the original Atari 800, and as such should use the 800 hardware mode. Some newer games that need more memory will need 800XL mode and 64K memory instead, and perhaps 128K of memory. When running demos, 800XL hardware mode with 320K of memory will run almost anything, although you should use PAL for demos as the vast majority of demos are produced in Europe.
Altirra emulates the hardware with much higher compatibility than its internal ROM emulates the kernel, so for much better success, it's recommended that you use real Atari kernel ROMs if available. These should be placed next to Altirra.exe:
With these available, you can switch the firmware to 800 OS-B and 800XL mode. I won't tell how to obtain these ROMs, and needless to say, you should only use images of the ROMs if you actually own the real ones. If you don't, you can still run a lot of software on the internal kernel, and the full Atari hardware is still emulated.
Protected disk support
If you have actual original diskettes with Atari software on them and have transferred them to your computer, you can use them with Altirra. A special trick is that Altirra can use special disk formats that allow you to run copy protected software authentically, without bypassing the copy protection. (Please heed the usual warning here about only using validly licensed software; I'll assume you own a real copy.) Two protected formats are supported.
APE (.pro):
This is the format produced and used by the Atari Peripheral Emulator (APE). Support for the .pro format was implemented by reverse engineering the protected disks (but not the program), so emulation is spotty. The PRO format works mostly by encoding the order in which phantom sectors are read by the program, so they do not truly support full emulation and must be run with the Accurate Sector Timing option disabled. Not all PRO disks will work, unfortunately.
VAPI (.atx):
This is a newer format created by a group of people dedicated to Atari software archival. Unlike the .pro format, the .atx format encodes sector positioning, which allows Altirra to actually emulate true disk read timing for a high level of compatibility. Accurate Sector Timing is recommended when using VAPI disks.
Copy protection algorithms are notoriously fickle, and thus may fail to boot without optimal settings. For maximum compatibility, use the following settings:
Many programs will boot with the SIO patch enabled, though, as it is designed to try to maintain correct sector timing even though the emulated Atari isn't actually spending time reading a sector. For programs that switch to custom disk routines, you can either use warp mode to speed the load, or try enabling the burst SIO transfer mode.
Options
Altirra has a number of options that can be used to customize the emulated Atari hardware.
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.
View > 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.
View > 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.
View > Vertical Sync
Lock the display to the vertical sync period, thus reducing the amount of tearing seen on screen.
View > 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.
Hardware options > 800XL
Enables Atari 800XL/130XE 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.
Firmware options > 800 (OS-A)
Selects the OS-A version of the Atari 800 firmware. You must have ATARIOSA.ROM for this to work.
Firmware options > 800 (OS-B)
Selects the OS-B version of the Atari 800 firmware. You must have ATARIOSB.ROM for this to work.
Firmware options > 600XL/800XL
Selects the Atari 800XL firmware. You must have ATARIXL.ROM for this to work.
Firmware options > Other OS
Loads OTHEROS.ROM as firmware, if present. This firmware must be for the XL series (16K).
Firmware options > 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.
Firmware options > 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.
Memory size options > 48K
Standard Atari 800 configuration with RAM from 0000-BFFF. The range from C000-CFFF is unconnected.
Memory size options > 52K
Extended Atari 800 configuration with RAM from 0000-CFFF.
Memory size options > 64K (XL)
Standard Atari 800XL configuration with RAM from 0000-FFFF, with the upper 14K swappable with Kernel ROM via PORTB.
Memory size options > 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.
Memory size options > 320K
Extended Atari 800/800XL configuration with an additional 12 banks of memory. This mode supports ANTIC bank switching.
Memory size options > 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.
Memory size options > 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 > 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.
Video options > Frame blending
Averages adjacent frames together to reduce flickering with programs that use alternating frames to multiplex sprites or increase apparent frame buffer depth.
Video options > 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.
Video options > 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.
Video options > 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.
Video options > 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.
Video options > 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.
Video options > 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.
Video options > 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.
Video options > 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.
Disk options > 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.
Disk options > 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.
Disk options > 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.
Disk options > 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.
Cassette options > 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.
Cassette options > 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.
CPU options > Record instruction history
Causes the CPU to record a trace record for every instruction executed.
CPU options > Track code paths
Enables tracking of all memory where instructions are executed and which instructions are branch or call targets.
CPU options > Stop on BRK instruction
Causes the debugger to stop when a breakpoint (BRK) instruction is executed. This often indicates that the Atari has crashed.
CPU options > Enable illegal instructions
Allows execution of undocumented NMOS 6502 instructions, which are used by some programs. This only works in 6502C mode.
CPU options > CPU model > 6502C
Selects the base NMOS 6502C as the CPU model. This is the CPU type used by all official Atari models.
CPU options > 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 options > 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.
Currently, the 65C816 mode does neither: the CPU still runs at 1.79MHz and there is no memory available outside of bank 0. However, this mode can run some extended BIOS and application code that makes use of 65C816 features.
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.
Audio options > 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.
Misc options > 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.
Misc options > 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.
Misc options > 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.
Misc options > R-Time 8
Enables emulation for the R-Time 8 cartridge, which reflects the real system time.
Emulation accuracy
Altirra was written with reference to the original Atari hardware and OS manuals, as well as many helpful documents on the Internet and even hardware specs and gate diagrams that have since been graciously released to the public, and is designed to target very high hardware emulation accuracy. Despite that, there are still many areas in which its behavior does not quite match that of a real Atari. Here is the known emulation status.
CPU:
Instruction execution is believed to be nearly cycle exact with an NMOS 6502C. Page crossing and false reads are implemented, including indexing retry cycles. All instructions, including illegal instructions, are supported.
65C02 and 65C816 support is still fairly experimental at this point. The 6502 emulation mode portion of the 65C816 is stable, but the native mode may have some problems. There is currently 192K of extended memory in banks $01-03.
ANTIC:
DMA is emulated at cycle level. Cycle stealing timing, including refresh DMA, is believed to be cycle-exact. There may be cases where mid-scanline changes do not take effect at exactly the right time. The timing of several registers, most notably VSCROL, VCOUNT, and WSYNC, has been calibrated to match a real Atari.
GTIA:
P/M and playfield collisions are fully supported on a per-cycle basis, undocumented priority modes are implemented, including the colorful mode 0.
Mid-scanline PRIOR-based GTIA mode changes are supported, including the false ANTIC E mode that results when switching GTIA modes on and off. The color clock position difference in Graphics 10 is also implemented.
The colors produced by Altirra are designed to provide a reasonable look. Actual colors produced by real Ataris vary considerably based on model and TV standard; PAL Ataris produce slightly different colors than NTSC models. I have seen an NTSC 130XE that actually generates fairly horrid colors, only about 12 unique hues of the 15 it is supposed to generate.
NTSC artifacting is supported.
POKEY:
All timers run on cycle granularity and output is downfiltered from 1.79MHz equivalent rate waveforms.
Two-tone mode is supported, as is serial tone beeping.
The polynomial counters use the same polynomials as the real hardware, but the sequence position seen by RANDOM may not be correct when switching between 9-bit and 17-bit polynomial mode.
POKEY serial port parameters are only partially emulated, so invalid or otherwise out-of-spec serial port parameters may work in Altirra even though they wouldn't on a real Atari.
RAM:
CPU, ANTIC, Kernel ROM, and Self-Test ROM banking are all supported, assuming they are enabled according to the current machine and memory settings.
FLOPPY DISK:
Intended to emulate an Atari 810. I even checked the 810 schematics and partially disassembled the firmware to determine the exact SIO bus transfer rates and error handling behavior.
The base 810 command set is supported, as well as a few additional extended commands (Format Medium, Read PERCOM Block, high-speed commands). The disk emulator will read and write disks with 256 byte sectors, as well as mega images of up to 65535 sectors (the max supported by the SIO protocol).
The disk subsystem emulates the rotational and seek latency of an Atari 810 when accurate sector timing is enabled. When disabled, rotational position is still simulated to select phantom sectors for VAPI disks.
CASSETTE:
Only partially implemented. The emulation is based on raw SIO waveforms and not decoded sectors; CAS files are converted to bitstreams.
When reading raw .wav files, Altirra attempts to decode the cassette similarly to the 410 hardware, with two bandpass filters and a comparator with hysteresis. As such, it should have fairly good success at decoding raw tapes.
KERNEL:
The kernel is fully compatible when using authentic Atari firmware, because, well, it IS the actual firmware.
The low level kernel is quite incomplete, but contains partial implementations of SIO, CIO, and interrupt services. SIO can boot DOS 2.0S, but in some cases it may corrupt transfers and the SIO patch bypass is recommended. Note that the low level kernel is written like a real kernel ROM, so it is not specific to Altirra and can be run on other emulators or on a real Atari.
At this point, the high level emulation (HLE) kernel actually has better compatibility than the LLE kernel. Timing-wise it will not be as good as a real 6502-based kernel, but at this point it boots a wide variety of demos and games and is now the default. There are missing features in the S: and E: device handlers that can cause glitches when running productivity software.
As noted above, the floating point acceleration does not always exactly match the results from the real floating point ROM.
PBI:
The 800XL parallel bus interface is not supported. I've never seen or touched any PBI peripherals anyway.
VBXE:
MEMAC windows, the extended display list (XDL), LR/SR/HR/text overlays, and attribute maps are implemented. This includes horizontal and vertical scrolling. Collision detection, overlay priority, and hires/CCR switching are not implemented. Transparency and extended color are partially implemented.
All features of the blitter are implemented, but the blitter currently only runs at the end of a scan line. Blitter cycle accounting does throttle the blitter according to blit size, but DMA contention is not implemented.
VBXE DMA fetches are not cycle exact or interleaved with the CPU; they are performed at the end of a scan line or at a control register write driven sync instead.