Retro-Spektro

SHOP

ATARI HDD DRIVE ACSI EMULATOR

ACSI hard drive emulator for ATARI ST, STF, STFM, STE, MEGA ST, original project acsi2stm by Jean-Matthieu COULON

Main features

Mount 3 standard SD/SDHC/SDXC cards on the Atari (FAT16/FAT32/ExFAT).
Expose raw SD cards as ACSI hard disks connected to the Atari.
Expose ACSI hard disk image files as hard disks connected to the Atari.
It also provides an UltraSatan compatible real-time clock if you add a simple 3V lithium battery such as a CR2032.

Modes

Offer access to SD cards formatted with FAT16, FAT32, or ExFAT. No additional drivers need, making it easy to transfer files between your Atari and modern PCs. GemDrive Mode

Emulates traditional ACSI hard drives and supports multiple partitions. This mode requires Atari-compatible hard disk drivers, offering enhanced compatibility with legacy software. ACSI Mode

Hardware compatibility

ACSI2STM was successfully tested on the following configurations:

  • Atari 520 STF, TOS 1.04, GemDrive + ICD driver
  • Atari 520 STE, TOS 1.60, GemDrive + ICD driver
  • Atari 1040 STE, TOS 1.62, GemDrive + ICD driver
  • Atari 1040 STE, TOS 1.62, GemDrive + PP driver
  • Atari 1040 STE, TOS 2.06, GemDrive + Atari AHDI driver
  • Atari 1040 STE, TOS 2.06, GemDrive + ICD driver
  • Atari 1040 STE, EmuTOS, EmuTOS integrated ACSI driver + GemDrive
  • Atari Mega STE, TOS 2.06, GemDrive + Atari AHDI driver
  • Atari TT030, ACSI mode (driver not specified)

GemDrive mode is currently tested on Atari ST and STE (no TT or Falcon). It probably works on the TT or the Falcon. If anybody owns this hardware and is interested, please open a GitHub issue. Testing is safe for the hardware, not for data.
TOS >= 1.04 (“rainbow TOS”) is strongly recommended because older TOS will leak a small amount of memory when a program stops. It may or may not have an impact depending on how you use the machine.
TOS replacements such as MultiTOS, MiNT or others are incompatible with GemDrive mode. Implementing multitasking in GemDrive is nearly impossible on such a small microcontroller.

SD card, partition and file system compatibility

ACSI2STM is compatible with all SD cards that can work in SPI mode, meaning most old SD cards, all SDHC and all SDXC cards. New SDUC was not tested and probably won’t work, but who needs more than 2TB on a ST ?
In GemDrive mode, the SD card must be formatted either in FAT16, FAT32 or ExFAT format, with a single partition (the standard format for SD cards). The partition size is limited to 2TB.
In ACSI mode, the SD card must be formatted with Atari tools. TOS restrictions apply.
In ACSI image mode, the SD card must be formatted with standard SD format (like GemDrive) and the image itself must be formatted with Atari tools.
Floppy disk images in ST format can be used as ACSI images and will appear as a small C drive on the ST. This won’t make games compatible though since it is not a real floppy emulator.

Emulator compatibility

ACSI images are compatible with Hatari ACSI images. Using a SD writing tool like Raspberry Pi Imager, you can transfer an image to the physical SD card.
GemDrive cards are mostly compatible with Hatari’s GEMDOS drives, with a few differences in unicode translation, long file name support or other details.
Other emulators provide similar features but were not tested.

Atari software compatibility

This section explains why some programs are compatible and some are not.

Software properly using the operating system
These programs use the normal GEMDOS interface to access disk drives. This means that they have no path restrictions and follow the rules.

Programs usually working like this:

  • Most desktop programs
  • A few games with no disk protection
  • Basically everything using the standard file selector to open files

Compatible with

  • Internal floppy disk (A:)
  • External floppy disk (B:)
  • ACSI hard disk
  • GemDrive
  • Hatari GEMDOS

Software relying on bugs
These programs use the normal GEMDOS interface to access disk drives but rely on weird patterns or buggy TOS error codes to work properly.

Compatible with

  • Internal floppy disk (A:)
  • External floppy disk (B:)
  • ACSI hard disk
  • GemDrive

Incompatible with

  • Hatari GEMDOS

Software doing BIOS access
These programs access low level disks using BIOS or XBIOS interfaces.

Programs usually working like this:

  • Most disk utilities
  • Maybe some very weirdly programmed games

Compatible with

  • Internal floppy disk (A:)
  • External floppy disk (B:)
  • ACSI hard disk

Incompatible with

  • GemDrive
  • Hatari GEMDOS

Software doing direct floppy controller access
These programs directly access the floppy controller.

Programs usually working like this:

  • Most games
  • Most programs relying on copy protected floppy disks
  • Floppy disk utilities (copy/format/repair)

Compatible with

  • Internal floppy disk (A:)
  • (not always) External floppy disk (B:)

Incompatible with

  • ACSI hard disk
  • GemDrive
  • Hatari GEMDOS

Choosing a hard disk driver for ACSI mode

GemDrive mode is recommended. However in some situations you might want to use ACSI mode with a hard disk driver.

There are many hard disk drivers for the Atari ST out there. All of them come with their pros and cons.

Here is the list of the free drivers I’m aware of, in no particular order:

ICD PRO Festplatentreiber 6.55
Free (not open source) driver that works well and is very stable.

Pros:

  • Officially supported by ACSI2STM. Tested before each release.
  • Good set of tools.
  • Supports SD card hot swap (the new SD card must have the same number of partitions).
  • Works well with GemDrive if set up correctly.

Cons:

  • Incompatible with BigDOS.
  • Eats up memory like crazy if you leave cache enabled (disable cache, ACSI2STM is nearly as fast as memcpy).
  • Not open source.


P.Putnik’s ACSID07 driver (free, 2008 version)
Pros:

  • Supports MS-DOS partition tables.
  • Compatible with BigDOS.
  • Works with GemDrive.

Cons:

  • Supports only ACSI id 0.
  • Does not support SD card hot swap.
  • Not 100% ACSI standard compliant, does funky stuff on boot (re-enables A1 mid-command).
  • Uwe Seimet’s HDDriver

Pros:

  • Fully supporting the SCSI command set.
  • Supports more than 1 LUN per drive.
  • Very high quality set of tools.
  • Supports MS-DOS partition tables.
  • Compatible with BigDOS.

Cons:

  • The free version is very limited in functionality.
  • Does not support ACSI2STM officially (later versions should work).
  • Not open source.


AHDI
The antique driver provided by Atari. While it should work, nobody seem to use it anymore.

Pros:

  • Authentic, “pure” Atari experience.
  • May be already installed on old hard disks.
  • None, really.

Cons:

  • Incompatible with BigDOS.
  • Unstable, does not always detect drives.
  • Compatible with GemDrive, but only through GEMDRIVE.PRG.
  • Supports only Atari partition tables.
  • Must start at ACSI id 0.
  • Does not support SD card hot swap.
  • Not open source.

EmuTOS
The integrated ACSI driver found in EmuTOS.

Pros:

  • Faster than Atari TOS.
  • More reliable than Atari TOS.
  • Open source.

Cons:

  • EmuTOS is not compatible with all ST programs.
  • Compatible with GemDrive, but only through GEMDRIVE.PRG.
  • Does not support SD card hot swap.

Powering the unit

Power the unit via its USB Type-C port. It has no specific power requirements, so any 5V USB Type-A to Type-C cable (or PC) should be able to power the unit. Power supplies with the Power Delivery (PD) protocol are not supported.


Backup battery

Before installing, insert a CR2032 battery in the socket. The battery is only needed for keeping the clock running when the ST is off.

Installing on the DB19 port

Plug the unit on the back of the ST, components toward the keyboard. The mounting holes of the Hard Disk socket should be aligned.
Lock screws to hold the unit in place.
Optionally, you can plug other devices such as an UltraSatan on the IDC20 socket.

Installing using the UltraSatan (IDC20) port

If you mounted an IDC20 socket, you can connect the ACSI2STM unit through it instead of the DB19 port. This is useful if you have other IDC20 devices.

On the most standard configuration (no internal hard drive, no other device), just plug the unit, power it on before turning on the ST, and there you go: a C: drive will appear that corresponds to the first SD card slot. It behaves like a floppy drive: you can insert / swap SD cards at any time without rebooting.

Setting date and time

In GemDrive mode, you can use any tool to set the date, such as CONTROL.ACC or XCONTROL.ACC available in the Language disk provided with the computer.
In ACSI mode, ACSI2STM emulates an UltraSatan clock, so you can use UltraSatan tools such as US_SETCL.PRG and US_GETCL.PRG. GemDrive mode also responds to UltraSatan clock queries as a convenience.
When the system is switched off, the STM32 clock is powered by the onboard CR2032 battery so it will keep time even when powered off.

Updating a 4.0 (or later) unit from the Atari ST

ACSI2STM supports updating the firmware from the ST itself since version 4.0. It uses the Seagate SCSI standard command to do that, this is supported by ACSI2STM both in ACSI and GemDrive modes.
Steps to update your firmware:
Download the release package and unzip it.
Choose which firmware variant you want to use.
Copy the firmware file (acsi2stm-VERSION-VARIANT.ino.bin) and rename it to HDDFLASH.BIN
Copy HDDFLASH.TOS and HDDFLASH.BIN files on any medium readable by the ST (floppy, ACSI drive, GemDrive SD card, …).
On the ST, run HDDFLASH.TOS.
When prompted, choose the hard drive to update (usually ID 0).
Press Y to start flashing.
When finished, the ST and the ACSI2STM unit will both restart.

How hard disks work on the Atari ST

This document is aimed at people who don’t have prior experience with using hard disks on an Atari ST.
It talks about general concepts, not specific to ACSI2STM. It can be useful for setting up real hardware as well as emulators.
Remember that using ACSI drivers is discouraged, you should probably use GemDrive unless you have very specific needs or want an authentic user experience (read: having a hard time struggling against old buggy software).

The physical “hard disk” port

All Atari ST and derivatives have a hard disk socket somewhere. It’s a DB19 female socket, a very rare kind that doesn’t exist anymore.
Because it doesn’t have a real name, it can be called DB19, Hard disk, ACSI or DMA port.
This port is a bus, meaning that you can plug multiple devices on the same port. Usually, devices are daisy-chained, meaning that each device has a female port that can receive another device.

IDC20 and UltraSatan connectors

Because DB19 isn’t produced anymore and hard to find, modern hardware tend to standardize around IDC20 (flat cable) connectors.
With these connectors, you can put many plugs on the same flat cable to connect multiple devices on the bus, just like PC floppy or IDE drives.

DMA plague, Bad DMA, faulty hardware

It’s so important that it needs to be mentioned in a beginner tutorial: many ST have partially faulty DMA ports. It was a very common issue that nobody suspected because hard drives were rare back in the days, so people didn’t realize that their machine had a problem.
It randomly hits a very wide range of computers, from early STF to late Mega STE and maybe even later models.

Multiple devices and ACSI ID

Hard drives use a derivative of the SCSI protocol to communicate: ACSI.
You can plug up to 8 devices on the same port. In order to separate communication between different peripherals, each peripheral is assigned a unique identifier: a number between 0 and 7 (included).
Most ACSI peripherals have a selector to assign a specific device id. Some have limited ranges, or use a fixed id.
Warning: The most important rule is: DO NOT ASSIGN THE SAME ID TO MULTIPLE DEVICES. This will lead to devices trying to output signals on the bus at the same time, which will put extra load on their internal circuitry; this could damage the hardware.
Usually, you want to start at id 0 and put devices in increasing orders.
Software also brings its own limitations about ids. This is explained later.

Mega STE internal hard drive

Some models have internal hard drives, however it seems that only the Mega STE has an internal ACSI drive, sharing the DMA port. By default it is set on the device id 0, but this can be changed by internal DIP switches.

ACSI2STM

ACSI2STM provides a set of jumpers named ID_SHIFT which can change device ids of the SD slots as well as theyr GemDrive drive letters. It can’t map to all 8 ids freely though.

Device drivers and boot process

Atari TOS doesn’t have a full hard drive driver, meaning that you can’t just plug a hard drive and hope to see a sweet C: icon on the GEM desktop.

How ACSI drivers work

When you bought a hard drive, it came with a driver on a floppy disk. The most common driver was Atari’s AHDI driver, a very bad driver full of limitations and bugs. So other companies started to sell alternative drivers that work better.
They all work on the same principle: you have a small TOS/PRG file that runs the driver itself. It is usually installed in the AUTO folder of the driver floppy disk. Along with this driver, there is a format/partitioning tool, and a boot sector installer.
The formatting/partitioning tool works just like modern ones, so there isn’t much to say about it: Format, set partition sizes, apply settings, reboot and there you go.

The boot process

Thankfully, while TOS doesn’t have a full hard drive driver, it has a boot driver. It uses the same boot routine as floppy drives:

  • For each device id, it reads the first sector (512 bytes)
  • If read fails or times out, it tries the next device id
  • If the sector has a checksum of 0x1234, it means that it’s bootable
  • If the sector is bootable, it just runs the content of the boot sector as code
  • If the boot sector code returns, it tries the next device id

So when you have a hard drive, you can use its boot sector installer to install a special boot sector on the hard drive that will load the full driver from the drive itself.
Usually, the boot sector contains code that will load a special *.SYS file at the root of the hard drive, and this file contains the actual driver.
The end result is that, once you properly installed everything, your ST won’t need floppy disks at all anymore (except protected games, but that’s a special case).

Boot floppy

TOS is a bit lost when it has no floppy disk inserted into the internal drive. Drive motor keeps spinning and some timeouts are very long, increasing boot time a lot.
There are software workarounds, but the simplest way around that is to keep a blank formatted disk in the drive at all times.

The special case of GemDrive

GemDrive takes advantage of this boot process to start itself. When the ST asks for a boot sector, the ACSI2STM unit provides the GemDrive driver embedded in its own firmware. That’s why you don’t need to specially prepare SD cards.

TOS quirks

Atari TOS has many quirks and bugs. Some of them can be worked around with tons of software patches, but no configuration was ever proven to be fully stable as soon as you start to really scale.

  • Size limitations: partitions have absolute size limitations, depends on TOS version. BigDOS tries to alleviate this, but requires compatible drivers.
  • Cluster size limitations: Windows scales FAT filesystems by increasing cluster sizes while TOS requires to scale FAT filesystems by increasing physical sector sizes. TOS fails in weird ways with Windows-style FAT filesystems.
  • Folder count limitations: If you have too many folders, things start to behave strangely. FOLDR100.PRG tries to increase limits, with various degrees of success.
  • TOS has no file/folder cache, which was provided by CACHE100.PRG.

The only way around that is not to use TOS at all, this is what GemDrive does.

GEM desktop and disk drive icons

Depending on your TOS version, GEM can be a bit mysterious about how it handles disk drive icons.
DESKTOP.INF and NEWDESK.INF

GEM can save the desktop state, including desktop icons, preferences, view mode, file extension associations and various other things.
On old TOS (TOS < 2.00) it is saved in DESKTOP.INF at the root directory of the boot disk. New TOS uses the file NEWDESK.INF that contains much more information, but it is still backward-compatible with DESKTOP.INF.
Mounted drives

TOS maintains a list of mounted drives. This is invisible to the end-user, and it differs from which icons are visible on the desktop. GEM does not provide any way to know which drives are mounted or not, and does nothing to assist you.
When you try to access a drive letter that is not mounted from the desktop, you will get the infamous The drive you specified does not exist message.
Most hard drive drivers will list mounted drives at boot.
C: drive icon

TOS handles the C: drive specially: if the drive is mounted during boot process, it will add the corresponding icon to the desktop. If the drive is not mounted during the boot process, it will actively remove the icon, even if it was present in your DESKTOP.INF file.
TOS doesn’t care about other mounted drives, you will need to install them manually (see below).

Boot drive

TOS is a bit inconsistent about which drive is the boot drive. When booting, GemDrive will select the first SD card as boot drive, starting AUTO programs, accessories and loading DESKTOP.INF/NEWDESK.INF from there. However, the Save Desktop feature will disregard that boot drive and use its own logic. It seems that it tries to save to C:, and if C: doesn’t exist it saves to A:.
Installing drive icons

Old TOS (TOS < 2.00)

Older versions of TOS have a very peculiar procedure to install drive icons. You need to install each of them manually:

  • Select any pre-existing drive icon
  • Open the Options menu and select Install Disk Drive…
  • Type the drive letter in Disk identifier
  • Optionally, you can label the icon
  • Click install, the icon will appear on the desktop
  • Don’t forget to save the desktop

New TOS and EmuTOS

This is much more user-friendly:

  • Open the Options menu and select Install Devices
  • Don’t forget to save the desktop

Notes

Weird things can happen when installing drives:

  • Newly installed icons can be placed over or under an already existing icon. If you cannot find an icon, try to move other icons around. Make sure not to drag icons over other icons because it will trigger a copy operation !
  • Drive C: needs to be typed upper case because c: is the cartridge drive. Other drive letters are case insensitive.
  • Why Install Disk Drive is disabled when you don’t select any icon is beyond me. It doesn’t make any sense and looks like a bug IMHO. New TOS fixes this weird behavior.


Removing drive icons

Old TOS

  • Select the icon to remove
  • Open the Options menu and select Install Disk Drive…
  • Click Remove

Warning: Don’t remove all drive icons on old TOS or you won’t be able to recreate any drive icon ! Saving the desktop while in this state is a bad idea.
New TOS and EmuTOS

  • Select icon(s) to remove
  • Open the Options menu and select Remove Desktop Icon

Note: New TOS can even remove multiple icons at once, just select all of them at the same time.

Troubleshooting

If you have an issue, check this place first.

First of all, ACSI2STM is not a hardware nor software vendor. It is not a finished product that is guaranteed to work. Your old ST is also not guaranteed to work. You need technical knowledge to assemble, test and debug the project.

Reporting issues

You can report issues on the GitHub project page. Feedback is welcome.

Things that you should do before reporting an issue:

  • Check this page.
  • Check if similar issues were not already solved.
  • The project is well tested and mature. If the issue is trivial (i.e. nothing works), please research what you could have done differently from the documented configuration and mention it in the GitHub issue.
  • Try to reproduce the issue in the simplest possible case.
  • Flash the debug firmware and capture its output.
  • If your hardware never worked correctly, check signals with an oscilloscope if possible.

“Nothing works” – where to start ?

ACSI2STM will display a message on the ST screen during boot. If it doesn’t appear, check this section.

Things to check first

  • The power LED must be on, bright and steady at all times. If not you have a power supply issue.
  • The activity LED must stay on when the ST is off. If it is not, you have an issue with the STM32 (bad firmware upload ? hardware issue ?)
  • The activity LED must turn off nearly immediately when powering the ST on. If it doesn’t, you may have a hardware fault on the ST or a bad STM32 chip.
  • Flash the debug firmware in case of issues. Debug messages help a lot. The debug firmware outputs data at 1Mbps.

Check that your ST actually works

If you don’t have a working hard disk (or emulator) to test your port, here is what you can do:

With nothing connected to the DB19 HD port, the following signals must be present during the boot process (after the first floppy disk access and before the desktop appears):

  • RST must be high and steady
  • CS must pulse low exactly 8 times, pulses are around 250ns long and spaced by about 50ms (more or less)
  • A1 must pulse low from time to time. A1 must be low anytime CS pulses low.
  • R/W must be high when CS pulses low
  • IRQ, DRQ and ACK must be high around CS pulses
  • See protocols and hardware for technical details that will help you do all the necessary checks.

Check these signals with a logic analyzer or (better) a digital oscilloscope.

You will need a digital oscilloscope with single capture mode and at least 20MHz bandwidth.

If CS, A1 and IRQ works, but DRQ/ACK doesn’t, try the PIO firmware variant (see firmware).

SD cards not detected / malfunctioning

Check in the debug output that the SD card are effectively detected. For GemDrive, the SD card should be specified as “mountable”. If the SD card is not marked as “mountable” or marked as “bootable”, then it will be set to ACSI mode.

The best cards are the most modern SDHC/SDXC cards. Reputable brands offer better reliability. Be careful with the many bootleg/knockoffs, some of them even include the whole packaging and look very convincing.

The SdFat library uses SD cards in SPI mode. Normally, all cards are compatible, but some full size SD cards may not support this mode.

Some old SD cards don’t work at 50MHz and will fall back at 25MHz.

If SD cards aren’t detected, check connections and make sure you don’t use a SD slot board with logic level adapters for 5V Arduinos. Connections between the SD card and the microcontroller must be direct.

If you need slower speed, change ACSI_SD_MAX_SPEED to 25 or to 1 in acsi2stm.h and recompile the firmware.

Programs not working in GemDrive mode

Unfortunately GemDrive isn’t 100% compatible due to the way it works.

Mainly, most games and low level disk tools probably won’t work. Games that were adapted to work on hard disks should work though.

See compatibility for information about software compatibility.

No debug output with debug/verbose firmware variants

First, check that you effectively have a debug variant. GemDrive mentions this on its splash screen on the ST.

Make sure you have the correct settings on your serial port:

  • 1000000 bauds (1Mbps)
  • 8 bits
  • 1 stop bit
  • no parity

If you need a slower speed, change ACSI_SERIAL_SPEED in `acsi2stm.h’ and recompile the firmware.

Random errors while copying a lot of files

TOS has a poor FAT filesystem implementation, with a lot of bugs. This gets better with each new version, especially TOS 2.06, but it still has issues.

Some workaround programs were released, patching various parts of the filesystem but this may have adverse effects with GemDrive:

  • FOLDR100.PRG (and its variants)
  • CACHE064.PRG (and its variants)
  • BigDOS

Even with this, the filesystem is laden with bugs, memory leaks, bad error code handling and other quirks.

The best way to limit possible interaction between these patching tools is to load GemDrive through GEMDRIVE.PRG and make sure it’s loaded after all these tools. That way access to GemDrive drives will be done with pristine system calls.

The safest solution is to stay away from TOS/ACSI as much as possible and use GemDrive only. If you really need to do ACSI file management, use EmuTOS.

Issues with multiple ACSI2STM units on the same computer

It should be possible to use multiple units at the same time when using ACSI strict mode. Just make sure you don’t have ACSI id conflicts (use ID_SHIFT).

“Bad DMA” chips

This article describes a phenomenon that introduces DMA issues on some ST. It mentions a possible software workaround. GemDrive implemented this workaround, so it should be immune to the issue.

For ACSI, if you use a modern driver, contact the developer. If you use an old legacy driver, there is nothing you can do. Use GemDrive instead.

Despite all these precautions, it seems that some Atari really have defective chips. This is very difficult to diagnose. If your ACSI2STM unit is working on one atari and not another, you can suspect the Atari. All ST and STE with TOS versions between 1.04 and 2.06 work exactly the same way. ACSI2STM units seem to work equally well on buffered and unbuffered DMA ports if the computer is healthy.

Warning: ACSI2STM firmwares version 3.x and lower had random issues. Many people were confused by this and thought that they had a bad DMA chip because of this. New versions fixed many subtle bugs so it might be worth trying an up to date version on older hardware that didn’t work previously.

Workaround for bad DMA

ACSI2STM provides a special firmware that doesn’t use DMA at all: this is called the PIO variant. Only GemDrive works in that mode.

You need to load GemDrive through GEMDRPIO.PRG because that mode cannot be automatically started at boot.

This mode offers less performance: 50-100KB/s instead of 500-1500KB/s for DMA.