Changes in readme.txt [3523847:8e1b163] in buchla-emu

File:

• readme.txt (modified) (7 diffs)

readme.txt

@@ -26 +26 @@
   https://libsdl.org/
 
-The SDL2 website also hosts the SDL2_net and SDL2_ttf projects, which
-add support for networking and TrueType fonts to SDL2
-
-SDL2_ttf, in turn, requires the FreeType library, which is available
-from the FreeType website:
+The SDL2 website also hosts the SDL2_ttf project, which adds support
+for TrueType fonts to SDL2. SDL2_ttf, in turn, requires the FreeType
+library, which is available from the FreeType website:
 
   https://www.freetype.org/
@@ -69 +67 @@
   make install
 
-  # Build and install SDL2_ttf, now that we have FreeType and SDL2
+  # Build and install SDL2_ttf last
 
   tar zxvf SDL2_ttf-2.0.14.tar.gz
@@ -78 +76 @@
   ../configure --prefix=/opt/sdl2 \
     --with-sdl-prefix=/opt/sdl2 --with-freetype-prefix=/opt/sdl2
-
-  make
-  make install
-
-  # Build and install SDL2_net last
-
-  tar zxvf SDL2_net-2.0.1.tar.gz
-  cd SDL2_net-2.0.1
-  mkdir build
-  cd build
-
-  ../configure --prefix=/opt/sdl2 --with-sdl-prefix=/opt/sdl2
 
   make
@@ -113 +99 @@
 Then, to cross-build the emulator, invoke
 
-  make buchla.exe WIN=1
+  make buchla WIN=1
 
 from the top-level directory of this repository. Defining the "WIN"
 variable selects the cross-toolchain and "/opt/sdl2-win" as the
 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.
-  [...]
 
 
@@ -285 +118 @@
   * Motorola MC6840: Timers.
 
-  * Rockwell R65C52: Serial console and MIDI ports.
+  * Motorola MC6850: Serial console and MIDI ports.
 
   * Epson SED1335: LCD controller.
@@ -333 +166 @@
 
       2. A second chip for the actual sound generation. This is likely
-         a DSP.
+         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).
 
-         XXX - Details to be filled in.
+         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).
 
          We don't know how many of the envelopes not related to FM
@@ -352 +190 @@
 would be great to be able to compare the emulation to real hardware.
 
-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.
+If it's non-functional, this is also fine. We might be able to gain
+some insights from reading the FPU microcode PROMs.