NF_SCSI - SCSI Driver for Hatari and ARAnyM
-------------------------------------------

The SCSI Driver standard is an open software interface for the Atari and was
initiated by Steffen Engel.
This is the TOS part of the SCSI Driver for Hatari and ARAnyM.

--

The SCSI Driver for Hatari and ARAnyM implements a SCSI Driver on top of
the Linux SG 3 driver interface. With this driver, Atari software running
in Hatari or ARAnyM can access devices (SCSI, IDE, SATA, USB) managed by the
Linux SG driver. (Note that NVMe is not supported by the SG driver.)
The Linux user needs the proper permissions to access the SG device files
/dev/sg*. Depending on the Linux distribution, you may have to a member of
the groups 'disk' and 'cdrom', for instance.

The SCSI Driver for Hatari and ARAnyM implements the SCSI Driver interface
version 1.01. It consists of two software components:

1. Native SCSI Driver host implementation, which for Linux is provided by
   Hatari and ARAnyM. It maps SCSI Driver calls to Linux driver calls.
   In order to run the SCSI Driver stub for TOS on other platforms than
   Linux, this is the code that has to be ported.
2. SCSI Driver stub for TOS, NF_SCSI.PRG. This component uses the NatFeats
   interface of Hatari or ARAnyM to call the host driver. The stub is
   independent of the host platform.

In order to install the SCSI Driver either launch NF_SCSI.PRG, e.g. from the
AUTO folder of an emulated GEMDOS drive, or place the NF_SCSI driver as
HDDRIVER module HDDRMOD0.SYS in the root directory of the boot drive image.
NF_SCSI establishes two SCSI Driver buses with bus IDs 30 and 31. Optionally,
a different bus start ID can be passed as an argument when launching NF_SCSI.
The first bus is called "Linux SCSI (Bus A)" and maps the Linux devices
/dev/sg0 up to /dev/sg7. The second bus "Linux SCSI (Bus B)" maps /dev/sg8
up to /dev/sg15.
Mapping more than 8 devices to the same bus would have caused (compatibility)
issues with mapping the device IDs to XHDI major device numbers. This is why
the approach with two buses has been taken.

The SCSI Driver provides low level device access for software that is aware
of SCSI Drivers, like HDDRIVER, HDDRUTIL, DISKUS, ExtenDOS, GEMAR, the
Atari drivers for the DaynaPort or the SCSI2Pi client tools. In order to get
direct access to mass storage devices on filesystem level, an Atari hard
disk driver with SCSI Driver support has to be run, e.g. HDDRIVER.

HDDRIVER automatically provides XHDI functionality for all mass storage
devices managed by SCSI Drivers that were launched before HDDRIVER. XHDI
major device IDs are mapped to SCSI Driver bus and device IDs like this:

XHDI major device ID = 8 * SCSI Driver bus ID + SCSI Driver device ID

--

The NatFeats-based interface between the TOS stub and the host driver
implementation consists of these calls (NatFeats sub-ids):

1. SCSI_INTERFACE_VERSION

Returns the driver interface version number. (Note that this is not the same
as the SCSI Driver version.) Only when the host implementation and the TOS
stub interface version match, the stub can be installed. The format of the
version string is MAJOR.MINOR, coded as a 16 bit value. 0x0102, for instance,
means version 1.02.

2. SCSI_INTERFACE_FEATURES

Returns the host's bus features, which depend on the host system. For reasons
of backwards compatibility, this call also returns a bus name, but this name
is ignored by the TOS stub since NF_SCSI version 1.20.

3. SCSI_INQUIRE_BUS, SCSI_OPEN, SCSI_CLOSE, SCSI_ERROR, SCSI_CHECK_DEV

The host implementations of the corresponding SCSI Driver calls.

4. SCSI_INOUT

The host implementation of the SCSI Driver's In() and Out() calls. Except for
the data flow direction flag both calls are identical, so that they can be
mapped to the same interface call.

All SCSI Driver calls not listed above are implemented by the TOS stub.
Please refer to the source code (Hatari or ARAnyM, as well as the TOS stub)
for details.


  Uwe.Seimet@seimet.de, 2026-10-22
