MMPM/2 Device Driver Reference:MAD16 PDD and VDD Sample Device Drivers

From EDM2
Jump to: navigation, search
MMPM/2 Device Driver Reference
  1. Adding Support for Audio and Video Adapters
  2. Audio Physical Device Driver Template
  3. Audio Virtual Device Driver Template
  4. MAD16 PDD and VDD Sample Device Drivers
  5. PDD Sample for Video Capture Adapters
  6. PDD Sample for MPEG Video Playback Devices
  7. Audio Sample for Vendor-Specific Drivers
  8. Using the High-Resolution Timer
  9. Real-Time MIDI Subsystem
  10. Audio Device Driver Exerciser (PMADDE) Tool
  11. AP2/P2STRING Tool
  12. Ultimotion Data Stream Specification
  13. DDCMD Messages
  14. SHD Messages
  15. Vendor-Specific Driver Commands
  16. IOCtl Functions
  17. Data Types
  18. Types of MIDI Messages
  19. Notices
  20. Glossary

By IBM

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

MAD16 PDD and VDD Sample Device Drivers (Watcom C)

The Developer Connection Device Driver Source Kit for OS/2 includes a PDD/ VDD pair that program the OPTi/MediaChips 82C928/82C929 Audio Controller (MAD16). The MAD16 is an integrated digital audio controller for PC sound applications.

Beyond its use for multimedia device developers, the sample provides a reference for using Watcom 16 and 32-bit C compilers for OS/2 device driver development.

The device drivers are located on the CD-ROM in the multimedia section.

PDD \ddkx86\mmos2\samples\mad16
VDD \ddkx86\mmos2\samples\vmad16

Board Architecture

The reference design for the MAD16 includes the following primary parts:

Chip Description
OPTi 82C929 (MAD16) Primary chip. ISA bus interface, CD-ROM control, MPU-401 interface and Sound Blaster to Windows Sound System command translation.
Audio Codec Windows Sound System compatible audio CODEC. The sample supports the Analog Devices AD1848 and the Crystal Semiconductor CS4231.
Yamaha YMF-262 (OPL-3) FM MIDI synthesis (same part as Sound Blaster Pro).
CD-ROM connectors Support Sony31A, Mitsumi, IDE and Panasonic drives. All interfaces are controlled via the MAD16.

The MAD16-based board can support applications and device drivers written to a variety of CD-ROM, audio and MIDI interfaces.

MAD16.ADD Device Driver Overview

All device configuration is performed through software programmable settings. Base I/O address and DMA and IRQ selections for CD-ROM and audio are initialized from software through the MAD16.ADD device driver. There are no jumpers.

Once enabled, existing device drivers can be used to perform audio and CD- ROM actions. For example, existing AD1848 business audio device drivers can be used on configurations with the AD1848. Existing CS4231 device drivers can be used in board configurations that have the CS4231 device. Likewise, the MAD16 device can be set to enable Sony31A, Mitsumi, Panasonic or IDE CD -ROM interfaces. An appropriate CD-ROM device driver is loaded later to perform CD-ROM activities.

The job of the MAD16.ADD is to initialize the device.

Boot Sequence

To initialize the device before the other device drivers load, the MAD16.ADD device driver has to load before the other device drivers (Audio/CD-ROM). OS/2 loads device drivers in a specific order. Device drivers needed to boot the system are loaded early. Less critical device drivers including audio are loaded toward the end of the device driver load sequence. In a particular class of device drivers, load order is based on order in the CONFIG.sys.

Device driver load order is as follows:

  1. Kernel known basedevs (resource manager)
  2. BASEDEVs
    a) .ADDs first
    b) .SYS
  3. Non-BASEDEVs (for example, Audio)

To load early, the MAD16.ADD wakeup code is written as a BASEDEV.ADD. This insures that regardless of CONFIG.SYS order, it loads early. For CD-ROM however, both the wakeup code and CD-ROM device driver are .ADDs. This creates an install requirement that the MAD16.ADD precede the CD-ROM device driver in CONFIG.SYS.

PDD Operation and Architecture

The MAD16.ADD does most of its work during initialization. Device modes and settings are read from a persistent database (CONFIG.SYS). The MAD16 device is programmed to set the base address of all the other parts on the board. For CD-ROM, turning the device on is all that is required. For audio, an initialization sequence is required to bring the audio Codec and MAD16 to a state where both Windows Sound System and Sound Blaster applications can be supported.

Using Watcom 16-bit C, the MAD16.ADD device driver has very little assembler code. The strategy routine is executed with no assembler stub. Watcom provides "pragma aux";, which allows the programmer to specify that parameters arrive in registers rather than on the stack. With this, much of the stub code popular in C device drivers is unnecessary.

The following table describes the MAD16.ADD source code.
MAD16.ADD Source Files Description
makefile Build procedure - "nmake".
DATA.C Device driver data (global).
DDPRINTF.C Support for writing messages to console (printf).
DDSTRING.C String processing routines (command line parsing support).
HEADER.C Device driver header (DevHdr).
IDC_PDD.C IDC operations for PDDs.
IDC_VDD.C IDC operations for VDDs.
INIT.C Initialization code (Good place to start reading).
IOCTL.C IO Control processing (called from Strategy routine).
MAD16.C Code that knows how to initialize the 82C929 MAD16 device.
MADUTIL.C Code that programs the MAD16 (retained after init).
QMAD16.C 32-bit Application - display PDD structures to screen.
SNDBLAST.C Code that knows how to reset and program a Sound Blaster Pro.
STRATEGY.C Device driver strategy routine.
TRACE.C Holds trace information and copies of error messages.
UTIL.C I/O delay function, OPL-3 mute code.
WSS.C Code that initializes the audio CODEC.
WSSUTIL.C Audio CODEC code (retained after init).
SEGS.ASM Define device driver segments.
UTILA.ASM IDC entrypoints (16:16 <-> 16:32 thunks).
DATA.H Header file for DATA.C.
DDPRINTF.H Header file for DDPRINTF.C.
DDSTRING.H Header file for DDSTRING.C.
HEADER.H Header file for HEADER.C.
IDC_PDD.H Header file for IDC_PDD.C.
IDC_VDD.H Header file for IDC_VDD.C.
IOCTL.H Header file for IOCTL.C.
MAD16.H Header file for MAD16.C.
REQPKT.H Header file for REQPKT.C.
RMHELP.H Header file for RMHELP.C.
SNDBLAST.H Header file for SNDBLAST.C.
STRATEGY.H Header file for STRATEGY.C.
TRACE.H Header file for TRACE.C.
UTIL.H Header file for UTIL.C.
WSS.H Header file for WSS.C.

VDD Operation and Architecture

Because all audio operations are performed by the audio CODEC, only one audio mode can be active at one time. The device is not capable of performing two concurrent wave audio play operations.

At initialization, one mode must be selected. By convention, the Windows Sound System mode is the default because this support is used by MMPM/2 and WinOS2 for wave audio operations.

Becuase OS/2 and WinOS2 audio are controlled by the audio CODEC PDD, DRV, and VDD, the VMAD16 VDD must communicate with the other drivers to negotiate use of the audio device.

Audio operations are performed using existing audio device drivers. Sound Blaster games are supported in a virtual DOS machine through a OS/2 Virtual Device Driver (VMAD16).

The figure below illustrates the architecture.

  +----------+  +----------+  +----------+ +-----------+ +-----------+
  |QMAD16.exe|  |MMPM/2    |  |WinOS2    | |DOS Session| |DOS Session|
  |Diagnostic|  |MME subsys|  |MME subsys| |WSS App    | |SB App     |
  +----------+  +----------+  |----------| +-----------+ +-----------+
       |             |        |Audio.DRV |      |             |
       | Ring-3      |        +----------+      |             |
  -----|-------------|--------------|-----------|-------------|-------
       | Ring-0      |              | +---------+             |
  +---------+     +---------+     +---------+            +---------+
  |MAD16.ADD|     |Audio PDD|-----|AudioVDD |            | VMAD16  |
  +---------+     +---------+     +---------+            +---------+
        |               +----------------------------------+  |
        +-----------------------------------------------------+

When a Sound Blaster specific application, such as a game, programs the device from a Virtual DOS machine, the VMAD16.SYS VDD intercepts the first port I/O and takes this as a request to use the audio hardware. It communicates with the audio CODEC PDD to gain ownership. Once ownership is attained, the VMAD16 VDD sends a command to the MAD16.ADD wakeup code commanding it to switch the device from Windows Sound System mode into Sound Blaster mode.

When the owning DOS application terminates, the VDD commands a switch back to Windows Sound System mode and returns device ownership to the audio CODEC PDD.

The following table describes the VMAD16.SYS source code.

VMAD16.SYS Source Description
makefile Build procedure - "nmake".
DDSTRING.C String processing routines.
EVENTS.C Session create/terminate and other event hooks.
GLOBDATA.C VDD global data declarations.
INIT.C Initialization code.
AUDIOREQ.C Routines to communicate with audio PDD for hardware ownership.
DATA.ASM Per DOS session instance data declarations.
UTILA.ASM IDC support (16:32 to 16:16 far calls).
AUDIOREQ.H Header for AUDIOREQ.C.
AUDIOVDD.H Header for AUDIOVDD.C.
DATA.H Prototypes for GLOBDATA.C and DATA.ASM.
DDSTRING.H Header for DDSTRING.C.
EVENTS.H Header for EVENTS.C.
UTIL.H Header for UTIL.C.