MacSD User's Manual
Firmware v0.11.1
1. Overview

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: Compatibility: Feature Summary:
2. Card Requirements

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.

4. Configuration

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] Section Attributes: [n:hdd] Section Attributes:

An HDD device section must define either an image_file or partition:
[n:cdrom] Section Attributes:
[n:composite] Section Attributes:
[disc] Section Attributes: Supported Disc Image Types:
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

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 as a file under 400KB, named in the pattern: macsd_1.2.3.fwi. To update the device firmware:
  1. Download the latest firmware image file from to the root directory of a FAT32-formatted SDHC or SDSC card. The macsd.ini configuration file is not required to update firmware.
  2. Ensure only one firmware image file is present in the root directory of the card.
  3. With the Mac's power turned off, insert the SD card into the MacSD.
  4. Set the BL jumper.
  5. Turn the Mac on and observe the status LEDs:
    • 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.
  6. Remove the BL jumper
  7. 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.

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:
  1. Turn the Mac off
  2. Remove the BL jumper
  3. Turn the Mac on (partition type is changed within one second)
  4. Turn the Mac off (shut down safely if booting has begun)
  5. Install the BL jumper
  6. Turn the Mac on and allow the allow the update to complete

8. Bootloader Error LED Codes

Applicable while the BL LED is illuminated

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.

10. Termination Settings

Three termination configurations may be selected by installing or removing the two resistor arrays from the DIP socket:
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

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 configuration option.

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.