Buchla 700 Hardware Emulator
----------------------------

This repository, buchla-emu.git, contains a software emulation of the
Buchla 700's hardware.

It is minimalistic; it emulates just enough of the hardware to be able
to run the firmware from the companion repository, buchla-68k.git.

We don't have access to original hardware, so this is our best guess
based on the firmware source code published by Lynx Crowe - the
firmware's developer - via Aaron Lanterman:

  http://lanterman.ece.gatech.edu/buchla700/

See the buchla-68k.git repository for the firmware source code.


Building the emulator
---------------------

The emulator uses SDL2, an abstraction layer for low-level machine
access on Linux, OS X, and Windows. It can be obtained from the
project's website:

  https://libsdl.org/

The SDL2 website also hosts the SDL2_ttf project, which adds support
for TrueType fonts to SDL2. SDL2_ttf, in turn, requires the FreeType
library, which is available from the FreeType website:

  https://www.freetype.org/

Currently, we build the emulator natively on Linux and OS X. The
Windows version is cross-compiled on Linux using a x86_64-w64-mingw32
cross-toolchain.

For Linux and OS X, our Makefile expects all of the above libraries to
reside in /opt/sdl2. This is how we typically install them:

  # Build and install FreeType first

  tar zxvf freetype-2.7.1.tar.gz
  cd freetype-2.7.1
  mkdir build
  cd build

  # Skip the optional features (compressed fonts, etc.) that would
  # create more dependencies

  ../configure --prefix=/opt/sdl2 \
    --without-zlib --without-bzip2 --without-png --without-harfbuzz

  make
  make install

  # Then build and install SDL2

  tar zxvf SDL2-2.0.5.tar.gz
  cd SDL2-2.0.5
  mkdir build
  cd build

  ../configure --prefix=/opt/sdl2

  make
  make install

  # Build and install SDL2_ttf last

  tar zxvf SDL2_ttf-2.0.14.tar.gz
  cd SDL2_ttf-2.0.14
  mkdir build
  cd build

  ../configure --prefix=/opt/sdl2 \
    --with-sdl-prefix=/opt/sdl2 --with-freetype-prefix=/opt/sdl2

  make
  make install

Now that we have everything in place, invoke

  make buchla

from the top-level directory of this repository to build the emulator.

The cross-build for Windows is done similarly, with the following
differences when configuring the libraries:

  * We use "--prefix=/opt/sdl2-win" instead of "--prefix=/opt/sdl2",
    so that the Windows versions of the libraries go to a different
    directory. That's where our Makefile expects to find them when
    cross-building.

  * We additionally specify "--host=x86_64-w64-mingw32" to enable
    cross-compilation.

Then, to cross-build the emulator, invoke

  make buchla WIN=1

from the top-level directory of this repository. Defining the "WIN"
variable selects the cross-toolchain and "/opt/sdl2-win" as the
library directory.


Emulated hardware
-----------------

Here's what we emulate:

  * Motorola 68000 CPU. This is actually the Musashi CPU emulator by
    Karl Stenerud:

      https://github.com/kstenerud/Musashi

  * Motorola MC6840: Timers.

  * Motorola MC6850: Serial console and MIDI ports.

  * Epson SED1335: LCD controller.

  * Intel 82716: Video chip.

  * National Semiconductor LMC835: Equalizer.

  * General Instrument AY-3-8910: A sound chip, which is not used for
    sound generation, but only for its I/O ports. It connects the CPU
    to the above equalizer chip.

  * Western Digital WD1772: Floppy disk controller.

  * A few LEDs.

  * Item X: A program running on a microcontroller. It converts the
    analog signals from the Buchla's controller pads to digital
    values.

    Neither the program, nor the microcontroller are known, but the
    protocol (known from the firmware source code) is pretty simple
    and self-explanatory.

  * Item Y: The actual sound generator, referred to by the firmware
    source code as "the FPU." This could actually be two chips:

      1. One chip, maybe a DSP, for generating the 15 different
         parameter envelopes for each of the 12 voices:

           - 4x FM modulator (oscillator) frequency.

           - 6x FM modulator (oscillator) envelope.

           - 1x Output signal amplitude envelope.

           - 1x Output signal filter envelope.

           - 1x Output signal filter resonance envelope.

           - 1x Output signal stereo location.

           - 1x "Dynamics." (TBD - currently not emulated.)

         Over time, the chip interpolates between the points of the
         envelopes drawn in the MIDAS VII instrument editor.

      2. A second chip for the actual sound generation. This is likely
         a DSP, possibly a Hitachi HD61810, which supports a 16-bit
         floating-point format that's also found in the firmware
         source code (12-bit mantissa, 4-bit exponent).

         This chip takes in the current levels of a voice's envelopes
         and, based on them, performs the FM synthesis for this voice
         by modulating the user-drawn carrier waves A and B according
         to the selected FM configuration (algorithm).

         We don't know how many of the envelopes not related to FM
         (e.g., the filter) are actually used digitally. At least some
         of the envelopes probably control analog circuits.

         Obviously, the emulator does everything digitally.

    This "two chip" hypothesis would be in line with the "four
    computers" marketing claim from the Buchla 700 marketing copy. The
    four "computers" would be the Motorola 68000, the microcontroller
    that does the A/D conversion of the pad inputs, plus the two CPUs
    that constitute "the FPU."

If you have access to an actual Buchla 700, please do contact us. It
would be great to be able to compare the emulation to real hardware.

If it's non-functional, this is also fine. We might be able to gain
some insights from reading the FPU microcode PROMs.
