Changeset 3523847 in buchla-emu for readme.txt


Ignore:
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:
1 edited

Legend:

Unmodified
Added
Removed
  • readme.txt

    r0edef06 r3523847  
    113113Then, to cross-build the emulator, invoke
    114114
    115   make buchla WIN=1
     115  make buchla.exe WIN=1
    116116
    117117from the top-level directory of this repository. Defining the "WIN"
     
    119119library directory.
    120120
     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
    121274
    122275Emulated hardware
     
    132285  * Motorola MC6840: Timers.
    133286
    134   * Motorola MC6850: Serial console and MIDI ports.
     287  * Rockwell R65C52: Serial console and MIDI ports.
    135288
    136289  * Epson SED1335: LCD controller.
     
    180333
    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).
    185 
    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.
     336
     337         XXX - Details to be filled in.
    190338
    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.
    205353
    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.