MacSD User's Manual
MacSD is a SCSI2 target device which emulates multiple drive types using an SD or MMC card for storage. The circuit board is embedded within a 3D-printed ABS bracket which mounts in a standard 3.5" bay or sled. It is powered through the SCSI connector.
Ports and Controls:
- 50-pin SCSI connector - Used for data transfer and power
- CD audio out - Analog audio output to the logic board
- CD audio in - Analog audio pass-through from a CD-ROM drive
- Expansion port - For external LEDs and add-on boards
- Configuration jumpers - Used to update firmware (BL) and select firmware-dependent options (X,Y,Z)
- Terminator DIP socket - Accepts a pair of optional resistor arrays for bus termination
- Mini USB port - Full-speed capable, reserved for future functionality
- Card slot - Accepts SD and MMC cards
- Most SCSI-equipped Macintosh computers
- SCSI Manager
- SCSI Manager 4.3
- Windows 98
- Windows XP
- MS-DOS 6.22
- Adaptec 29xx-series SCSI cards
2. Card Requirements
- 1.4MB+ per second sustained transfer speeds without overclocking (PowerMac 6100)
- Up to 7 simultaneous SCSI devices
- Hard drives
- CD-ROM drives
- Composite drives using partition images
- FAT32 SD card filesystem
- No special software needed to transfer disk images
- Configuration is stored on the card as an INI file
- Firmware updates via SD card
- Floppy/partition image support using composite devices
- Multiple partition images (floppy, Mini vMac, HFS, FAT, ProDOS, etc) are dynamically assembled into a single drive
- Work with multiple floppy images simultaneously, at SCSI speeds
- Add new images without reconfiguration
- Up to 60 partition images across multiple SCSI IDs
- AppleCD 300i Plus emulation
- Multiple emulated CD-ROM drives
- 8X read throughput
- Supports "cooked" ISO disc images
- Supports BIN/MODE1, redbook/audio and mixed-mode disc images
- Supports TOC and CUE table-of-contents file formats
- 44.1KHz 12.45-bit stereo audio output, concurrent with data transfers
- Full compatibility with AppleCD Audio Player
- Software CD audio volume control
- Eject and load discs from a configured catalog without rebooting
- Boot from CD image
- Multiple termination options
Compatible card types are MMC, SDSC (less than 4GB), SDHC (4-32GB) and SDXC (64GB and up). Cards must support 3.3V operation. The card may use either an MBR partition table, or no partition table with the filesystem beginning on block zero. If partitioning is used, partition type must be 0x0B or 0x0C (WIN95 FAT32/LBA). Only the FAT32 filesystem is supported. All files and directories referenced in the configuration file must be located in the root directory of the card. The write protect switch on full size cards will not inhibit writes. A single image file may not exceed 4GB due to FAT32 limitations.
3. Composite Devices
The composite device feature dynamically combines a series of partition images into a virtual hard drive, complete with an Apple Partition Map. The device entry in the configuration file is bound to a directory on the card using the image_directory
option. Images within the specified directory are automatically detected and assembled at boot without additional configuration. HFS, ProDOS, FAT and other filesystems may be used by a Mac equipped with the appropriate extensions. Composite devices are useful for working with floppy/MiniVMac images, transferring files from a PC and more. Multiple SCSI IDs may be configured as composite devices. Partition images are collectively limited to 60. If a fragmented partition image is found, it will be excluded from the disk image and the FRAG LED will illuminate. Booting from composite devices is not currently supported.
The MacSD is configured via a macsd.ini file in the root directory of the SD card. The syntax follows INI file format. Comments may be added to the configuration file beginning with a semicolon. Any text on a line to the right of a semicolon will be ignored. The character set is limited to 7-bit ASCII. Either Windows (\r\n) or Unix (\n) style line termination may be used. The final statement in the configuration file must be terminated with a newline or it will not be parsed.
There are five section types:
- [general] - General configuration options
- [n:hdd] - Configures a hard drive device, where n is SCSI ID 0-6
- [n:cdrom] - Configures an AppleCD 300i Plus drive, where n is SCSI ID 0-6
- [n:composite] - Configures a composite device, where n is SCSI ID 0-6
- [disc] - Adds a data, audio or mixed mode disc image to the disc catalog
[general] Section Attributes:
[n:hdd] Section Attributes:
- system_clock_mhz=[33|48|57] - This option adjusts the system clock speed. Selecting a value other than the three specified results in a general configuration error condition. The default option is 33MHz. 48MHz and 57MHz are overclocked settings which increase the speed of the MacSD's processor, SCSI data rate and SD card interface. These settings also increase the CD audio resolution. When overclocked, the 'A' LED will illuminate. Overclocking drives the MacSD's processor beyond specification, which may result in instability and/or data loss. In addition, some SD cards cannot operate reliably at the faster serial data rates. Overclocking does not typically yield a significant benefit for 68030 and slower Macs. Before changing this setting, backing up disk images is recommended.
||33 MHz Default
||48 MHz Overclock
||57 MHz Overclock
||system_clock_mhz=33 / none
|Maximum transfer speed
|CD audio DAC resolution
|CD audio gain
|CD audio dynamic range
- pcm_tune=[9500-10500] - Adjusts the PCM audio playback rate from 95% to 105% where 100% corresponds to a value of 10000 (default). Values outside of this range result in a general configuration error condition. The value must not contain decimal points or commas. Some games and applications (Descent for example) use system time to determine when to loop an audio track rather than querying the drive for position information. This, combined with clock drift and long tracks can result in playback ending a few seconds early or continuing into the following track before looping. Timing playback in AppleCD Audio Player is useful for finding a compensation value.
- int_led_intensity=[0-100] - Sets the intensity of the eight internal/on-board status LEDs at the edge of the board. This setting does not affect the intensity of the power, card slot and terminator LEDs. Integers from 0 to 100 are valid. Values outside of this range result in a general configuration error condition. The default value is 50.
- ext_led_intensity=[0-100] - Sets the intensity of external LEDs connected to the expansion port. Integers from 0 to 100 are valid. Values outside of this range result in a general configuration error condition. The default value is 50.
An HDD device section must define either an image_file or partition:
- image_file=filename - Specifies the image file to use for this drive. The filename is case insensitive and may be enclosed in quotes. No directories are allowed; the file must be located in the root directory of the volume.
- partition=[1-4] - Specifies the primary MBR partition to use for this drive. As an advanced alternative to using an image file, a hard drive device may be mapped directly to a partition. Unlike image files, partitions may exceed 4GB in size. Also, since they occupy a fixed region on the SD card, partitions are not subject to fragmentation. While the main FAT32 partition must have a type of 0x0B or 0x0C, partitions mapped to HDD devices may have any type. Since the MacSD will attempt to use the lowest numbered partition with a type of 0x0B or 0x0C for image files and configuration, using another type for HDD partitions is recommended. The ERR LED will indicate a partition error under these conditions:
- Multiple HDD devices mapped to the same partition
- HDD device mapped to main FAT32 partition
- partition attribute assigned to non-HDD device
- Corrupt, overlapping or missing partition table
- Undefined partition selected
- partition attribute set for HDD device with a defined image_file
[n:cdrom] Section Attributes:
- image_file=filename - Specifies the image file to use for this CD-ROM drive. The filename is case insensitive and may be enclosed in quotes. No directories are allowed; the file must be located in the root directory of the volume. If this option is not defined, the drive will start empty and an image from the disc catalog will be loaded.
- disc_id_min=[1-100] - The lower bound of the range of disc IDs to load when this drive is ejected. This optional attribute defaults to 1 and must not be greater than disc_id_max.
- disc_id_max=[1-100] - The upper bound of the range of disc IDs to load when this drive is ejected. This optional attribute defaults to 100 and must not be less than disc_id_min.
- disc_id=[1-100] - Specifies the first disc ID that will be mounted from the disc catalog.
[n:composite] Section Attributes:
- image_directory=directoryname - Specifies a directory at the top level of the card containing one or more partition images.
- convert_images=[true|false] - Partition images encoded in MacBinary, DiscCopy or other format will not normally work with the composite image feature. When the convert_images option is enabled, HFS-formatted images with these encodings can sometimes be converted to the required raw format. This process occurs at startup and is indicated by the FRAG and SD LEDs alterating rapidly. To avoid image corruption, reset signals from the host are ignored until conversion is complete. Conversion speed is roughly 600KB/s and may vary according to card speed. Image conversion will delay the boot process, however it is not repeated on subsequent boots. Boot blocks in the image are discarded. Because this option irreversibly modifies image files, it is disabled by default.
[disc] Section Attributes:
Supported Disc Image Types:
- image_file=filename - Specifies the CD image file to be added to the disc catalog. The filename is case insensitive and may be enclosed in quotes. No directories are allowed; the file must be located in the root directory of the FAT32 volume. This attribute is required for [disc] sections.
- id=[1-100] - The ID for this image. This mandatory attribute is an integer from 1 to 100 and must be unique for each [disc] section.
- pcm_byte_order=[little|big] - This optional attribute is only applicable to audio and mixed-mode disc images (*.bin). It defines the byte order of CD audio data. Audio data is normally encoded as little endian, but some programs (cdrdao) rip audio as big endian. If unspecified, audio byte order is detected when the disc is mounted so this option is usually unnecessary.
- eject_button=[x|y|z] - This optional attribute allows the connection of a physical normally-open pushbutton switch to the X, Y or Z position of the OPTION header, controlling the eject function of a single emulated CD-ROM device. It is intended primarily for non-Macintosh platforms which expect discs to be changed within a game or application that offers no software eject method. Where Windows hosts poll the drive for disc changes and read the new disc as needed, Macintosh hosts disable the drive's eject button and therefore have no reason to expect a disc change. Because of this, using the hardware eject feature with Macintosh computers will likely result in errors.
The eject button can traverse the disc catalog in both directions. After a short button press, a beep is played through the CD audio output to signal the next disc in the catalog is loaded. If the button is held longer until a second, lower-pitch beep is played, the previous disc in the catalog is loaded. Further button presses are ignored until the host polls the drive.
- soft_eject_alert=[true|false] - When set to true, a beep is played through the CD audio output when a software eject event has occurred on the drive. The default value is false.
- ISO - The ISO image format represents the first and only track of a data CD. It is not suitable for audio or mixed-mode discs. Data is encoded as 2048-byte sectors with no headers, error correction data or other metadata. This is the optimal format for data-only discs and yields a 15% file size and performance advantage over the BIN format. These images often have a .iso file extension, but .toast is also common.
- BIN - The BIN format is a raw image of a disc which may span multiple tracks. This format preserves all 2352 bytes per sector. For audio tracks, all 2352 bytes represent PCM data. For MODE1 data tracks, 2048 bytes are used for data with the remainder used for error correction and other purposes. BIN files must be accompanied by TOC or CUE files, which describe the layout of tracks in the BIN image. When specifying a BIN image in a [disc] or [n:cdrom] section, the name of the BIN file is required (rather than the TOC/CUE file). The TOC or CUE file must have the same base name as the BIN file, but with a .toc or .cue extension. For example, when the MacSD loads the BIN image file alone_in_the_dark_2.bin, it will search for alone_in_the_dark_2.toc and alone_in_the_dark_2.cue in the root directory. If neither is found, an error condition will be set and the disc will be treated as having a single track.
If a disc image's size in bytes is not a multiple of 2048 or if the filename ends with .bin/.BIN, it will be mounted as a BIN image.
Example macsd.ini File:
; Example MacSD configuration file
; Any text on a line after a semicolon is ignored
system_clock_mhz=33 ; Set system clock speed to 33MHz
pcm_tune=10024 ; Increase CD audio sample clock by 0.24%
ext_led_intensity=90 ; Set external LEDs to 90% intensity
int_led_intensity=75 ; Set internal LEDs to 75% intensity
[3:cdrom] ; Configure an AppleCD 300i Plus CD-ROM drive at SCSI ID 3
image_file=warcraft2.bin ; Begin with Warcraft II inserted
disc_id_min=20 ; Rotate through game discs
[4:cdrom] ; Another CD-ROM drive at SCSI ID 4
disc_id_min=50 ; Rotate through audio CDs
soft_eject_alert=true ; Play a beep when a disc is ejected
; Configure an emulated hard drive at SCSI ID 5. Macs
; will attempt to boot from higher SCSI IDs first.
; Configure a composite device at SCSI ID 2. The "floppies"
; directory contains disk images which are mounted
; simultaneously as a single hard drive.
; Configure an emulated hard drive at SCSI ID 1, mapped
; directly to MBR partition 2. Partitions may be >4GB.
; Disc catalog:
[disc] ; Data-only disc
[disc] ; Mixed mode data+audio disc
[disc] ; Mixed mode data+audio disc
[disc] ; Mixed mode data+audio disc
[disc] ; Command & Conquer GDI Disc
[disc] ; Command & Conquer NOD Disc
[disc] ; Audio CD
[disc] ; Audio CD
[disc] ; Audio CD
5. LED Indicators
The MacSD board is equipped with a series of LEDs to indicate various conditions:
6. Filesystem Fragmentation
- PWR - The board is receiving power on the SCSI TRMPWR line. This LED is not under firmware control.
- SCSI - Indicates SCSI bus activity directed toward any device ID (emulated, physical or absent).
- SD - Indicates SD card activity
- FRAG - If a fragmented image file is loaded, this LED will remain on until power is lost. See the filesystem fragmentation section for more information.
- PCM - Indicates active PCM (CD audio) playback.
- ERR - This LED indicates one or more error conditions by rotating through a series of flash codes. See the error code section for more information.
- BL - Indicates the bootloader is active (BL jumper is set). When the bootloader is active, the meaning of other LED indicators may be different than described in this section.
- A - Illuminated when overclocking is enabled.
- B - This LED has no function in this firmware release, but may be used in future releases.
- Terminator LED - Located within the terminator DIP socket and illuminated while pull-up termination is active on the SCSI bus. If this LED is not on when the Mac is running, it may indicate the bus is missing termination.
- SD power LED - Located next to the SD card, this LED is tied directly to the SD card power supply and indicates the card is receiving power.
As free space on a FAT32 volume becomes scarce or after files are deleted, files added to it may be written across multiple fragments. Because the FAT32 filesystem does not provide an efficient method of random file access, fragmented image files must be indexed by the MacSD before they can be used. When this occurs, the FRAG LED will remain illuminated until power is lost and the SD LED will stay on until indexing is complete. Depending on the size of the image file, indexing can take a significant amount of time, during which the Mac may become temporarily unresponsive or even hang. Fragmentation can be resolved by backing up the contents of the SD card to a computer, reformatting the card and copying the files back to the card. To prevent fragmentation, do not make changes to macsd.ini or other files on the card during the copy process. Because the MacSD only writes to image files in place, it cannot contribute to card fragmentation; an unfragmented card installed in the MacSD will remain unfragmented.
7. Firmware Updates and Bootloader Operation
Firmware updates are available from macsd.com as a file under 400KB, named in the pattern: macsd_1.2.3.fwi.
To update the device firmware:
- Download the latest firmware image file from macsd.com to the root directory of a FAT32-formatted SDHC or SDSC card. The macsd.ini configuration file is not required to update firmware.
- Ensure only one firmware image file is present in the root directory of the card.
- With the Mac's power turned off, insert the SD card into the MacSD.
- Set the BL jumper.
- Turn the Mac on and observe the status LEDs:
Remove the BL jumper
Cycle power to the Mac to run the newly installed firmware.
The bootloader is the firmware component responsible for verifying and installing firmware updates from the SD card. It is not user-updatable and therefore cannot be corrupted by a failed firmware update. Because of this, bricking the MacSD is very unlikely. The bootloader is activated when the MacSD is powered on with the BL jumper set. If no card is present, all LEDs will illuminate in a combination of steady and flashing which serves as an LED test and bootloader version identification. Reverting to older firmware is permitted.
- The SD LED will flash rapidly until the verification and installation process is complete (about 15 seconds).
- On success, the SCSI LED will pulse slowly.
- If the update fails, the error LED will indicate one or more error codes. See Bootloader Error LED Codes.
Note for modern Mac users: FAT32 partitions formatted by MacOS are set to type 0x0B. While partition types 0x0B and 0x0C are valid for normal operation, the partition type for firmware updates must be 0x0C under bootloader v0.5.5. Bootloader v0.6.0 can use either partition ID. The bottom of the MacSD PCB is labeled with the bootloader version.
To ease firmware updates for MacOS users, firmware as of v0.10.2 will convert type all 0x0B partitions to 0x0C at boot.
If a firmware update fails (2 error flashes) from a card newly formatted by MacOS:
- Turn the Mac off
- Remove the BL jumper
- Turn the Mac on (partition type is changed within one second)
- Turn the Mac off (shut down safely if booting has begun)
- Install the BL jumper
- Turn the Mac on and allow the allow the update to complete
8. Bootloader Error LED Codes
Applicable while the BL LED is illuminated
- 2 flashes: No macsd_x.x.x.fwi firmware update file found in the root directory
- 3 flashes: More than one macsd_x.x.x.fwi firmware update file found in the root directory
- 4 flashes: Unknown SD card format
- 6 flashes: Firmware update file is corrupt or has been renamed
- 7 flashes: Unable to initialize SD card
9. Application Error LED Codes
All error codes once set, persist until power is removed from the system or the SCSI initiator issues a reset. Multiple error codes can be set at once, in which case the ERR LED will rotate through each.
- 2 flashes: No memory card detected
- 3 flashes: No macsd.ini file found in the root directory
- 4 flashes: Error parsing TOC or CUE file
- 5 flashes: Malformatted track entry dropped from TOC or CUE file
- 6 flashes: No corresponding TOC or CUE file found for a BIN image - The link between BIN and TOC/CUE files is established on demand, not on startup; therefore this error is set for a given disc upon mounting.
- 7 flashes: Disc catalog mount failure
- 8 flashes: Excessive fragmentation - Set if mounted images span more than 127 total fragments.
- 9 flashes: SCSI request error
- 10 flashes: General configuration error - Set when a known configuration option is set to an illegal value. Unrecognized options will be ignored without causing an error.
- 11 flashes: FAT32 filesystem error / bad format
- 12 flashes: Error in macsd.ini file [disc] entry (missing/duplicate filename, missing/duplicate/out-of-range ID, invalid PCM byte order)
- 13 flashes: Partition error
- 14 flashes: Missing or damaged image file
- 15 flashes: Composite device error
10. Termination Settings
Three termination configurations may be selected by installing or removing the two resistor arrays from the DIP socket:
- Forced perfect termination (FPT)
- Pull-up termination
- Pull-down termination
Forced Perfect Termination (no resistors installed)
This mode is always active and absorbs signal reflections by clamping data line voltage to a range of approximately -0.5V to 3.7V. It does not affect the bus impedance or the load presented to devices. Begin with this option if you are unsure of which is appropriate.
Pull-up Termination (resistors to VCC)
This is selected by installing both resistor arrays with pin 1 inserted into the VCC column of the terminator DIP socket, leaving the GND column of the socket empty. Each data line is pulled up to 3.3V through its own resistor in the array. This option should not be used on an already functioning SCSI chain (where another device or the logic board is providing pull-up termination, indicated by an LED inside of the terminator DIP socket). Otherwise, there is a risk of excessive current flow through data lines which may result in damage to devices on the bus. Centris/Quadra/PowerMac-era machines often provide pull-up termination from the logic board, eliminating the need for this option. Pull-up termination on monochrome Macs is provided only by attached hard drives, so this option should be used if the MacSD is the only SCSI device present. The highest value (weakest) resistor array that yields good results should be used.
Pull-down Termination (resistors to GND)
This is selected by installing both resistor arrays with pin 1 inserted into the GND column of the terminator DIP socket, leaving the VCC column of the socket empty. With pull-down termination, each data line is biased toward ground through its own resistor in the array. This reduces the voltage level of both the 0 and 1 logic states for each data line. The output drivers on the MacSD may not be able to reliably drive a bus with very strong pull-up termination (<150 Ohms) as found in some Quantum hard drives. In this case, pull-down bias may resolve the issue without compromising the reflection-damping characteristics of the bus. The highest value (weakest) resistor array that yields good results should be used. As always, pull-up termination must be present somewhere on the bus.
Resistor Array Notes:
11. Expansion Port
- Arrays are directional. Pin 1 is common, which is marked with a dot and must be aligned with either VCC or GND depending on termination mode.
- Pin 1 may be identified using a multimeter: Resistance between pins 1 and 2 equals the nominal resistance of the array. Resistance between pins 9 and 10 is double.
- Arrays must be installed as a pair for pull-up and pull-down termination.
- Two 330 Ohm arrays are included, but values as low as 220 Ohm may be used.
- MacSD resistor arrays have the same pin configuration as those used in Quantum hard drives (pin 1 is common).
The expansion port/header allows connection of external devices. Currently, the header may be used to connect external LEDs which mirror the eight indicator LEDs on the edge of the board. Each of these has an anode (+) output on the header. The cathode (-) of each LED must be connected to pin 16 on the header (not ground). Current-limiting resistors are not needed. Any color LED may be used. Common cathode bicolor or RGB LEDs are useful for indicating multiple conditions where there is only room for a single LED. The intensity of external LEDs may be collectively adjusted using the ext_led_intensity
Warning: Use caution and reliable connections when attaching external LEDs. Shorting an LED line may result in permanent damage to the processor. LEDs connected with incorrect polarity can illuminate erratically and cause similar behavior in other LEDs.