source: buchla-emu/readme.txt@ 49efb91

Last change on this file since 49efb91 was 49efb91, checked in by Thomas Lopatic <thomas@…>, 3 years ago

Minor language changes.

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