Index: readme.txt =================================================================== --- readme.txt (revision 0edef063f9f44e2ab2453cf3de946f485c6efbc6) +++ readme.txt (revision 352384743b57b9deb7e4e936c75d5c70bd900438) @@ -113,5 +113,5 @@ Then, to cross-build the emulator, invoke - make buchla WIN=1 + make buchla.exe WIN=1 from the top-level directory of this repository. Defining the "WIN" @@ -119,4 +119,157 @@ library directory. +In addition to the emulator, we need to build the mkdisk utility, +which we'll use to create a 720-KiB floppy disk image that can be read +by the Buchla firmware. + +Building mkdisk works pretty much like building the emulator. On Linux +and OS X, invoke + + make mkdisk + +from the top-level directory of this repository. To cross-build the +Windows version, invoke + + make mkdisk.exe WIN=1 + +instead. + + +Running the emulator +-------------------- + +This is where this repository, buchla-emu, meets its companion +repository, buchla-68k. We assume that you built the following files +according to the instructions in the buchla-68k repository: + + bios.abs + midas.abs + +Please copy (or symlink) them into the top-level directory of this +repository, buchla-emu. + +bios.abs contains the Buchla 700's BIOS code. The file is loaded by +the emulator directly to emulate the BIOS PROM. + +midas.abs is the MIDAS VII software. Unlike the BIOS, which resides in +a PROM, it is loaded from a floppy disk. To create this floppy disk, +we need the mkdisk utility. + +mkdisk expects to be run from inside the directory that contains +midas.abs and produces a disk image file, buchla.disk in the same +directory. For example, on Linux: + + ~/buchla-emu$ ls -l midas.abs + lrwxrwxrwx 1 emu emu 23 Jul 30 18:07 midas.abs -> ../buchla-68k/midas.abs + ~/buchla-emu$ ./mkdisk + ~/buchla-emu$ ls -l buchla.disk + -rw-r--r-- 1 emu emu 737280 Aug 6 09:44 buchla.disk + +Now we have everything in place to run the emulator. On Linux and OS X +you can invoke it directly from the top-level directory of this +repository: + + ~/buchla-emu$ ./buchla + +If you prefer to install the emulator elsewhere, be sure to copy the +following files: + + buchla | buchla.exe emulator executable (.exe for Windows) + ttf/vera-sans-mono.ttf emulator font + bios.abs BIOS code + buchla.disk disk image + +This also applies to copying the cross-compiled Windows emulator to a +Windows machine. + +If you would like to keep the BIOS code, disk image, and font separate +from the emulator executable, check out the emulator's -b, -d, and -f +command line options. Use -h for an overview of all available options. + + +Cross-debugging the firmware +---------------------------- + +While the emulator is running, it listens on TCP port 12053 for +incoming connections from a GDB cross-debugger. This allows for +comfortable source-level debugging of the cross-compiled BIOS and +MIDAS VII code, while it runs in the emulator. + +We assume that you have a GCC cross-toolchain in /opt/cross-m68k, as +described in the buchla-68k repository. Based on that, we build a +GDB cross-debugger: + + # If you haven't yet done so, add the cross-toolchain to your + # PATH, so that the GDB build can find it. + + export PATH="/opt/cross-m68k/bin:${PATH}" + + tar zxvf gdb-7.12.tar.gz + cd gdb-7.12 + + mkdir build + cd build + + ../configure --prefix=/opt/cross-m68k --target=m68k-none-elf + + make -j2 + make install + +The Buchla firmware uses its own (Atari-like) object and executable +file format. However, the cross-toolchain and the cross-debugger +support the ELF standard. + +When you built the BIOS and MIDAS VII software, you ended up with two +files in the Buchla's executable file format, bios.abs and midas.abs. +However, the cross-build process also produces matching ELF files, +bios.elf and midas.elf, suitable for the cross-debugger. + +Depending on whether you would like to cross-debug the BIOS or MIDAS +VII, you'd specify either bios.elf or midas.elf when invoking the +cross-debugger. + +To follow along the following example, copy (or symlink) bios.elf and +midas.elf from the buchla-68k repository into the top-level directory +of this repository. + +In order to open a debug session for the BIOS, run the cross-debugger +with bios.abs and connect it to the running emulator using GDB's + + target remote :12053 + +command. 12053 is the port on which the emulator listens for incoming +GDB connections. + + host:~/buchla-emu$ m68k-none-elf-gdb ./bios.elf + GNU gdb (GDB) 7.12 + Copyright (C) 2016 Free Software Foundation, Inc. + [...] + (gdb) target remote :12053 + Remote debugging using :12053 + trwzsup () at rom/bios.s:832 + 832 move.l 0(a0,d0),d0 | Get routine address + (gdb) + +From here on, everything is pretty much standard GDB, for example: + + (gdb) break pscan + Breakpoint 1 at 0x105a64: file rom/romp.c, line 3403. + (gdb) cont + [...] + (gdb) bt + #0 pscan () at rom/romp.c:3403 + #1 0x00105e96 in main () at rom/romp.c:3587 + #2 0x00105fd6 in Croot (cp=0x0) at prolog/croot.c:141 + #3 0x00105f52 in start1 () at prolog/fsmain.s:59 + (gdb) + +In order to debug MIDAS VII, run the cross-debugger with midas.elf, +instead: + + host:~/buchla-emu$ m68k-none-elf-gdb ./midas.elf + GNU gdb (GDB) 7.12 + Copyright (C) 2016 Free Software Foundation, Inc. + [...] + Emulated hardware @@ -132,5 +285,5 @@ * Motorola MC6840: Timers. - * Motorola MC6850: Serial console and MIDI ports. + * Rockwell R65C52: Serial console and MIDI ports. * Epson SED1335: LCD controller. @@ -180,12 +333,7 @@ 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). + a DSP. + + XXX - Details to be filled in. We don't know how many of the envelopes not related to FM @@ -204,4 +352,4 @@ 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. +If your Buchla is non-functional, this is also fine. We might be able +to gain some insights from reading out the FPU microcode PROMs.