Index: readme.txt
===================================================================
--- readme.txt	(revision 0efe29788b258adaac4b1db0e6e6d6fcdf5b9c9a)
+++ readme.txt	(revision 0efe29788b258adaac4b1db0e6e6d6fcdf5b9c9a)
@@ -0,0 +1,134 @@
+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/
+
+Currently, the emulator supports Linux and OS X. A port to Windows
+should be pretty easy, given that it doesn't use any platform-specific
+features, just C99 and SDL2.
+
+Our Makefile expects SDL2 to reside in /opt/sdl2. This is how we
+typically install it:
+
+  tar zxvf SDL2-2.0.5.tar.gz
+  cd SDL2-2.0.5
+
+  mkdir build
+  cd build
+
+  ../configure --prefix=/opt/sdl2
+  make
+  make install
+
+Now that we have SDL2 in place, invoke
+
+  make buchla
+
+from the top-level directory of this repository to build the emulator.
+
+
+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.