Merge pull request #47 from thp/update-readme

Update README.md with info from sbemu-x

README.md

@@ -1,24 +1,157 @@
 # SBEMU
-Sound blaster emulation with OPL3 for AC97.
-
-Supported Sound cards:
- * Intel ICH / nForce
- * Intel High Definition Audio
- * VIA VT82C686, VT8233
- * SB Live/Audigy
-
-The VT82C868 & ICH4 are tested working on real machine.\
-ICH & HDA tested working in virtualbox, not verified on real machine yet.\
-HDA tested working by community.
-
-Emulated modes/cards:\
-8 bit & 16 bit DMA (mono, stereo, high-speed)\
-Sound blaster 1.0, 2.0, Pro, 16.
-
-Requirements:
- * HDPMI32i (HDPMI with IOPL0) (https://github.com/crazii/HX)
- * QEMM (optional, used for real mode games) or JEMM (https://github.com/Baron-von-Riedesel/Jemm)
-
-SBEMU uses some source codes from:
- * MPXPlay: https://mpxplay.sourceforge.net/, for sound card drivers
- * DOSBox: https://www.dosbox.com/, for OPL3 FM emulation
+
+Emulate Sound Blaster and OPL3 in pure DOS using modern
+PCI-based (onboard and add-in card) sound cards.
+
+## Supported sound cards
+
+Source code from [MPXPlay](https://mpxplay.sourceforge.net/)
+is used to support the following sound cards/chips.
+
+Enabled and working:
+
+ * `sc_ich`: Intel ICH / nForce / SIS 7012
+ * `sc_inthd`: Intel High Definition Audio
+ * `sc_via82`: VIA VT82C686, VT8233
+ * `sc_sbliv`: SB Live! / Audigy
+ * `sc_sbl24`: SB Audigy LS (CA0106)
+
+Support compiled-in, but untested:
+
+ * `sc_es1371`: Ensoniq ES1371/1373
+ * `sc_cmi`: C-Media CMI8338/8738
+
+Source code exists, but "doesn't work yet":
+
+ * `sc_sbxfi`: Creative X-Fi EMU20KX
+
+Source code exists, but not sure if viable:
+
+ * `sc_wss`: Windows Sound System compatible cards
+ * `sc_cmi`: CMI 8338/8738 (PCI) cards
+ * `sc_ess`: ESS card handling
+ * `sc_gus`: Gravis UltraSound
+ * `sc_midas`: MIDAS library handling
+
+## Emulated modes
+
+ * 8-bit and 16-bit DMA (mono, stereo, high-speed)
+ * Sound Blaster 1.0, 2.0, Pro, 16
+ * OPL3 FM via [DOSBox' OPL3 FM implementation](https://www.dosbox.com/)
+
+## Requirements
+
+ * [HDPMI32i](https://github.com/crazii/HX) (HDPMI with IOPL0)
+ * Optional, for real-mode game support (I/O trapping):
+   * [JEMM](https://github.com/Baron-von-Riedesel/Jemm) with QPIEMU.DLL loaded
+   * or [QEMM](https://en.wikipedia.org/wiki/QEMM), commercial software
+
+For memory management, use either:
+
+ * `JEMMEX` only: Provides both HIMEM + EMM
+ * `HIMEMX` and `JEMM386`: Separate HIMEM + EMM
+
+In both cases, use `JLOAD` (from the Jemm distribution)
+to load `QPIEMU.DLL` before starting `SBEMU`,
+so that real-mode support is enabled. If you don't load
+JEMM+QPIEMU (or QEMM), only protected mode applications
+will be supported.
+
+## Building from source
+
+macOS, Linux and Windows is supported. For Windows, consider using
+WSL2 + Linux binaries. DOS isn't supported officially, because why
+would you use a single-tasking operating system (either emulated or
+on old hardware) to build this project? :)
+
+### Installing a cross-compiler (DJGPP)
+
+Scripts to build a recent GCC toolchain for DJGPP are available here:
+
+* https://github.com/andrewwutw/build-djgpp
+
+There's also prebuilt releases for the toolchain if you don't want
+to build DJGPP yourself. The current version (October 2023) is using
+GCC 12.2.0, but in the future newer GCC versions might become available:
+
+* https://github.com/andrewwutw/build-djgpp/releases
+
+### Installing make
+
+This assumes a Debian/Ubuntu installation. If you are using any other
+distro, I'm assuming you know your way around and can translate those
+instructions to your specific distribution.
+
+To get `make` and other tools, it's easiest to install host build tools:
+
+   sudo apt install -y build-essential
+
+On MacOS, install the Xcode command-line tools, which should give you
+`make` and other host utilities.
+
+If you are planning on building DJGPP from source, some additional build
+tools are needed. Refer to the `build-djgpp` README file for details.
+
+### Building the project
+
+The `bin` folder of your DJGPP toolchain needs to be in your `$PATH`,
+so that the following command works and outputs your DJGPP GCC version:
+
+    i586-pc-msdosdjgpp-gcc --version
+
+If this works, building the project is as simple as:
+
+    make
+
+Because you are on a modern machine with multi-core CPUs, do a parallel
+build, which is faster, for example, for a quad-core CPU, use 8 parallel
+processes to speed up building:
+
+    make -j8
+
+After the build is done, you'll find the build result in a folder called
+`output`, i.e. `output/sbemu.exe`.
+
+## Feature usage
+
+### CD Audio
+
+CD audio support in DOS requires two parts:
+
+1. Audio control (play/pause/seek/...) via `MSCDEX` (or `SHSUCDX`)
+2. Volume control via the mixer
+
+For part one, you need to have a CD-ROM drive with analog audio out
+and an MSCDEX-compatible CD-ROM driver set up.
+
+Part two (volume control) is taken care of by SBEMU on startup.
+
+To adjust the volume of CD-Audio (by default it's 100% volume),
+you can use any Sound Blaster-compatible program, such as "SBMIX",
+as SBEMU does emulate and forward CD-Audio mixer settings.
+
+Don't forget that to actually hear anything, you need to connect
+an analog audio cable from your CD-ROM drive to the 4-pin CD-IN
+header on your soundcard (or motherboard for onboard sound).
+
+
+### Debug output on serial
+
+You can configure SBEMU to output its debug messages to the serial
+port instead of the console. This also works in the background when
+games are full-screen, and so is really useful for debugging.
+
+To build SBEMU with debug output, use:
+
+    make DEBUG=1
+
+Then, launch SBEMU with this command for debug output (9600, 8N1)
+on COM1 (use `/DBG2` for COM2):
+
+    sbemu /DBG1
+
+To disable serial port debug output at runtime, use:
+
+    sbemu /DBG0
+
+Serial debug output is disabled by default.