GUSemu32 - the Gravis Ultrasound emulator for Win32

Overview:

• System Requirements
• Usage
• Emulation Issues
• Current State of Implementation
• Troubleshooting
• Frequently Asked Questions
• Legal Stuff

Without the following GUSemu wonīt work:

• Windows 95/98/ME or Windows 2000/XP
• Pentium class CPU
• DirectX 5 or better
• Soundcard supported by DirectSound

Heavily recommended:

• faster CPU
• at least 32 MB of RAM
• Soundcard with drivers for DirectSound capable of 44.1 kHz,16Bit,Stereo
• Proper settings in config.sys + autoexec.bat / config.nt + autoexec.nt (HIMEM / EMS enabled, at least 550k of conventional DOS memory)

Not that much, isnīt it ?

Win 9x/ME installation

Just unpack / copy the files into a directory of your choice. In order to activate GUSemu32, just run GUSemu32.exe.
Some programs read the configuration out of the ULTRASND= environment variable, in this case type e.g. SET ULTRASND=220,1,1,5,5 after starting up a DOS box or use a batch file for it (you may use the batch file in conjunction with a shortcut file, if you want). The first number identifies the base address of the emulated GUS, the second and third the DMA channel used for sampling and wavetable access, the last two indicate the wavetable and MIDI IRQs. Note that GUSemu32 supports only one IRQ and only one DMA, so set both DMA channels and both IRQ channels to the same values.

Win 2000 installation

Unpack / copy the files into a directory of your choice.
GUS emulation is instantly available whenever GUSemu32.exe is running.

Using the GUSemu32 GUI

This is the control panel of the GUSemu32 application. Using the minimize button, you can put it into the taskbar as a tray icon.
The titlebar always shows the currently selected base address, IRQs and DMA channels.
In the main area, the currently playing out of the maximum voices enabled are shown, followed by the number of interrupts scheduled into the DOS box per sound buffer update (not per second - in order to get the interrupts per second multiply this value with the selected Soundbuffer Update Rate).
Under Win95/98/ME, a more detailed statistic is available using the system monitor.
Whenever the tray icon gets red, GUSemu32 is active. This happens as soon as the first access to the GUS takes place. After 3 seconds of inactivity, the mixing engine is suspended and the tray icon gets blue again.

The Menus

GUSemu

• Shutdown:
  Stops GUS emulation and closes the GUSemu32 application.

Tools

• Clear GUS DRAM:
  Overwrites all sample data stored in RAM with zeroes, stops noise due to looped voices left running.
• Reset GF1 Registers:
  Sets all GF1 internal registers back to their default state, stopping voice playback and IRQ generation.
• Reset GUSemu32:
  Restarts the complete mixer / sound playback code.
• Permanent Statistics:
  Updates, if enabled, the shown status of voices and IRQ numbers several times per second instead of only at time of window redrawal. Eats pretty much CPU time.
• Wavetable RAM
  • Dump to Disk:
    Stores the current content of the GUS Wavetable DRAM into a file sized 1MB as raw data to disk (useful for sample ripping). Shows a SaveDialog for filename selection.
  • Load from File:
    Loads the content of an user-selected file as raw data into the GUS Wavetable DRAM. The file content is stored from the beginning of the GUS Wavetable DRAM up to the end of the selected file, file content above 1MB is ignored.

Config

The following settings are stored permanently within the registry and can be changed on-the-fly even when GUSemu32 is playing back sound:
• Change GUS Port, DMA, IRQ:
  Opens a Dialog for changing the Base Address, the IRQ and the DMA channel.
  Valid Ports range from 210h - 290h (usually set to 220h, 240h or 260h),
  IRQ can be any IRQ between 0 and 15 (IRQ 3,5,7,9 preferred),
  DMA can be any number between 0 and 7 (channel 1 or 3 preferred).
  IRQs and DMA channels are completely virtualized within a DOS Box, it is possible to use DMA and IRQ channels which are also used by other devices.
  However, port addresses cannot be shared and are thus not available if another driver already reserves or them.
• Set GF1 Framerate / Samples per Frame:
  Sets the frequency at which the sounddata is recalculated and mixed. Higher frequencies and thus lower mixing buffer sizes increase playback quality and latency but need more CPU time. Unless your PC is too slow or its configuration is somewhat mixed up, use 100 Hz or more.
• Set Soundbuffer update rate / Block length:
  Sets the update rate of the DirectSound buffer. Increasing the update rate decreases latency, but may cause clicks in the playback. The best setting depends on the OS (9x/ME or 2000), the program running within the DOS box and the soundcard driver.
• Set number of prebuffers:
  Determines the number of prebuffers. A value of 1 indicates double buffering, 2 triple buffering and so on. 1 or 2 prebuffers should be enough on nearly all PCs.
• Buffer update using DSound event:
  If checked, DirectSound notifies the mixer whenever a new block is needed. If it is not enabled, a separate thread is used to query the soundbuffer state. Try out which one works better on your PC (this depends on the driver and OS).

The average latency is calculated by: Replace 0.5 with 0 to get the minimum latency or by 1 to get the maximum latency using the current settings.
Help

• Well... these items are pretty self-explanatory.

An emulation of a hardware device cannot provide a completely equal environment like the hardware itself. The main problems are:

• Hardware works asynchronous parallel to the program using it while the emulator works in concurrence with the program using it (at least in single-CPU environments). Thus, the program using the emulation grabs CPU time needed by the emulation and vice versa. Thus critical-timed programs may not work correctly.
• The maximum timer frequency of a real GUS is 0.08ms compared to 1ms, the maximum timer frequency offered by Win32. Additionally, the interrupts can be delayed by some milliseconds by the OS. This affects only few programs, usual timer rates are above 1ms.
• Emulating the registers and mixing the sample data takes some time. On today's machines... who cares about these few percent, the impact by running the programs within a multitasking systems DOS-Box is much higher.
• The DMA-Controller works asynchronously while the emulator copies the entire memory block at once. This is a major problem for emulating soundblaster-type playback, but since the GUS requires the audio data copied to its local wavetable memory even in case of stream playback, it does not affect the GUS emulation.

However, there are also some benefits:

• An emulator also works if it is impossible to use the according hardware for any reason
• An emulation can provide benefits like sharing resources, built-in local data access,...
• Changing the configuration is much easier

For an emulator running under Win32 providing emulation for DOS-Boxes, the compatibility is also affected by the capabilities of the OS itself rather than the emulator itself. This applies mainly to:

• the amount and type of memory available (base memory, upper memory, XMS, EMS + VCPI, DPMI)
• access and/or virtualization of hardware not covered by GUSemu32 (e.g. InterruptController, DMA Controller, SystemTimer, VGA card (VBE2 is not available under Win2000 and XP; ModeX and VerticalBlank is not supported well))
• access violations not caught in DOS can cause the programs to be thrown out by the OS
• privileged instructions are either not available or emulated within a protected mode DOS box (note that a running EMM386 in DOS also switches into V86 mode). So programs depending on their own PMode switcher or memory manager do not run.
• STI and CLI are privileged instructions changing the Interrupt Flag (also called IF), while POPF also modifies IF without being privileged. Being in Protected/V86 mode, none of the instructions can change IF directly. However, CLI and STI can be virtualized, while POPF cannot. As a result, when a program uses POPF for changing/restoring IF, the virtualized interrupt flag in the DOS Box is not correct. Typical behaviour is IF not being activated again, causing sound playback to stop or to hang and/or program execution to hang (the programs do not react to any IRQ then, including timer/keyboard/mouse IRQs). However, most of these programs can be patched by replacing POPF with a combination of STI.

Old programs (lets better say: badly written programs) do not run if the PC is too good. If the CPU is too fast, the program can crash or execute to fast. The first case is widespread in programs written in TurboPascal and can be patched, the second case can be solved by special slowdown utilities.
And if there is more memory installed when the programmer ever thought of, memory-detection algorithms may fail due to interpreting the value as a negative or modulo number. Solve this be changing your shortcut file or the memory-manager configuration line in config.sys/config.nt

Implemented:

• 1024 kB local Wavetable RAM
• Sample-uploading/downloading via register 3x7h or DMA
• DMA transfers regarding GF1 pages, 8/16 bit and signed/unsigned conversion, DMA interrupt
• Playback of up to 32 voices limited by the MaximumVoiceRegister
• Linear Interpolation (same as used by GF1)
• VoicePlayback normal,looped, ping-pong and backwards
• VoiceVolume (interpreted exactly the same way as by GF1)
• Panning-Register (linear)
• VolumeRamping normal, looped, ping-pong and backwards
• VolumeRamping supporting fractional increment rates
• Rollover-Flag and IRQ
• Voice and Volume Ramp IRQs and IRQ status registers
• GUS timer interrupts
• Reset and Output enable register
• so-called Mixer/Configuration register 2x0h
• GF1 Sampling Control Register (nonfunctional, same as used by Interwave)

Not implemented:

• MIDI In / Out / Loopback / IRQ
• Mixer IC and its register (not present in original GUS)
• All Interwave-specific wavetable registers
• Additional CODEC found on later GUS cards
• Hidden DMA channel and IRQ hardware configuration registers 2xAh / PNP-registers
• Registers used for SB and AdLib emulation
• Joystick interface register

Differences:

• Voices are always mixed at 44.1 kHz, unaffected by the number of active / maximum voices
• GUSemu32 has a latency caused by the mixer and the sound output
• Stopped voices without active volume ramps are not mixed into the output stream (yes, the GF1 does this !)
• Port accesses are slower than on real GUS, DMA transfer is faster
• IRQs can get delayed by several ms
• IRQs and DMA channels not used by the original GUS are also available
• DMA always transfers a complete data block at once rather than using a step-by-step transfer
• Volumes, playback positions and interpolation use one bit more or one bit less in calculations
• It still requires you current sound hardware ;-)

GUSemu32.exe does not start at all

• Make sure that the following files are in the current directory:
  gusemu32.exe
  gusemu9x.dll and gusemu32.vxd (Win9x/ME)
  gusemuNT.dll and gusNTvdd.dll (Win2000)
• Does DirectSound work ? DirectX Version is 5 or above ?(Check with DXDiag or similar)
• At least 2 MB of free memory is required
• GUSemu32 does not work under NT4, it needs Windows2000
• GUSemu32 does not start by itself, you have to start it manually or include it in a startup file.

DOS programs using GUS do not produce sound or cannot find the emulated GUS

• Is GUSemu32.exe running ?
• Windows 2000 users: Is the path to gusNTvdd.dll stored correctly in the registry ? You can check this using any tool showing the DLLs loaded by a specific process (DLLSpy, DLLview, DependancyViewer, SystemInfo,...), just look if NTVDM.EXE (the DOS box emulator) has loaded gusNTvdd.dll .
• Is the ULTRASND= environment variable set correctly ? Note that although the GUSemu32 sets the ULTRASND= variable correctly in every starting VDM, it may get killed if several programs run sequentially in the same VDM
• Some programs only work with standard settings like port 220h or 240h, DMA1, IRQ 3, 5 or 7.
• Trivial but quite common: Does the program really use GUS playback code ? Some state having it but it has not been implemented for any reason...
• The program may be affected by the STI / CLI / POPF - problem (see above) and does not work unpatched.
• Some programs would not run in the same configuration using a original GUS (e.g., more free memory is required)

GUSemu32 terminates or crashes

GUSemu32 is written in a way that neither the hardware abstraction driver nor the mixer engine access invalid memory addresses or code sections, no matter what the state of the emulator currently is. Thus, crashes can only be caused by external problems not related to GUS emulation.

• Win 9x: this can happen if a DOS program overwrites critical parts of the emulator due to insufficient access protection in Win 9x. Modifying the DOS Box memory configuration usually solves this. In general, such programs are likely to cause the whole OS to crash as well.
• Win 2000: This should never happen, if you can reproduce it several times please mail me a detailed description of the problem.

This FAQ is new and therefore there are only few questions asked so far... Add more by sending them to ts@deinmeister.de.

• What do all these abbreviations mean ?
• See here:
  • GUS:
    Gravis Ultrasound, the famous 32-Voice-Wavetable card using up to 1 MB of sample RAM, capable of mixing up to 14 voices at 44.1kHz in hardware (32 voices were mixed at 19.2kHz).
  • VDM:
    Virtual DOS Machine, the DOS emulation provided by NTVDM.EXE in WindowsNT/2000. Note that a VDM is only created when starting a DOS program, the NT console uses CMD.EXE instead of COMMAND.COM by default, and since CMD.EXE is a 32bit NT executable, it does not use NTVDM or run in a VDM
  • EMS:
    Expanded Memory, provided by EMM386.EXE, most memory managers under DOS switch from RealMode to V86 mode in order to provide it
  • XMS:
    Extended Memory, provided by HIMEM.SYS, does not require DOS running in V86, allocated memory can be used in every execution mode
  • VCPI:
    Protected-Mode interface provided by memory managers like EMM386.EXE. Requires running DOS in V86 and is typically used if DPMI is not available, but V86 is active. Not used for memory allocation
  • DPMI:
    Protected-Mode interface provided by DPMI servers like Win3.x/9x, CWSDPMI (DOS) or DOSX (under WinNT/2000). Quite famous since it allows easy use of 32bit code under DOS and has a handy interface for memory allocation, interrupt usage and protected mode execution. Used by PMODE and DOS4GW if available.

• How much CPU time does GUSemu32 use ?
• On a 350-MHz K6, running plain GUSemu32 requires about 2-3 % CPU time. Playing all voices increase this only by a few %. Activating the frequent update feature eats up about 20%. However, large amounts of interrupts and/or port accesses can eat up most of the CPU time granted to a DOS Box easily.

• Can I run other applications with sound while GUSemu32 is running ?
• Yes, GUSemu32 uses a secondary buffer, thus other applications using secondary buffers can use the soundcard as well, even while GUSemu plays sound back. On my system, both GUSemu32 and the modplayer are running for hours without problems. If applications using wave out will also work at the same time depends on the driver: WDM drivers always support this, VxD drivers usually donīt.

• What are the benefits of running GUSemu under Win9x rather than on Win2000?
• Win9x grants access to all memory addresses and ports not hooked by a driver, allowing programs to use nonvirtualized features like VBE2.

• What are the benefits of running GUSemu under Win2000 rather than on Win9x ?
• A VDM provides more free base memory than the DOS Box in Win9x. NT also provides better multitasking which can be a problem for GUSemu32 under 9x. And DOS programs do not crash the OS.

• Can other Windows/OS2/... programs also benefit from GUSemu32 ?
• No. GUSemu32 virtualizes the GUS only for DOS-boxes and thus is only accessible from DOS applications

• Whatīs the exact format of the ULTRASND= environment variable ?
• The format is the following:
  
  ULTRASND=Port,DMA1,DMA2,IRQ1,IRQ2
  
  Port indicates the base port between 210 and 290 (hexadecimal).
  
  DMA1 the DMA channel used for accessing the Wavetable RAM (uploading / downloading samples to the GUS)
  DMA2 the DMA channel used by the CODEC
   Both DMA channels can be merged together using only the first DMA channel (this is what GUSemu32 uses). In this case, both DMA1 and DMA2 are set to this channel.
  
  IRQ1 the IRQ line used by wavetable (voice playback, volume ramping, DMA uploading)
  IRQ2 the IRQ line used for MIDI
   Both IRQ lines can be merged together using only one IRQ line (this is what GUSemu32 uses). In this case, both IRQ1 and IRQ2 are set to this line.

• Starting programs using the GUS takes some time
• Most programs upload the samples to the GUS using the 3x7h register. In this case every byte requires about 2 - 5 port accesses for uploading it. Every port access causes an exception to be handled and switched back to the DOS Box. Uploading 1 MB of sample data causes several millions of mode switches, each requiring hundreds of clock cycles.
  Uploading data via DMA, however, is practically only limited by the speed of the main memory.

• Will there be GUSemu for other Operating Systems ?
• GUSemu for RealMode DOS will follow soon, GUSemu for EMM386/VCPI and/or DPMI is planned and under development. Versions for Bochs, Plex86, VMWare or DOSEMU are thought of, but without any guarantee. It depends on the available interfaces and quality of these emulators as well.

• What should a good Win9x configuration look like ?
• Take a look at:
  • If himem.sys uses 40kb of memory like in Win95b, get the io.sys patch for it (check using the mem /c /p command)
  • Add LocalLoadHigh=1 to your system.ini in the [386enh] section
  • msdos.sys
    • set DblSpace=0
    • set DrvSpace=0
    • set LoadTop=1
  • config.sys
    • include DOS=NOAUTO in order to prevent drivers beeing loaded automatically without being contained in config.sys
    • add DOS=HIGH,UMB in order to allow parts of DOS to be loaded to upper memory rather than conventional memory
    • include DEVICE=HIMEM.SYS
    • followed by DEVICE=EMM386.EXE AUTO RAM , this enables use of High and UMB memory as well as EMS memory
    • add DEVICEHIGH=IFSHLP.SYS , it is needed by 9x and is no longer loaded automatically due to DOS=NOAUTO specified
    • throw out: IDE CD-ROM driver, mouse drivers, SMARTDRV.EXE, maybe also DISPLAY and MODE lines and the keyboard driver.
      Make sure the EMM386 line is NOT followed by a NOEMS parameter, otherwise some programs wonīt work.
  • autoexec.bat
    • Throw out: mouse driver, MSCDEX (=CD-ROM) driver, SMARTDRV.EXE, maybe the keyboard driver.
  Example for a good Win9x config.sys:

  DOS=NOAUTO
  SWITCHES=/F
  DOS=HIGH,UMB
  DEVICEHIGH=C:\WINDOWS\HIMEM.SYS /TESTMEM:OFF
  DEVICE=C:\WINDOWS\EMM386.EXE AUTO RAM
  DEVICEHIGH=C:\WINDOWS\IFSHLP.SYS
  LASTDRIVEHIGH=F

And the according Win9x autoexec.bat:

SET BLASTER=A220 I5 D1 H5 T6
PROMPT $P$G
PATH=C:\WINDOWS;C:\WINDOWS\COMMAND
SET TEMP=C:\WINDOWS\TEMP
SET TMP=C:\WINDOWS\TEMP

• What to do under Windows2000 ?
• There is not much to do, you may get a few extra bytes of free DOS memory by creating a special autoexec.nt and config.nt by removing DOSX and MSCDEXNT. Activating the compatible timer emulation and XMS / EMS (in general or in specific PIF files) can solve some problems.

In order to use GUSemu32, you have to acknowledge the following rules:

• Sharing copies of GUSemu32 is welcome, but you have to distribute the entire package containing of at least gusemu32.exe, gusemu9x.dll, gusemu32.vxd, gusemuNT.dll, gusNTvdd.dll and the complete manual consisting of manual.htm, gusemu.css, a.gif, back.jpg, card.gif, g32gui.gif and q.gif.
• Publishing GUSemu on websites, magazines and other media as well as distribution on CD-ROM, floppy disks, etc. requires permission by the author.
• The user of GUSemu32 is responsible for all cases of damage (hardware, software, financial, health,...) caused by GUSemu32.
• All rights depending on the GUSemu32 program are owned by its author, Tibor Schütz aka T$