MacSD User's Manual
Firmware v2.0.2
1. Overview

MacSD is a multi-function SCSI2 target device which uses 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.

Performance considerations

The speed of random and sequential reads and writes can be improved by using a V60 or better SD card. Faster SCSI hosts will benefit more from a fast card than slower machines.

MacSD's CD audio and synthesizer features require consistently low SD card access times. Some cards may stall up to several hundred milliseconds when accessing specific blocks on the card. This results in breaks in the audio output. A sure sign of slow blocks on a card is CD audio breaking up at the same point in a track. The synthesizer may do the same when specific instruments are played.

Resolving a stalling SD card:

Replacing the card with one of higher quality is recommended. If the same card is to be used, rename the affected synthesizer patch file or CD image on the SD card so that it will not be used, but continues to occupy the same sectors on the card. Then, write a new copy of the file to the SD card.

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 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 host machine 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 MacSD only writes to image files in place, it cannot contribute to card fragmentation; an unfragmented card installed in the MacSD will remain unfragmented. 3. Configuration

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 nine section types: Options for each section type are described in detail in the following sections. An example configuration file is described at the end of this manual.

Options requiring a Boolean (true/false) parameter will also accept these aliases:

Boolean aliases
true false
t f
1 0
enabled disabled
yes no
y n
4. USB Terminal Interface

MacSD implements a standard serial port over its USB interface. This appears as a COM port in Windows or /dev/ttyACMx in most Linux distributions. Text commands may be sent to MacSD to monitor or modify its parameters. Connecting a WiFi-equipped single board computer such as a Raspberry Pi allows for wireless administration. A connected host may, for example:
[terminal] configuration section attributes:

Serial port settings

The following settings are recommended for the serial terminal interface. Other values may not work correctly:

USB Serial Port Settings
Baud rate115200 bps
Data bits8
Stop bits0
Flow controlNone

Non-interactive control with a Linux host

When connected to a Linux host, such as a Raspberry Pi, commands may be sent to MacSD using the echo command. This is useful for scripting or automating commands. The device ttyACM0 is used below as an example. The serial device may vary based on your distribution and system configuration.

Example echo usage:
Set speed of fan channel X to 90%:
echo "fan speed 90 x" > /dev/ttyACM0

Set synthesizer depth effect to 80:
echo "synth depth 80" > /dev/ttyACM0

Interactive control and monitoring with PuTTY

PuTTY is a free terminal emulator for Windows, Linux and Mac which can be used with MacSD. Any other VT100-compatible terminal emulator may be used as well.

Setting up PuTTY:
  • Select the Serial connection type

  • Enter the MacSD serial device for your system

  • Set the speed to 115200 bps

  • Enter a name for the session

  • Click Save
  • Select the Terminal category in the left window

  • Set the terminal options as shown. The local echo option displays character typed in the PuTTY window. The local line editing option causes PuTTY to wait until enter is pressed before sending any typed characters to MacSD.
  • Select the Serial category in the left window

  • Set the serial options as shown.

  • Return to the Session category in the left window (shown in the first image) and click Save to preserve the updated options. These settings can now be easily loaded by selecting the saved session and clicking Load.

  • Click Open to connect to the terminal.

Sample terminal session:

General terminal commands:
Terminal commands specific to each subsystem are described in detail in the following sections.

5. General Configuration Options

[general] configuration section attributes:

General Configuration Summary
[general] Configuration Section Terminal Interface Values Default
System clock speedsystem_clock_mhz = n33, 48, 5733
CD audio rate trimpcm_tune = n9500-1050010000
Internal LED intensityint_led_intensity = nled int n0-10050
External LED intensityext_led_intensity = nled ext n0-10050
Read parityparity = ntrue, falsefalse
6. Hard Drive Device Emulation

[n:hdd] configuration section attributes:

An HDD device section must define either an image_file or partition:
7. CD-ROM Device Emulation

MacSD emulates one or more AppleCD 300i 2X CD-ROM drives. Read and seek performance exceed that of the real drive.

[n:cdrom] configuration section attributes:
8. 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.

[n:composite] configuration section attributes:
9. MIDI Interface and Router

MacSD can route MIDI data through multiple interfaces:

MIDI Interfaces
Interface Source Sink Notes
SCSI MIDI over the SCSI bus via OMS driver
USB 12Mb/s, compliant to the USB MIDI 1.0 specification
MPU-401 31250 bps, 3.3V
Synthesizer Internal to MacSD

By default, MIDI events supplied by an interface are forwarded to all other enabled destinations capable of accepting MIDI events, but are not looped back to the source interface. The MIDI router interfaces with the internal synthesizer, but is a separate component. While the synthesizer requires a 57MHz clock speed, the MIDI router operates at any frequency.

The MPU-401 is an obsolete MIDI interface manufactured by the Roland Corporation. Across the PC world, the term became a defacto standard for virtually any MIDI device externally attached to a PC. The logical signaling of MPU-401 UART mode is identical to that of the standard 5-pin DIN MIDI port. For the purposes of this document, MPU-401 should be considered synonymous with a physical MIDI DIN port.

Macintosh software components
MIDI over SCSI is a Macintosh-exclusive feature enabled by the MacSD OMS (Open Music System) Driver. This driver interfaces with OMS and is installed in the OMS Folder within the System Folder. OMS in turn, can receive MIDI from QuickTime and the Apple MIDI Driver. Therefore, an application or game compatible with at least one of these software components can send MIDI to MacSD.

While the MacSD OMS Driver is active, the SCSI LED will flash regularly as small synchronization packets are exchanged, even when no MIDI events are sent. MIDI events are buffered in order to ensure smooth playback during periods of file access. This buffering results in latency of about 500ms.

Connecting external devices and sound cards

Resistors are required when connecting external MIDI devices and sound cards to MacSD for level shifting and limiting current. Directly connecting the MacSD expansion port to external devices may damage the device and/or MacSD. See the Expansion Port section for details.

SoundBlaster 16 / AWE32

Some cards in the SoundBlaster 16 and AWE32 family are affected by a bug which corrupts the MIDI data stream, resulting in hanging notes. Setting mpu_401_source_rs option to false greatly reduces the prevalence of hanging notes.

Running status

Running status is a simple, lossless compression scheme, part of the original MIDI specification. It increases the maximum event throughput of 31.25Kb/s MIDI serial links by omitting redundant status bytes. Because the USB and OMS/SCSI interfaces are not subject to the 31.25Kb/s limitation of the MPU-401 interface, they do not implement running status. Many games using SoundBlaster cards do not take advantage of running status. This allows the mpu_401_source_rs=false setting to discard stray bytes from these cards rather than reconstructing false events that cause hanging notes. Disabling running status for sources which employ it will result in dropped events.

[midi] configuration section attributes and terminal commands:

MIDI Configuration Summary
[midi] Configuration Section Terminal Interface Values Default
SCSI source enable scsi_source = n midi scsi_source n true, false false
Synthesizer sink enable synth_sink = n midi synth_sink n true, false false
USB source enable usb_source = n midi usb_source n true, false false
USB sink enable usb_sink = n midi usb_sink n true, false false
MPU-401 source enable mpu_401_sink = n midi mpu_401_sink n true, false false
MPU-401 source running status mpu_401_source_rs = n midi mpu_401_source_rs n true, false true
MPU-401 sink enable mpu_401_sink = n midi mpu_401_sink n true, false false
MPU-401 sink running status mpu_401_sink_rs = n midi mpu_401_sink_rs n true, false true
MPU-401 sink invert polarity mpu_401_sink_invert = n midi mpu_401_sink_invert n true, false false
MPU-401 loopback mpu_401_loopback = n midi mpu_401_loopback n true, false false

Monitoring MIDI status

Modifying a MIDI parameter through the terminal interface or sending a midi info command results in a report of all MIDI parameters. Enabled options are represented by an X while disabled options show an underscore:

10. MIDI Synthesizer

MacSD features a sample-based MIDI synthesizer. Waveform data stored in a patch file on the SD card is loaded, transformed and mixed by the processor in real time according to streaming MIDI events. The audio output signal is generated on the CD audio out header. The synthesizer uses a different audio driver than the CD audio system, which precludes simultaneous CD audio and synthesizer playback. In cases where both features are engaged, CD audio takes precedence over the synthesizer.


The MacSD synthesizer is an original design, partially written in optimized assembly. Melodic samples were sourced from the Korg X50, a descendant of the Triton synthesizer. Drum samples were sourced from the Korg X50, Yamaha MU100 and Roland SC-55.

MIDI Features