search

ZuluSCSI / ZuluSCSI-firmware

Firmware for the ZuluSCSI advanced SCSI emulator
https://zuluscsi.com
Other
186 stars 20 forks source link

readme

ZuluSCSI™ Firmware

Hard Drive & ISO image files

ZuluSCSI uses raw hard drive image files, which are stored on a FAT32 or exFAT-formatted SD card. These are often referred to as "hda" files.

Examples of valid filenames:

In addition to the simplified filenames style above, the ZuluSCSI firmware also looks for images using the BlueSCSI-style "HDxy_512.hda" filename formatting.

The media type can be set in zuluscsi.ini, or directly by the file name prefix. Supported prefixes are HD (hard drive), CD (cd-rom), FD (floppy), MO (magneto-optical), RE (generic removeable media), TP (sequential tape drive).

CD-ROM images in BIN/CUE format

The .iso format for CD images only supports data track. For audio and mixed mode CDs, two files are needed: .bin with data and .cue with the list of tracks.

To use a BIN/CUE image with ZuluSCSI, name both files with the same part before the extension. For example CD3.bin and CD3.cue. The cue file contains the original file name, but it doesn't matter for ZuluSCSI.

If the image consists of one .cue file and multiple .bin files, they need to be placed in a separate subfolder. For example, create CD3 folder, then MyGame subfolder and put the .cue and .bin files there. The .bin file names must then match the names specified in the .cue file.

Supported track types are AUDIO, MODE1/2048 and MODE1/2352.

Creating new image files

Empty image files can be created using operating system tools:

If you need to use image files larger than 4GB, you must use an exFAT-formatted SD card, as the FAT32 filesystem does not support files larger than 4,294,967,295 bytes (4GB-1 byte).

ZuluSCSI firmware can also create image files itself. To do this, create a text file with filename such as Create 1024M HD40.txt. The special filename must start with "Create" and be followed by file size and the name of resulting image file. The file will be created next time the SD card is inserted. The status LED will flash rapidly while image file generation is in progress.

Log files and error indications

Log messages are stored in zululog.txt, which is cleared on every boot. Normally only basic initialization information is stored, but switching the DBG DIP switch on will cause every SCSI command to be logged, once the board is power cycled.

The indicator LED will normally report disk access. It also reports following status conditions:

In crashes the firmware will also attempt to save information into zuluerr.txt.

Configuration file

Optional configuration can be stored in zuluscsi.ini. If image file is found but configuration is missing, a default configuration is used.

Example config file is available here: zuluscsi.ini.

Performance

Performance information for the various ZuluSCSI hardware models is documented separately, here

Hotplugging

The firmware supports hot-plug removal and reinsertion of SD card. The status led will blink continuously when card is not present, then blink once when card is reinserted successfully.

It will depend on the host system whether it gets confused by hotplugging. Any IO requests issued when card is removed will be timeouted.

Programming & bootloader

For RP2040-based boards, the USB programming uses .uf2 format file that can be copied to the virtual USB drive that shows up in bootloader mode.

For ZuluSCSI V1.1 and V1.2:

DIP switches

For ZuluSCSI V1.1, the DIP switch settings are as follows:

For ZuluSCSI V1.2, the DIP switch settings at SW301 are as follows:

ZuluSCSI Mini has no DIP switches, so all optional configuration parameters must be defined in zuluscsi.ini

ZuluSCSI RP2040 Full Size DIP switch settings are:

Physical eject button for CDROM

CD-ROM drives can be configured to eject when a physical button is pressed. If multiple image files are configured with IMG0..IMG9 config settings, ejection will switch between them. Two separate buttons are supported and they can eject different drives.

[SCSI1]
Type=2 # CDROM drive
IMG0 = img0.iso
IMG1 = ...
EjectButton = 1

On ZuluSCSI V1.0 and V1.1 models, buttons are connected to J303 12-pin expansion header. Button 1 is connected between PE5 and GND, and button 2 is connected between PE6 and GND. Pin locations are also shown in this image.

On red RP2040-based ZuluSCSI models, buttons are connected to the I2C pins.

Button 1 is connected between SDA and GND and button 2 is connected between SCL and GND. On full-size models, the pins are available on expansion header J303 (image). On compact model, pins are available on 4-pin I2C header J305 (image).

SCSI initiator mode

The full-size RP2040 and RP2040 Pico models supports SCSI initiator mode for reading SCSI drives. When enabled by the DIP switch, ZuluSCSI RP2040 will scan for SCSI drives on the bus and copy the data as HDxx_imaged.hda to the SD card.

LED indications in initiator mode:

The firmware retries reads up to 5 times and attempts to skip any sectors that have problems. Any read errors are logged into zululog.txt.

Depending on hardware setup, you may need to mount diode D205 and jumper JP201 to supply TERMPWR to the SCSI bus. This is necessary if the drives do not supply their own SCSI terminator power.

ROM drive in microcontroller flash

The RP2040 model supports storing up to 1660kB image as a read-only drive in the flash chip on the PCB itself. This can be used as e.g. a boot floppy that is available even without SD card.

To initialize a ROM drive, name your image file as e.g. HD0.rom. The drive type, SCSI ID and blocksize can be set in the filename the same way as for normal images. On first boot, the LED will blink rapidly while the image is being loaded into flash memory. Once loading is complete, the file is renamed to HD0.rom_loaded and the data is accessed from flash instead.

The status and maximum size of ROM drive are reported in zululog.txt. To disable a previously programmed ROM drive, create empty file called HD0.rom. If there is a .bin file with the same ID as the programmed ROM drive, it overrides the ROM drive. There can be at most one ROM drive enabled at a time.

Project structure

To port the code to a new platform, see README in lib/ZuluSCSI_platform_template folder.

Building

This codebase uses PlatformIO. To build run the command:

pio run

Origins and License

This firmware is derived from two sources, both under GPL 3 license:

Main program structure:

Major changes from BlueSCSI and SCSI2SD include: