source: buchla-emu/readme.txt @ 56746cf

Last change on this file since 56746cf was 56746cf, checked in by Alexander Heinrich <alex.heinrich@…>, 21 months ago

Merge branch 'master' into mida

  • Property mode set to 100644
File size: 11.1 KB
Line 
1Buchla 700 Hardware Emulator
2----------------------------
3
4This repository, buchla-emu.git, contains a software emulation of the
5Buchla 700's hardware.
6
7It is minimalistic; it emulates just enough of the hardware to be able
8to run the firmware from the companion repository, buchla-68k.git.
9
10We don't have access to original hardware, so this is our best guess
11based on the firmware source code published by Lynx Crowe - the
12firmware's developer - via Aaron Lanterman:
13
14  http://lanterman.ece.gatech.edu/buchla700/
15
16See the buchla-68k.git repository for the firmware source code.
17
18
19Building the emulator
20---------------------
21
22The emulator uses SDL2, an abstraction layer for low-level machine
23access on Linux, OS X, and Windows. It can be obtained from the
24project's website:
25
26  https://libsdl.org/
27
28The SDL2 website also hosts the SDL2_net and SDL2_ttf projects, which
29add support for networking and TrueType fonts to SDL2
30
31SDL2_ttf, in turn, requires the FreeType library, which is available
32from the FreeType website:
33
34  https://www.freetype.org/
35
36Currently, we build the emulator natively on Linux and OS X. The
37Windows version is cross-compiled on Linux using a x86_64-w64-mingw32
38cross-toolchain.
39
40For Linux and OS X, our Makefile expects all of the above libraries to
41reside in /opt/sdl2. This is how we typically install them:
42
43  # Build and install FreeType first
44
45  tar zxvf freetype-2.7.1.tar.gz
46  cd freetype-2.7.1
47  mkdir build
48  cd build
49
50  # Skip the optional features (compressed fonts, etc.) that would
51  # create more dependencies
52
53  ../configure --prefix=/opt/sdl2 \
54    --without-zlib --without-bzip2 --without-png --without-harfbuzz
55
56  make
57  make install
58
59  # Then build and install SDL2
60
61  tar zxvf SDL2-2.0.5.tar.gz
62  cd SDL2-2.0.5
63  mkdir build
64  cd build
65
66  ../configure --prefix=/opt/sdl2
67
68  make
69  make install
70
71  # Build and install SDL2_ttf, now that we have FreeType and SDL2
72
73  tar zxvf SDL2_ttf-2.0.14.tar.gz
74  cd SDL2_ttf-2.0.14
75  mkdir build
76  cd build
77
78  ../configure --prefix=/opt/sdl2 \
79    --with-sdl-prefix=/opt/sdl2 --with-freetype-prefix=/opt/sdl2
80
81  make
82  make install
83
84  # Build and install SDL2_net last
85
86  tar zxvf SDL2_net-2.0.1.tar.gz
87  cd SDL2_net-2.0.1
88  mkdir build
89  cd build
90
91  ../configure --prefix=/opt/sdl2 --with-sdl-prefix=/opt/sdl2
92
93  make
94  make install
95 
96  # Build and install rtmidi
97 
98  tar zxvf rtmidi-3.0.0.tar.gz
99  cd rtmidi-3.0.0
100  mkdir build
101  cd build
102 
103  ../configure --prefix=/opt/rtmidi
104 
105  make
106  make install
107
108Now that we have everything in place, invoke
109
110  make buchla
111
112from the top-level directory of this repository to build the emulator.
113
114The cross-build for Windows is done similarly, with the following
115differences when configuring the libraries:
116
117  * We use "--prefix=/opt/sdl2-win" instead of "--prefix=/opt/sdl2",
118    so that the Windows versions of the libraries go to a different
119    directory. That's where our Makefile expects to find them when
120    cross-building.
121
122  * We additionally specify "--host=x86_64-w64-mingw32" to enable
123    cross-compilation.
124
125Then, to cross-build the emulator, invoke
126
127  make buchla.exe WIN=1
128
129from the top-level directory of this repository. Defining the "WIN"
130variable selects the cross-toolchain and "/opt/sdl2-win" as the
131library directory.
132
133In addition to the emulator, we need to build the mkdisk utility,
134which we'll use to create a 720-KiB floppy disk image that can be read
135by the Buchla firmware.
136
137Building mkdisk works pretty much like building the emulator. On Linux
138and OS X, invoke
139
140  make mkdisk
141
142from the top-level directory of this repository. To cross-build the
143Windows version, invoke
144
145  make mkdisk.exe WIN=1
146
147instead.
148
149
150Running the emulator
151--------------------
152
153This is where this repository, buchla-emu, meets its companion
154repository, buchla-68k. We assume that you built the following files
155according to the instructions in the buchla-68k repository:
156
157  bios.abs
158  midas.abs
159
160Please copy (or symlink) them into the top-level directory of this
161repository, buchla-emu.
162
163bios.abs contains the Buchla 700's BIOS code. The file is loaded by
164the emulator directly to emulate the BIOS PROM.
165
166midas.abs is the MIDAS VII software. Unlike the BIOS, which resides in
167a PROM, it is loaded from a floppy disk. To create this floppy disk,
168we need the mkdisk utility.
169
170mkdisk expects to be run from inside the directory that contains
171midas.abs and produces a disk image file, buchla.disk in the same
172directory. For example, on Linux:
173
174  ~/buchla-emu$ ls -l midas.abs
175  lrwxrwxrwx 1 emu emu 23 Jul 30 18:07 midas.abs -> ../buchla-68k/midas.abs
176  ~/buchla-emu$ ./mkdisk
177  ~/buchla-emu$ ls -l buchla.disk
178  -rw-r--r-- 1 emu emu 737280 Aug  6 09:44 buchla.disk
179
180Now we have everything in place to run the emulator. On Linux and OS X
181you can invoke it directly from the top-level directory of this
182repository:
183
184  ~/buchla-emu$ ./buchla
185
186If you prefer to install the emulator elsewhere, be sure to copy the
187following files:
188
189  buchla | buchla.exe     emulator executable (.exe for Windows)
190  ttf/vera-sans-mono.ttf  emulator font
191  bios.abs                BIOS code
192  buchla.disk             disk image
193
194This also applies to copying the cross-compiled Windows emulator to a
195Windows machine.
196
197If you would like to keep the BIOS code, disk image, and font separate
198from the emulator executable, check out the emulator's -b, -d, and -f
199command line options. Use -h for an overview of all available options.
200
201
202Cross-debugging the firmware
203----------------------------
204
205While the emulator is running, it listens on TCP port 12053 for
206incoming connections from a GDB cross-debugger. This allows for
207comfortable source-level debugging of the cross-compiled BIOS and
208MIDAS VII code, while it runs in the emulator.
209
210We assume that you have a GCC cross-toolchain in /opt/cross-m68k, as
211described in the buchla-68k repository. Based on that, we build a
212GDB cross-debugger:
213
214  # If you haven't yet done so, add the cross-toolchain to your
215  # PATH, so that the GDB build can find it.
216
217  export PATH="/opt/cross-m68k/bin:${PATH}"
218
219  tar zxvf gdb-7.12.tar.gz
220  cd gdb-7.12
221
222  mkdir build
223  cd build
224
225  ../configure --prefix=/opt/cross-m68k --target=m68k-none-elf
226
227  make -j2
228  make install
229
230The Buchla firmware uses its own (Atari-like) object and executable
231file format. However, the cross-toolchain and the cross-debugger
232support the ELF standard.
233
234When you built the BIOS and MIDAS VII software, you ended up with two
235files in the Buchla's executable file format, bios.abs and midas.abs.
236However, the cross-build process also produces matching ELF files,
237bios.elf and midas.elf, suitable for the cross-debugger.
238
239Depending on whether you would like to cross-debug the BIOS or MIDAS
240VII, you'd specify either bios.elf or midas.elf when invoking the
241cross-debugger.
242
243To follow along the following example, copy (or symlink) bios.elf and
244midas.elf from the buchla-68k repository into the top-level directory
245of this repository.
246
247In order to open a debug session for the BIOS, run the cross-debugger
248with bios.abs and connect it to the running emulator using GDB's
249
250  target remote :12053
251
252command. 12053 is the port on which the emulator listens for incoming
253GDB connections.
254
255  host:~/buchla-emu$ m68k-none-elf-gdb ./bios.elf
256  GNU gdb (GDB) 7.12
257  Copyright (C) 2016 Free Software Foundation, Inc.
258  [...]
259  (gdb) target remote :12053
260  Remote debugging using :12053
261  trwzsup () at rom/bios.s:832
262  832           move.l  0(a0,d0),d0     | Get routine address
263  (gdb)
264
265From here on, everything is pretty much standard GDB, for example:
266
267  (gdb) break pscan
268  Breakpoint 1 at 0x105a64: file rom/romp.c, line 3403.
269  (gdb) cont
270  [...]
271  (gdb) bt
272  #0  pscan () at rom/romp.c:3403
273  #1  0x00105e96 in main () at rom/romp.c:3587
274  #2  0x00105fd6 in Croot (cp=0x0) at prolog/croot.c:141
275  #3  0x00105f52 in start1 () at prolog/fsmain.s:59
276  (gdb)
277
278In order to debug MIDAS VII, run the cross-debugger with midas.elf,
279instead:
280
281  host:~/buchla-emu$ m68k-none-elf-gdb ./midas.elf
282  GNU gdb (GDB) 7.12
283  Copyright (C) 2016 Free Software Foundation, Inc.
284  [...]
285
286
287Emulated hardware
288-----------------
289
290Here's what we currently emulate:
291
292  * Motorola 68000 CPU. This is actually the Musashi CPU emulator by
293    Karl Stenerud:
294
295      https://github.com/kstenerud/Musashi
296
297  * Intel 82716: Video chip.
298
299  * Epson SED1335: LCD controller.
300
301  * Western Digital WD1772: Floppy disk controller.
302
303  * Rockwell R65C52: Serial console and MIDI ports.
304
305  * Motorola MC6840: Timers.
306
307  * Unknown item #1: A program running on a microcontroller. It
308    converts the analog signals from the Buchla's controller pads to
309    digital values.
310
311    Neither the program, nor the microcontroller are known, but the
312    protocol (known from the firmware source code) is pretty simple
313    and self-explanatory.
314
315The next development milestone will hopefully emulate the following
316additional components:
317
318  * National Semiconductor LMC835: Equalizer.
319
320  * General Instrument AY-3-8910: A sound chip, which is not used for
321    sound generation, but only for its I/O ports. It connects the CPU
322    to the above equalizer chip.
323
324  * A few indicator LEDs.
325
326  * Unknown item #2: The actual sound generator, referred to by the
327    firmware source code as "the FPU." This is the biggest unknown so
328    far. Judging from the firmware source code it consist of two
329    parts:
330
331      1. The function generator that generates the 15 different
332         parameter envelopes for each of the 12 voices:
333
334           - 4x FM modulator (oscillator) frequency.
335
336           - 6x FM modulator (oscillator) envelope.
337
338           - 1x Output signal amplitude envelope.
339
340           - 1x Output signal filter envelope.
341
342           - 1x Output signal filter resonance envelope.
343
344           - 1x Output signal stereo location.
345
346           - 1x "Dynamics" - whatever that is.
347
348         The firmware feeds the the points of the envelopes drawn in
349         the MIDAS VII instrument editor to the function generator,
350         which then interpolates between them.
351
352      2. The digital oscillator.
353
354         XXX - Details to be filled in.
355
356         We don't know how many of the envelopes not related to FM
357         (e.g., the filter) are actually used digitally. At least some
358         of the envelopes probably control analog circuits.
359
360    This "two FPU parts" hypothesis would be in line with the "four
361    computers" marketing claim from the Buchla 700 marketing copy. The
362    four "computers" would be the Motorola 68000, the microcontroller
363    that does the A/D conversion of the pad inputs, plus the two parts
364    that constitute "the FPU."
365
366    The firmware source code archive indicates that the FPU is based
367    on micro-programmable hardware. We recently ran this by Lynx, the
368    developer of the firmware, who generously agreed to meet up with
369    us in Oakland, CA. While he did not work on the FPU and thus was
370    not familiar with its implementation details, he was able to
371    confirm that the FPU is based on AMD's Am2900 family.
372
373If you have access to an actual Buchla 700, please do contact us. It
374would be great to be able to compare the emulation to real hardware.
375
376If your Buchla is non-functional, this is also fine. We might be able
377to gain some insights from reading out the FPU microcode PROMs or from
378figuring out how the FPU chips are wired together.
Note: See TracBrowser for help on using the repository browser.