Changeset 3523847 in buchla-emu for readme.txt

08/06/2017 08:51:38 AM (3 years ago)
Thomas Lopatic <thomas@…>

Document emulator invocation and cross-debugging.

1 edited


  • readme.txt

    r0edef06 r3523847  
    113113Then, to cross-build the emulator, invoke
    115   make buchla WIN=1
     115  make buchla.exe WIN=1
    117117from the top-level directory of this repository. Defining the "WIN"
    119119library directory.
     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.
     125Building mkdisk works pretty much like building the emulator. On Linux
     126and OS X, invoke
     128  make mkdisk
     130from the top-level directory of this repository. To cross-build the
     131Windows version, invoke
     133  make mkdisk.exe WIN=1
     138Running the emulator
     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:
     145  bios.abs
     146  midas.abs
     148Please copy (or symlink) them into the top-level directory of this
     149repository, buchla-emu.
     151bios.abs contains the Buchla 700's BIOS code. The file is loaded by
     152the emulator directly to emulate the BIOS PROM.
     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.
     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:
     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
     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
     172  ~/buchla-emu$ ./buchla
     174If you prefer to install the emulator elsewhere, be sure to copy the
     175following files:
     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
     182This also applies to copying the cross-compiled Windows emulator to a
     183Windows machine.
     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.
     190Cross-debugging the firmware
     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.
     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:
     202  # If you haven't yet done so, add the cross-toolchain to your
     203  # PATH, so that the GDB build can find it.
     205  export PATH="/opt/cross-m68k/bin:${PATH}"
     207  tar zxvf gdb-7.12.tar.gz
     208  cd gdb-7.12
     210  mkdir build
     211  cd build
     213  ../configure --prefix=/opt/cross-m68k --target=m68k-none-elf
     215  make -j2
     216  make install
     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.
     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.
     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
     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.
     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
     238  target remote :12053
     240command. 12053 is the port on which the emulator listens for incoming
     241GDB connections.
     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)
     253From here on, everything is pretty much standard GDB, for example:
     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)
     266In order to debug MIDAS VII, run the cross-debugger with midas.elf,
     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  [...]
    122275Emulated hardware
    132285  * Motorola MC6840: Timers.
    134   * Motorola MC6850: Serial console and MIDI ports.
     287  * Rockwell R65C52: Serial console and MIDI ports.
    136289  * Epson SED1335: LCD controller.
    181334      2. A second chip for the actual sound generation. This is likely
    182          a DSP, possibly a Hitachi HD61810, which supports a 16-bit
    183          floating-point format that's also found in the firmware
    184          source code (12-bit mantissa, 4-bit exponent).
    186          This chip takes in the current levels of a voice's envelopes
    187          and, based on them, performs the FM synthesis for this voice
    188          by modulating the user-drawn carrier waves A and B according
    189          to the selected FM configuration (algorithm).
     335         a DSP.
     337         XXX - Details to be filled in.
    191339         We don't know how many of the envelopes not related to FM
    204352would be great to be able to compare the emulation to real hardware.
    206 If it's non-functional, this is also fine. We might be able to gain
    207 some insights from reading the FPU microcode PROMs.
     354If your Buchla is non-functional, this is also fine. We might be able
     355to gain some insights from reading out the FPU microcode PROMs.
Note: See TracChangeset for help on using the changeset viewer.