Changeset 3523847 in buchla-emu

Timestamp:

08/06/2017 08:51:38 AM (7 years ago)

Author:

Thomas Lopatic <thomas@…>

Branches:

master

Children:

05e6dbe

Parents:

0edef06

Message:

Document emulator invocation and cross-debugging.

File:

• readme.txt (modified) (5 diffs)

readme.txt

@@ -113 +113 @@
 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 +119 @@
 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 +285 @@
   * Motorola MC6840: Timers.
 
-  * Motorola MC6850: Serial console and MIDI ports.
+  * Rockwell R65C52: Serial console and MIDI ports.
 
   * Epson SED1335: LCD controller.
@@ -180 +333 @@
 
       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 +352 @@
 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.