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

{{IBM-Reprint}}

{{MMPM2DDRef}}
=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:
{|class="wikitable"
!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:
# Kernel known basedevs (resource manager)
# BASEDEVs
#:a) .ADDs first
#:b) .SYS
# 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.

{|class="wikitable"
|+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.

Because 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.
<pre>
  +----------+  +----------+  +----------+ +-----------+ +-----------+
  |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  |
  +---------+     +---------+     +---------+            +---------+
        |               +----------------------------------+  |
        +-----------------------------------------------------+
</pre>
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.
{|class="wikitable"
!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.
|}

[[Category:MMPM/2 Device Driver Reference]]