source: buchla-emu/readme.txt @ e5a7d09

Last change on this file since e5a7d09 was 6027d76, checked in by Thomas Lopatic <thomas@…>, 18 months ago

Get rid of ttf subdirectory.

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