bump to v0.3v0.3

2 files changed, 45 insertions, 20 deletions

diff --git a/ExtPack.xml b/ExtPack.xml
index 7423b26..c92b67a 100644
--- a/ExtPack.xml
+++ b/ExtPack.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0"?>
 <VirtualBoxExtensionPack xmlns="http://www.virtualbox.org/VirtualBoxExtensionPack" version="1.0">
     <Name>VMusic</Name>
-    <Description>Adds virtual devices for common music hardware: Adlib card (OPL2/OPL3), and MPU-401 compatible (UART mode only).</Description>
-    <Version>0.2</Version>
+    <Description>Adds virtual devices for common music hardware: Adlib card (OPL2/OPL3), MPU-401 compatible (UART mode only), and SBAWE32 (EMU8000).</Description>
+    <Version>0.3</Version>
     <MainModule>VMusicMain</MainModule>
     <MainVMModule>VMusicMainVM</MainVMModule>
 </VirtualBoxExtensionPack>
diff --git a/README.md b/README.md
index fba2024..2f70ecd 100644
--- a/README.md
+++ b/README.md
@@ -3,34 +3,46 @@
 **VMusic** is an extension pack for [VirtualBox](https://www.virtualbox.org), containing
 some virtual devices for common music hardware:
 
-* An `adlib` device emulating an OPL2/OPL3 using the [Nuked OPL3 emulator](https://github.com/nukeykt/Nuked-OPL3).
-By default this device is configured on the standard Adlib Gold ports, 0x388-0x38B, but can also be configured
-to listen simultaneously on a second set of ports in order to provide some Sound Blaster Pro/SB FM compatibility
+* A `mpu401` device emulating a MPU-401 "compatible" dumb/UART-only, on the usual ports 0x330-0x331.
+This allows the guest to output MIDI data to the host. The raw MIDI data is sent to a "Virtual RawMIDI" ALSA device
+which can be connected with either a real MIDI device or a synthesizer such as [FluidSynth](https://www.fluidsynth.org/)
+or [Munt](https://sourceforge.net/projects/munt/). MIDI input is also partially supported.
+
+* An `adlib` device emulating an OPL2/OPL3 FM synthesizer using the [Nuked OPL3 emulator](https://github.com/nukeykt/Nuked-OPL3).
+By default this device is configured on the standard AdLib ports, 0x388-0x38B, but can also be configured
+to listen simultaneously on a second set of ports in order to provide Sound Blaster FM compatibility
 (e.g. 0x220-0x223).
 The generated audio is sent directly via ALSA to the default PCM output device (usually PulseAudio), ignoring 
 VirtualBox settings.
 
-* A `mpu401` device emulating a MPU-401 "compatible" dumb/UART-only, on the usual ports 0x330-0x331.
-This allows the guest to output MIDI data to the host. The raw MIDI data is sent to a "Virtual RawMIDI" ALSA device
-which can be connected with either a real MIDI device or a synthesizer such as [FluidSynth](https://www.fluidsynth.org/)
-or [Munt](https://sourceforge.net/projects/munt/).
+* A `emu8000` device emulating the EMU8000 chip, the wavetable synthesis device that was included in the Sound Blaster AWE32,
+using code from the [PCem emulator](https://www.pcem-emulator.co.uk/).
+This allows most software to assume an SB AWE32 is installed (rather than VirtualBox's standard SB16).
+The default base port of 0x620 matches the default base port of VirtualBox's SB (0x220).
+Using this device requires the AWE32.RAW file that can be dumped using the AWE-DUMP tool, as with PCem.
+Like the AdLib device, the generated audio is sent directly via ALSA.
 
 Note that **this extension pack only works with Linux hosts**, but should work with any type of guests. 
 To make an extension pack work in Windows, it would need to be
 [signed like a kernel mode driver](https://forums.virtualbox.org/viewtopic.php?f=10&t=103801),
 which is practically impossible for an individual.
 
-These devices can be used with the standard VirtualBox SB16 emulation, so as to experience a more complete SB16
-emulation, albeit is also not necessary. You can enable each device independently, e.g. to have pure Adlib card only.
-Note that "SB MIDI" support is not implemented; for MIDI out you can only use the Mpu401 device. Most Sound Blaster
-drivers post-SB16 use the Mpu401 device.
+These devices can be combined with the standard VirtualBox SB16 emulation, to experience a more complete SB16
+emulation (or even SB AWE32), albeit it is not necessary.
+You can enable each device independently, e.g. to have pure MPU-401 only.
+Note that "SB MIDI" support is not implemented; for MIDI out you can only use the MPU-401 device. Most Sound Blaster
+drivers post-SB16 already use the MPU-401 device.
+
+### Screenshots
 
 ![Screenshot of VirtualBox playing The Secret of Monkey Island while connected to the Munt MT-32 Emulator](http://depot.javispedro.com/vbox/VirtualBoxMunt.png)
 
+![Screenshot of Windows 98 playing CANYON.MID while showing all the 3 devices available for MIDI output](http://depot.javispedro.com/vbox/win98e.png)
+
 # Installing
 
-You can try using the [VMusic.vbox-extpack](http://depot.javispedro.com/vbox/VMusic-0.2-vbox6.1.30.vbox-extpack)
-I built for VirtualBox 6.1.30,
+You can try using the [VMusic.vbox-extpack](http://depot.javispedro.com/vbox/VMusic-0.3-vbox6.1.32.vbox-extpack)
+I built for VirtualBox 6.1.32,
 which you can install into VirtualBox through the VirtualBox Preferences -> Extension Packs GUI,
 or by running `VBoxManage extpack install VMusic.vbox-extpack`.
 This should work at least for most other recent versions in the 6.1.x series.
@@ -42,12 +54,17 @@ Each device must be enabled on each VM individually, and there is no GUI to do i
 Run the following, replacing `$vm` with the name of your Virtual Machine:
 
 ```shell
+# To enable the MPU-401 device
+VBoxManage setextradata "$vm" VBoxInternal/Devices/mpu401/0/Trusted 1
 # To enable the Adlib device
 VBoxManage setextradata "$vm" VBoxInternal/Devices/adlib/0/Trusted 1
-# To enable the Adlib device on the default SB16 ports too
+# To enable the EMU8000 device
+VBoxManage setextradata "$vm" VBoxInternal/Devices/emu8000/0/Config/ROMFile "$HOME/.pcem/roms/awe32.raw"
+
+# Optional: to enable the Adlib device on the default SB16 ports too
 VBoxManage setextradata "$vm" VBoxInternal/Devices/adlib/0/Config/MirrorPort "0x220"
-# To enable the MPU-401 device
-VBoxManage setextradata "$vm" VBoxInternal/Devices/mpu401/0/Trusted 1
+# Optional: to enable an IRQ for MPU-401 MIDI input
+VBoxManage setextradata "$vm" VBoxInternal/Devices/mpu401/0/Config/IRQ 9
 ```
 
 If the devices have been correctly enabled, you should see the following messages in the
@@ -55,14 +72,15 @@ VBox.log file of a virtual machine after it has been powered on:
 
 ```{ use_pygments=false }
 00:00:00.799849 Installed Extension Packs:
-00:00:00.799866   VMusic (Version: 0.2 r0; VRDE Module: )
+00:00:00.799866   VMusic (Version: 0.3 r0; VRDE Module: )
 ...
 00:00:00.920058 adlib0: Configured on port 0x388-0x38b
 00:00:00.920066 adlib0: Mirrored on port 0x220-0x223
 00:00:00.920825 mpu401#0: Configured on port 0x330-0x331
+00:00:00.924719 emu8000#0: Configured on ports 0x620-0x623, 0xA20-0xA23, 0xE20-0xE23
 ```
 
-### Connecting Adlib
+### Connecting Adlib or EMU8000
 
 You do not need to do anything else to hear the emulated audio.
 It will be automatically sent to the default ALSA PCM out device,
@@ -107,6 +125,9 @@ Note that the port numbers may be completely different in your system.
 Also, [Qsynth](https://qsynth.sourceforge.io/) (a GUI frontend for FluidSynth) has an option to automatically connect
 all virtual MIDI ports to it, in which case you may not need to connect anything.
 
+For MIDI input, you should do the connection in the opposite direction: connect from your real MIDI hardware to the
+`Virtual RawMIDI` device.
+
 # Building
 
 You need the standard C++ building tools, make, libasound and headers (e.g. `libasound2-dev` in Ubuntu).
@@ -121,4 +142,8 @@ E.g. copy `/usr/lib/virtualbox/VBoxRT.so` into `VirtualBox.linux.amd64/VBoxRT.so
 
 After this, just type `make` followed by `make pack` and `VMusic.vbox-extpack` should be generated.
 
+# Changelog
+
+* v0.3 added support in MPU-401 for UART-mode MIDI input, and the EMU8000 device.
 
+* v0.2 is the initial release