MMPM/2 Device Driver Reference:Adding Support for Audio and Video Adapters

MMPM/2 Device Driver Reference
Adding Support for Audio and Video Adapters Audio Physical Device Driver Template Audio Virtual Device Driver Template MAD16 PDD and VDD Sample Device Drivers PDD Sample for Video Capture Adapters PDD Sample for MPEG Video Playback Devices Audio Sample for Vendor-Specific Drivers Using the High-Resolution Timer Real-Time MIDI Subsystem Audio Device Driver Exerciser (PMADDE) Tool AP2/P2STRING Tool Ultimotion Data Stream Specification DDCMD Messages SHD Messages Vendor-Specific Driver Commands IOCtl Functions Data Types Types of MIDI Messages Notices Glossary

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

This DDK enables adding audio and video adapter support to the Multimedia Presentation Manager/2 (MMPM/2) audio and video subsystems without having to write a separate installation DLL for each adapter.

Adapters are added to the appropriate MMPM/2 subsystem by:

Specifying parameters in a resource file (.RC). The resource file is compiled to create the resource DLL.

Modifying control files that tell MINSTALL how to install your adapter.

Modifying a help file that displays help information to users when they are installing your adapter.

This process is shown in the illustration for a video adapter.

For additional information about adding support for an audio adapter, see Audio Adapter Installation or for adding support for a video adapter, see Video Adapter Installation.

Audio Adapter Installation

MMPM/2 allows installation of device drivers developed for audio adapters into the MMPM/2 audio subsystem. MMPM/2 can then use the audio adapter to play and record digital audio files. It can also play, but not record, MIDI files.

This DDK provides a generic installation program that performs the following functions:

Asks the user for any information needed to install your adapter, such as the interrupt level.

Updates the CONFIG.SYS file with your DEVICE= statements and any other necessary statements.

Updates the MMPM2.INI file so that MMPM/2 recognizes your device driver.

Copies the files needed by your adapter, such as device drivers.

The following steps provide an overview of how to use the generic audio installation program to install a device driver into the MMPM/2 audio subsystem. The \MMOS2\MMTOOLKT\SAMPLES\AUDINST subdirectory provides the generic audio installation sample files. For more information about the AUDINST files, see #Source Code. More detailed information about each step is provided in the following sections.

To add an audio adapter to the MMPM/2 audio subsystem, follow these steps:

Create an OS/2 device driver for the audio adapter.

For information on creating an OS/2 device driver, refer to Audio Physical Device Driver Template.
Write a Vendor-Specific Driver Resource File.

This file is an audio resource file that describes your audio device to MMPM/2.

For more information, see Step 2. Writing a Vendor-Specific Driver.
Modify the CARDINFO.RC file.

This file contains specific information about the adapter. MMPM/2 uses this information to interface with the adapter.

For more information, see Step 3. Modifying the CARDINFO.RC File.
If necessary, create a DLL to perform actions not provided by this generic audio installation program.

This step is not necessary, unless you want to perform some action that is not provided by the generic audio installation program.

For more information, see Step 4. Creating an Audio Installation DLL.
Modify the AUDHELP.ITL file.

This file contains information that is presented to the user when installing your adapter.

For more information, see Step 5. Modifying the AUDHELP.ITL File.
Run the MAKEFILE.

This file compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles AUDHELP.ITL into a help file called AUDHELP.HLP.

For more information, see Step 6. Running the MAKEFILE.
Modify the CONTROL.SCR file.

This file is the control file used by MINSTALL to determine what subsystems and devices a user can install.

For more information, see [[#Step 7. Modifying the CONTROL.SCR File]|Step 7. Modifying the CONTROL.SCR File]].
Modify the AUDFILES.SCR file.

This file lists the files the adapter uses. It tells MINSTALL which files need to be copied and into which subdirectories to place them.

For more information, see Step 8. Modifying the AUDFILES.SCR File.
If necessary, create a MIDI map.

This step is not necessary if the adapter uses the general MIDI specifications.

For more information, see Step 9. Creating a MIDI Map.
Create an installation diskette.

This diskette must contain all the files necessary to install the adapter into the MMPM/2 audio subsystem using MINSTALL.

For more information, see Step 10. Creating the Installation Diskette.
Install your adapter using MINSTALL.

For more information, see Step 11. Using MINSTALL to Install Your Adapter.

Source Code

The \MMOS2\MMTOOLKT\SAMPLES\AUDINST subdirectory provides the generic audio installation sample files. These sample files illustrate how to install an audio device driver into the MMPM/2 audio subsystem. The sample files include:

Source File	Description
MAKEFILE	Creates the resource DLL containing the audio adapter information by compiling the CARDINFO.RC file into the CARDINFO.DLL file. This file also compiles the AUDHELP.ITL file into the AUDHELP.HLP help file.
CARDINFO.RC	Supplies information about the audio adapter.
MIDIMAP.RC	Contains the sample MIDI map table.
RCSTUB.C	Stub 'C' file for compiling CARDINFO.RC.
AUDHELP.ITL	Contains the help information.
CONTROL.SCR	Contains the control information used by MINSTALL to install the audio adapter.
AUDFILES.SCR	Lists the files to be copied by MINSTALL. MINSTALL also copies this file.
MIDIMAP.SCR	Contains the INI change control file used by MINSTALL to install a MIDI map table.
GENIN.DLL	Is the generic installation program that installs your adapter.
GENINMRI.DLL	Contains the text used be GENIN.DLL

Note: Before modifying any of these files, make sure you have a backup copy.

Step 1. Creating an OS/2 Device Driver for an Audio Adapter

For information on creating an OS/2 device driver, refer to Audio Physical Device Driver Template.

Step 2. Writing a Vendor-Specific Driver

The vendor-specific driver (VSD) resource file describes your audio device to MMPM/2. When audio services are requested, the Media Device Manager (MDM) communicates with the amplifier-mixer (ampmix) device. Then, the ampmix device is opened, and it loads the VSD resource DLL and transfers adapter information into a memory buffer. If a user requests a particular mode (or audio setting), the VSD looks up that mode to determine the device characteristics and reports the specific information to the MDM. This process is shown in the following illustration:

You can reduce the amount of code required to add a device to MMPM/2 by using a VSD resource file. This file enables you to supply only one DLL for all the devices being added to MMPM/2.

To add a new audio device to the MMPM/2 audio subsystem, you must supply a device driver and a VSD resource file. Both are installed using the generic audio installation program. For more information, see Audio Adapter Installation.

An example VSD resource file (SAMPLE.RC) is in the \MMOS2\MMTOOLKT\SAMPLES\VSDRC subdirectory. When you use the generic audio installation program, you must specify the following parameters in the audio ampmixer's device- specific parameters:

RESOURCEDLL=: Specifies the name of the DLL that contains the audio resource description. The resource example in the Toolkit contains a DLL named SAMPLE.DLL and creates the following line in the MMPM2.INI file:; RESOURCEDLL=SAMPLE; Note: Do not specify the .DLL extension.

RCID=: Indicates which adapter in the VSD resource file is used for audio support. Resource DLLs can contain descriptions for multiple adapters. The sample resource file (\MMOS2\MMTOOLKT\SAMPLES\VSDRC\SAMPLE.RC) contains a description of two audio adapters, the ProAudio Spectrum (indicated by RCID=1) and the Sound Blaster Pro (indicated by RCID=2).

Resource File Layout

The following is the format of the vendor-specific driver (VSD) resource file:

RCDATA  <Device Number>
BEGIN
<Device Name>,
<Device ID>, <Reserved1>,
<Reserved2>,
<Number of Datatype Rows>,
<Datatype Row>
END

The following list describes the VSD resource file format parameters:

RCDATA

Indicates the beginning of the resource file for each audio adapter. For example, in the \MMOS2\MMTOOLKT\SAMPLES\VSDRC\SAMPLE.RC file, this parameter is (indicated in red):

RCDATA PAS_16

Device Number

Describes the offset in the resource file used to describe the device. This parameter is usually the name of the adapter. For example, in the \MMOS2\MMTOOLKT\SAMPLES\VSDRC\SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

RCDATA PAS_16

and for the Creative Labs Sound Blaster Pro adapter it is:

RCDATA SB_PRO

Each device number in the resource file must be unique. These numbers are determined by the manufacturer. The defines for the device numbers that are valid in this field are in the SAMPLE.H file.

This field must be a ULONG.

Device Name

Indicates the device name. This parameter must be the first item in the table because it is used by the amplifier-mixer to return product information. This string must be an ASCII string. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is:

"Media Vision Pro Audio Spectrum"

and for the Creative Labs Sound Blaster Pro adapter it is:

"Creative Labs Sound Blaster Pro"

Device ID

Indicates which device the system is using. It is the same as the device ID returned from the AUDIO_INIT IOCtl. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

PAS16, 0,

and for the Creative Labs Sound Blaster Pro adapter it is (indicated in red ):

SOUND_BLASTER, 0,

This field must be a USHORT.

Note: Because the Device ID in not explicitly defined to be a LONG, the resource compiler assumes this field is a USHORT.

Reserved1

This parameter is reserved and should be set to 0. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

PAS16, 0, 0L,

This field must be a USHORT.

Reserved2

This parameter is reserved and should be set to 0. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):

PAS16, 0, 0L,

This field must be a ULONG.

Number of Data Type Rows

Indicates the number of data type rows. A data type row is defined below.

Some parameters in the data type row can be duplicated, however, all rows must be unique. For example, the Bits Per Sample parameter is repeated often, but the rows are unique.

In the SAMPLE.RC file, the Media Vision ProAudio Spectrum adapter has 17 unique combinations of parameters such as Samples Per Second, Bits Per Sample, and Channels (these fields are described in the following parameters). Therefore, the value of this field is:

17L

and the Creative Labs Sound Blaster Pro adapter has 11 unique row descriptions. Therefore, the value of this field is:

11L

This field must be a ULONG.

Data type Row

A data type row describes the specific capabilities of each of audio device and consists of a combination of the following parameters:

RIFF Data Type; RIFF Data Subtype; Samples per Second; Bits per Sample; Channels; Sampling Descriptions; Play Resource Class; Play Resource Units Used; Record Resource Class; Record Resource Units Used
RIFF Data Type: Indicates a RIFF defined data type indicated in OS2MEDEF.H. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; For additional information, see the OS/2 Multimedia Programming Reference. These are the same subtypes used in the streaming subsystem.; This field must be a ULONG.
RIFF Data Subtype: Indicates the RIFF subtypes for a given data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; For additional information, see the OS/2 Multimedia Programming Reference. These are the same subtypes used in the streaming subsystem.
Samples Per Second: Indicates the sampling rate supported in this RIFF data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; This field must be a USHORT.
Bits Per Sample: Indicates the bits per sample supported in this RIFF data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; This field must be a USHORT.
Channels: Indicates the channels supported in this RIFF data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,
Sampling Descriptions: Describes the sampling rates. If the current data type row supports a specific sampling rate (for example, the device only supports one specific rate), the STATIC_RATE flag should be specified. For example, the M-Audio adapter can play only one specific sampling rate, so the STATIC_FLAG is specified (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16 8000, 16, 1, STATIC_RATE, PCM_CLASS, 1, 0, 0,; If a range of sampling rates are supported (for example, the device can play any rate between 2 kHz and 48 kHz), the lowest sampling rate in the range should contain the BEGIN_CONTINUOUS flag and highest sampling rate should be specified in one of the following rows with the END_CONTINUOUS flag. Intermediate sampling rates should also contain the BEGIN_CONTINUOUS flag. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter indicates support for rates between 2 kHz and 48 kHz (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; DATATYPE_WAVEFORM, WAVE_FORMAT_1M16, 11025, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; DATATYPE_WAVEFORM, WAVE_FORMAT_2M16, 22050, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; DATATYPE_WAVEFORM, WAVE_FORMAT_4M16, 48000, 16, 1, END_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; Notice that BEGIN_CONTINUOUS is used with the first sampling rate of 2000 and that END_CONTINUOUS ends the sampling rate at 48000. For additional information, see the OS/2 Multimedia Subsystem Programming Guide.; This field must be a ULONG.
Play Resource Class: Indicates the class for the data type defined in this row. For example, this parameter indicates that when a particular data type is defined, the data type falls under this particular class. This parameter matches a class defined for the amplifier-mixer (ampmix) device in the MMPM2.INI file and is determined by the manufacturer. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; This parameter is defined in the SAMPLE.H file. This field must be a USHORT.
Play Resource Units Used: Indicates the number of resource units this RIFF data type (or class) consumes. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; The Media Vision ProAudio Spectrum adapter only supports one instance at a time playing PCM, so the total resources for the class is 1. When this parameter specifies 1 for the Data type row, MDM assures that not more than one instance plays PCM at any one time. For additional information, see the OS/2 Multimedia Subsystem Programming Guide.; This field must be a USHORT.
Record Resource Class: Indicates the class for the RIFF data type in record mode. This parameter matches the class defined in the MMPM2.INI file and is determined by the manufacturer. If this value is nonzero, the amplifier- mixer assumes that recording is possible for this data type. For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,; If the class contains a zero, it is assumed that recording is not possible. For example, a device might not be able to record mono, PCM, 44 kHz data. Therefore, a 0 is entered in the record class (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 44000, 8, 1, END_CONTINUOUS, PCM_CLASS, 1, 0, 1,; This parameter also indicates that when a particular data type is defined, the data type falls under this particular class. The Media Vision ProAudio Spectrum adapter supports only one instance at a time when recording PCM, so the total resources for the class is 1. When this parameter specifies 1 for the data type, MDM assures that the device does not exceed this number of units.; This field must be a USHORT.
Record Resource Units Used: Indicates the number of resources this RIFF data type consumes in record mode (USHORT). For example, in the SAMPLE.RC file, this parameter for the Media Vision ProAudio Spectrum adapter is (indicated in red):; DATATYPE_WAVEFORM, WAVE_FORMAT_8M16, 2000, 16, 1, BEGIN_CONTINUOUS, PCM_CLASS, 1, PCM_CLASS, 1,

Step 3. Modifying the CARDINFO.RC File

The CARDINFO.RC file is located in the \MMOS2\MMTOOLKT\SAMPLES\AUDINST subdirectory. Modify this file so that it contains information relevant to your audio adapter. MMPM/2 uses this information to interface with your adapter.

Notes:

The lines in this file that contain RCDATA, BEGIN, and END identify the beginning and ending of specific pieces of data. Do not change these lines.
If more than one adapter is added, increment each RCDATA number by 10 for each additional adapter. For example, the first adapter uses RCDATA 10 through RCDATA 19, the second adapter uses RCDATA 20 through RCDATA 29, and so forth.
If the audio adapter does not have a value corresponding to one of the CARDINFO.RC file parameters, use a null string "/0" in the parameter.

The CARDINFO.RC parameters are:

RCDATA 1

Indicates the number of adapters described in this CARDINFO.RC file. In most cases, this is 1. To install more than one type of audio adapter, place that number in this parameter.

For example, in the CARDINFO.RC file, the ProAudio Spectrum adapter is:

RCDATA 1


BEGIN

   "1"           /* Number of adapters in this rc file */

END

RCDATA 10

Contains two parameters, the ID number and the type of audio adapter. The ID number is used in the CONTROL.SCR file that you modify in Step 7. The ID number can be any number. However, it must match the ssdllinputparmskeyword in the CONTROL.SCR file. For the type of adapter, use "audiovdd" if the adapter uses the IBM AUDIOVDD.SYS device driver. If the adapter does not use this driver, put "audio" in this field.

For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:

RCDATA 10


BEGIN

   "26",            /* ID number of this adapter             */

   "audiovdd"       /* Type of adapter - use audiovdd if you use the IBM audiovdd.sys driver */

END

For more information, see Audio Physical Device Driver Template.

RCDATA 11

Contains parameters that indicate:

The maximum number of this type of audio adapter that can be installed at one time. The maximum is six adapters.

The name of the help file that describes the audio adapter. This name defaults to AUDHELP.HLP if the MAKEFILE provided to create the help file is used.

The name of the audio-adapter-specific DLL you wrote to perform functions not provided by this generic audio installation program. This DLL is described in Step 4. Creating an Audio Installation DLL. If you did not write a DLL, specify "\0".

The name of the audio-adapter-specific DLL entry point into the DLL in the previous field. If you did not write a DLL, specify "\0".

The number of CONFIG.SYS lines to add to the user's CONFIG.SYS file to support the audio adapter. The maximum is six lines.

Note:Do not count the AUDIOVDD.SYS line.

The CONFIG.SYS line format of the lines added to the user's CONFIG.SYS file (except for the AUDIOVDD.SYS line). Tokens in this line are replaced with the appropriate values at runtime. The following list describes the tokens and their data substitutions:

*PATH*

Indicates the path where MMPM/2 is installed (for example, c:\MMOS2).

*ORD*

Indicates the device ordinal of this adapter.

*SEQ*

Indicates the sequential number of this adapter. For example, if the user installs two IBM audio adapters, the first will have a number of 1 and the second a number of 2.

*PDD*

Indicates the PDDName of this adapter.

*VAL*

Indicates the values that the user gives when prompted by the installation program. You can have more than one of these tokens if the user is asked for more than one item.

Note: Later in the CARDINFO.RC file, you specify which questions the installation program should ask.

*SPEC*

Indicates special values passed from your adapter-specific DLL.

For example, the line in the sample CARDINFO.RC file is:

"DEVICE=*PATH*\\MVPRODD.SYS /I*VAL* /D*VAL* /N:*PDD*"

After the real values are substituted, the CONFIG.SYS line is similar to:

DEVICE=C:\MMOS2\MVPRODD.SYS /I5 /D12 /N:PAS161$

The number of drivers to install into the MMPM/2 system. For an audio adapter, this would normally be three because most audio adapters install a Waveform, Audio Sequencer, and Audio Ampmixer driver. The maximum is six drivers.

The name of the adapter as it is displayed to the user.

The version number of the device driver.

The physical device driver name (PDDName) used to identify the device driver. The sequential number of the adapter and a "$" is added to this name to form the final PDDName. For example, if the user installs two ProAudio Spectrum 16 adapters, the PDDNames are PAS161$ and PAS162$.

The name of the MCD command table used by the drivers. In most cases, this is the IBM MCD command table 'MDM'.

The name of the VSD command table used by the drivers. In most cases this is blank.

For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:

RCDATA 11
BEGIN
   "1",                        /* Max number of adapters (2 chars)           */
   "audhelp.HLP",              /* Helpfile name (19 chars)                   */
   "\0",                       /* Adapter specific dll name (19 chars)       */
   "\0",                       /* Adapter specific dll entry point (39 chars)*/

   /**** Data for CONFIG.SYS **/
   "1",                        /* Number of CONFIG.SYS lines (1 char)        */
   "DEVICE=*PATH*\\MVPRODD.SYS /I*VAL* /D*VAL* /N:*PDD*"
                               /* CONFIG.SYS Line 1                          */
                               /* (255 chars after token substitution)       */

   /**** Data for INI File ****/
   "3",                        /* Number of Drivers to Install (1 char)      */
   "Pro AudioSpectrum 16",     /* Product name (39 chars)                    */
   "1.0"                       /* Version of the adapter's software (5 chars)*/
   "PAS16",                    /* PDD Name  (6 chars)                        */
   "MDM",                      /* MCD table name (19 chars)                  */
   "\0"                        /* VSD table name (19 chars)                  */
END

RCDATA 12

This group of parameters is repeated for each driver you want to install. The repeated groups start with RCDATA 13, RCDATA 14, and so forth.) These parameters indicate:

The InstallName of this driver. This must be a unique name. Consider using a name that is a combination of a company name, device type, and device model. The sequential number of this adapter is added to the name (for example, IBMWAVEPAS1601).

The device type encoding. These codes are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

The numeric device flag of this driver. Specifies the LONG INT with the flags set. This determines whether or not the device is controllable. The device flags are defined in the MCIOS2.H file located in the \MMOS2\ MMTOOLKT\H subdirectory.

The name of the media control driver (MCD) used by this driver. In most cases, this is the IBM MCD "AUDIOMCD."

The name of the vendor-specific driver (VSD) used by this driver. In most cases, this is the IBM VSD "AUDIOIF."

The numeric share type. Specifies an encoding of the valid types of sharing supported. These codes are defined in the MMDRVOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

The name to be given to this driver's resources. Specifies a unique name for the management of the driver resources. The sequential number of the adapter is added to this name so that resources of different drivers are not mixed. If you have more than one driver, be sure to use a different resource name for each driver. For more information, see Resource Units and Classes.

The number of resource units supported by this driver. For more information, see Resource Units and Classes.

The number of resource classes supported by this driver. The maximum is nine resource classes. These classes are listed in the next field. For more information, see Resource Units and Classes.

The resource classes. For more information, see Resource Units and Classes.

The number of valid combinations of resource classes. The maximum is 81 combinations. For more information, see Resource Units and Classes.

The valid resource class combinations. Resource class combinations are always listed in pairs. For example, if a class 1 can combine with a class 2, then class 2 can combine with class 1.

For more information, see Resource Units and Classes.

The number of connectors. These are listed in the next field. The maximum is 10 connectors. Each implementation of a media driver defines the paths of information flow into and out of the device. These paths are known as connectors. Connectors have defined connector types, and each connector type has an associated connector-type name.

The connectors. Each connector has three values:

-Numeric type of connector. Connection types are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

-InstallName of the driver to which it connects. If left blank, a default connector is used.

-Sequential number of the connector to which it connects. The sample CARDINFO.RC file uses:

"3","IBMAMPMIXPAS16","1"

where:

3: Indicates the wave stream connector.
"IBMAMPMIXPAS16": Indicates the amplifier-mixer device.
1: Indicates the first connector of the amplifier-mixer device.

The number of file-name extensions associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the file extension. For example, if the .WAV extension is associated with an internal driver name, that driver will be used if a file ending in .WAV is opened.

The file-name extensions associated with this driver.

The extended attribute associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the file's extended attribute. For example, if the "Digital Audio" extended attribute is associated with an internal driver name, that driver will be used if a file with an extended attribute of "Digital Audio" is opened.

The AliasName given to the driver. The device ordinal is added to this name if the ordinal is greater than 1. For example, the second Waveform Audio driver would be given an AliasName of Digital Audio 2.

Any device specific parameters. For the Waveform Audio driver, the following parameters set up the initial state of the adapter, and should be listed:

FORMAT= RIFF Datatype

The RIFF Datatype is a format tab defined in \MMOS2\ MMTOOLKT\H\OS2MEDEF.H.

SAMPRATE=

Indicates the sample rate.

BPS=

Indicates the bits per second.

CHANNEL=

Indicates mono (1) or stereo (2).

DIRECTION=

Indicates PLAY or RECORD.

For the Audio AmpMixer driver, the following parameters set up the initial state of the adapter, and should be listed.

TREBLE=

Indicates the treble setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

BASS=

Indicates the bass setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

PITCH=

Indicates the pitch setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

GAIN=

Indicates the increase in level of output over the level of input setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

BALANCE=

Indicates the BALANCE setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

VOL=

Indicates the volume setting. Valid values are from 0 to 100. This parameter should usually match the sample CARDINFO.RC file.

INPUT=

Specifies LINE or MIC.

OUTPUT=

Specifies SPEAKERS or HEADPHONES.

RESOURCEDLL=

Specifies the name of the vendor-specific driver resource DLL that you create. For more information, see Step 2. Writing a Vendor- Specific Driver.

RCID Specifies the resource ID in the vendor-specific driver resource DLL that you create. For more information, see Step 2. Writing a Vendor- Specific Driver. For the Sequencer driver, the following parameters are listed

CHANNELS=: This parameter is followed by 16 1s or 0s to represent whether the sequencer's channels default to on (1) or off (0).
MIDITYPE=: This parameter is followed by "General MIDI" if your adapter uses the General MIDI specification. If your adapter does not use General MIDI, you create a MIDI Map Table as specified in Step 9. Creating a MIDI Map. In this case, the parameter is followed by the adapter name. This name must be the same name used for "keyname" in the MIDIMAP.SCR file in Step 9. Creating a MIDI Map.

For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:

RCDATA 12
BEGIN 
    /**** WAVEAUDIO Driver ****/ 
    "IBMWAVEPAS16 "             /* Installname (17 chars)                     */
    "7",                        /* Device type (3 chars)                      */
    "1",                        /* Device flag (3 chars)                      */
    "AUDIOMCD",                 /* MCD driver name (19 chars)                 */
    "AUDIOIF",                  /* VSD driver name (19 chars)                 */
    "3",                        /* Share Type (3 chars)                       */
    "ProAudioSpecW",            /* Resource name (17 chars)                   */
    "1",                        /* # of Resource units (2 chars)              */
    "1",                        /* # of Resource classes (2 chars)            */
    "1",                        /* Resource classes (2 char each)             */
    "0",                        /* # Valid resource class combos (2 chars)    */
                                /* Valid resource class combos (2 chars each) */
    "1",                        /* # of connectors (2 chars)                  */
    "3","IBMAMPMIXPAS16","1",   /* Connectors (2 chars), (17 chars), (2 chars)*/
    "1",                        /* # of extensions (2 chars )                 */
    "WAV",                      /* Extension names (3 chars each)             */
    "Digital Audio",            /* Extended attribute (255 chars)             */
    "Digital Audio",            /* Alias Name (17 chars)                      */
    "FORMAT=1,SAMPRATE=22050,BPS=16,CHANNELS=1,DIRECTION=PLAY"
                                /* Device Specific Parameters (255 chars)     */
END

RCDATA 19

This group of parameters indicates:

The number of prompts that should be presented to the user. This number is used to gather configuration-specific information about the adapter. The maximum is 10 prompts.

The title of the prompt text as it is displayed to the user.

The number of valid answers to the prompt. The maximum is 25 answers. You supply the valid answers in the next field.

The valid answers to your prompt. These answers are displayed to the user. The user can select one.

The values that are put in your CONFIG.SYS line. These values replace the *VAL* tokens that you placed in your CONFIG.SYS line format previously in this CARDINFO.RC file. These values correspond to the valid answers in the previous field. For example, if the user selects answer number three from the list of valid answers, then value number three is placed into your CONFIG.SYS line. This allows you to ask the user questions in a user-friendly fashion and then place a more cryptic value in the CONFIG.SYS line.

For example, if you want to ask the user which song to play, you can use the following prompt:

Song to play on startup?

You can present the following choices to the user:

Happy Birthday


Beethoven's Fifth

Joy to the World

The values put into the CONFIG.SYS line could be "birthday.wav", "beet_5.wav", or "joyworld.wav".

The default answer to the prompt. This is an index into the list of valid answers. For example, if the second answer is the default, specify "2". For an example of how to specify the RCDATA 19 parameters for this example, see Songs Example.

For example, in the CARDINFO.RC file, the ProAudio Spectrum 16 adapter is:

RCDATA 19
BEGIN
   // Prompts for the User
   "2",                        /* Number of prompts to ask user (2 chars)    */
                               /* (max 10 prompts)                           */
   // Prompt 1
   "DMA Channel",              /* Title of Prompt (max 50 chars)             */
   "7",                        /* # of valid values (2 chars)                */
   "0","1","2","3",            /* Valid values  (20 chars each)              */
   "5","6","7",
   "0","1","2","3",            /* Corresponding config.sys values            */
   "5","6","7",                /* (20 chars each)                            */

   "4",                        /* Default value - Index into valid values    */
                               /* (2 chars)                                  */

   // Prompt 2
   "Interrupt Level",          /* Title of Prompt (max 50 chars)             */
   "8",                        /* # of valid values (2 chars)                */
   "Interrupt 2",              /* Valid values (20 chars each)               */
   "Interrupt 3",
   "Interrupt 5",
   "Interrupt 7",
   "Interrupt 10",
   "Interrupt 11",
   "Interrupt 12",
   "Interrupt 15",

   "2",                        /* Corresponding config.sys values            */
   "3",                        /* (20 chars each)                            */
   "5",
   "7",
   "10",
   "11",
   "12",
   "15",

   "6"                         /* Default value - Index into valid values    */
                               /* (2 chars)                                  */
END

Songs Example

The following is an example of how to specify RCDATA 19 parameters to ask a user what song to play:

RCDATA 19
BEGIN
   // Prompts for the User
   "1",                        /* Number of prompts to ask user (2 chars)    */
                               /* (max 10 prompts).                          */
   // Prompt 1
   "Song to play on startup?", /* Title of prompt (max 50 chars).            */
   "3",                        /* Number of valid values (2 chars).          */
   "Happy Birthday"            /* Valid values  (20 chars each).             */
   "Beethoven's Fifth"
   "Joy to the World"

   "birthday.wav"              /* Corresponding CONFIG.SYS values            */
   "beet_5.wav"                /* (20 chars each)                            */
   "joyworld.wav"

   "2",                        /* Default value - Index into valid values    */
                               /* (2 chars)                                  */

END

Step 4. Creating an Audio Installation DLL

In some cases, you might want to perform some action that is specific to your adapter, and thus not provided by this generic audio installation program. For example, you might want to query the user's hardware setup to determine values, such as interrupt level, rather than prompting the user for those values. In this case, you can create your own DLL to perform these functions.

The audio installation program calls your DLL and allows it to return values that can be added to your lines in the CONFIG.SYS file. The following steps describe how to use your DLL:

1.Write and compile the DLL.

The entry point to your DLL must accept the following parameters:



CardSpecDLLEntry (USHORT usCardNum,






CHAR   achSpec[259])

where:

usCardNum: Is the sequential number of this adapter.; For example, if the user chooses to install two of these adapters, the DLL is called twice. The first time the DLL is called, usCardNum is 1, and the second time the DLL is called, usCardNum is 2.
achSpec[5][259]: Is a two dimensional array that can hold up to five strings of 259 characters each. Your DLL can put values into these five strings. The audio installation program then puts these strings into lines in the CONFIG.SYS file as specified in CARDINFO.RC. If there is more than one of these values, they are put into the CONFIG.SYS in sequential order. For example, your DLL fills in the following values:; achSpec[0]="rec"; achSpec[1]="3"; achSpec[2]="11"; achSpec[3]=""; achSpec[4]=""

The format of your CONFIG.SYS line in CARDINFO.RC is:

"DEVICE=*PATH*\\MVPRODD.SYS *SPEC* *SPEC* *SPEC*"

The line that is put into CONFIG.SYS is:

DEVICE=D:\MMOS2\MVPRODD.SYS rec 3 11

2.Put the name of the DLL and the name of the DLL's entry point into CARDINFO.RC.

Step 5. Modifying the AUDHELP.ITL File

AUDHELP.ITL is a help file that gives information to the user when the user installs the audio adapter. Use this file to describe any prompts that ask the user for information. Be careful when modifying this file because the basic format of the file must remain the same for the help to work correctly. If you do not prompt the user for any information, then modify only the first section of the file that explains to the user how many adapters can be installed.

Step 6. Running the MAKEFILE

The MAKEFILE compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles AUDHELP.ITL into a help file called AUDHELP.HLP.

Step 7. Modifying the CONTROL.SCR File

You must modify the CONTROL.SCR file so that it contains information relevant to your adapter. This file is the main control file used by MINSTALL, MMPM/2's installation program. CONTROL.SCR tells MINSTALL what subsystems and devices that the user can install.

Modify the following fields in the Audio Adapter Group:

Note: Do not change the fields not listed here.

ssgroup: Specifies the audio adapter group number. The only reason you might need to change this number is if you are installing more than one type of adapter. If you install more than one type of adapter, you must duplicate the entire audio adapter group and change the group number on the second group. If you add one or more groups, you must increment the group count at the top of this file.

ssname: Specifies the audio adapter's name.
ssversion: Specifies the version number of the device driver.
sssize: Specifies the total size (in KB) of the device drivers, the AUDHELP.HLP help file, GENIN.DLL, GENINMRI.DLL, and any other files you install.
ssdllinputparms: Matches the ID number used in CARDINFO.RC.; Specifies the MIDI map table. Uncomment this line if you create a MIDI map in Step 9.

Step 8. Modifying the AUDFILES.SCR File

Modify the AUDFILES.SCR file so that it lists all the files your adapter uses. AUDFILES.SCR tells MINSTALL which files need to be copied, and into which subdirectories those files should be copied.

After changing the list of files in AUDFILES.SCR, change the "Total Number of Files to Copy" in AUDFILES.SCR to match the number of files you have listed.

Step 9. Creating a MIDI Map

If the audio adapter uses the General MIDI specification, this step is not necessary. When MMPM/2 plays a MIDI file, it maps the patch assignments according to the General MIDI specification. If the audio adapter uses a patch assignment other than General MIDI, you must create a MIDI map table to tell MMPM/2 how to map the patches.

The following steps describe how to create a MIDI map:

1.Modify the MIDIMAP.RC file to hold the MIDI map table.

The MIDIMAP.RC file holds a sample MIDI map table. Modify this table to describe the adapter. The data in MIDIMAP.RC is defined by the MIDITYPE structure. This structure is defined in the MIDITYPE.H file.

typedef struct {
  USHORT uGenMidiPatchNumber; /* Device To General MIDI Conversion */
  USHORT uDevMidiPatchNumber; /* General MIDI to Device Conversion */
  USHORT uVolumePercent;      /* Channel Patch Volume Scaler */
  USHORT uGenMidiKeyNumber;   /* Device To General MIDI Key Conversion */
  USHORT uDevMidiKeyNumber;   /* General MIDI to Device Key Conversion */
} MIDITYPEENTRY;
typedef MIDITYPEENTRY FAR * PMIDITYPEENTRY;

typedef struct {
   USHORT     uStyle;           /* MIDI Mapping Style */
   USHORT     uDrums10;         /* Patch for Percussion Channel 10 */
   USHORT     uDrums16;         /* Patch for Percussion Channel 16 */
   ULONG      ulReserved;       /* Reserved */
   MIDITYPEENTRY MidiTypeEntry[128];   /* Array of MIDITYPEENTRYs  */
   CHAR       szPatchAndPercKeyName[2*128*40];
                                /* List of 128 Patch Names */
                                /* that are null terminated, then a */
                                /* list of 128 Percussion key names */
                                /* that are double null terminated  */
                                /* Each item is null terminated     */
} MIDITYPE;
typedef MIDITYPE FAR * PMIDITYPE;

The uStyle field specifies flags that indicate the type of mapping that is required in order to translate from general MIDI to a specific device.

The MT_PERCUSSIONKEYS flag indicates that the device supports percussion keys and that the percussion keys will be translated according to the key conversion tables. If percussion keys are not supported by the MIDI device and MT_MAPPERCKEYPATCHES is specified, then patches on percussion channels will be mapped to the patch indicated in uDrums10or uDrums16. This will enable the mapper to map patch changes on a percussion channel to a drum patch. Individual percussion sounds cannot be mapped but a percussive sound will be heard.

Included in the MIDITYPE data structure is an array of MIDITYPEENTRY structures. This structure includes information for mapping patches and percussion keys between general MIDI and the particular MIDI device.

uGenMidiPatchNumber: Describes the mapping of the nth Patch number from the devices patch assignments to general MIDI patch assignments.
uDevMidiPatchNumber: Describes the mapping of the nth patch number from the general MIDI patch assignments of the device.
uRelativeVolume: Describes the relative volume of the nth patch when mapping from general MIDI to the specified MIDI device.
uGenMidiKeyNumber: Describes the mapping of the nth percussion key number from the devices percussion key assignments to general MIDI percussion key assignments.
uDevMidiKeyNumber: Describes the mapping of the nth percussion key number from general MIDI percussion key assignments to the devices percussion key assignments.
szPatchAndPercKeyName: Lists patch names for each of 128 patches for this MIDI device. Each name is null terminated and the list is double-null terminated. Following the list of patch names is the list of percussion key names for each of 128 keys. These names can eventually be used in a user interface.

2.Modify the MAKEFILE to build the MIDIMAP.RC file into a resource file.

At the end of the MAKEFILE, there is a group of commands that are commented out. These are the commands that build MIDIMAP.RC into MIDIMAP.DLL. Take the comment character (#) off the beginning of each of these lines.

Also in the MAKEFILE are two lines that begin with the word "all." These should be near the 83rd line. Take the comment character (#) off the beginning of the second line and add a comment character (#) to the beginning of the first line. These lines tell the MAKEFILE which targets to build.

3.Run the MAKEFILE to create the MIDIMAP.DLL resource file.

4. Modify the .INI change file called MIDIMAP.SCR.

In MIDIMAP.SCR, change the keyname from "Your Adapter" to the name of the adapter. This file tells the installation program to install the MIDI map table contained in MIDIMAP.DLL into MMPM/2's MIDITYPE.INI file.

5. Modify the CARDINFO.RC file to name your MIDI map.

In the device-specific parameters field for the Sequencer driver, there is a parameter called MIDITYPE. Set this parameter to the same name used in the MIDIMAP.SCR file in Step 5. For example, you could use MIDITYPE=Your Adapter.

Note: Make sure that you use the exact spelling (including capitalization) as in MIDIMAP.SCR.

6. Modify CONTROL.SCR so that it calls MIDIMAP.SCR.

The last line of the CONTROL.SCR file contains a line that is commented out. Take the comment characters (/* */) off of this line. This removal causes the installation program to run MIDIMAP.SCR during installation.

7. Modify AUDFILES.SCR to add the MIDIMAP.DLL file.

In the AUDFILES.SCR file, the last file listed is MIDIMAP.DLL. This file is commented out. Remove the comment characters (/*) at the beginning of the line so that your MIDI map file is copied. Increment the number of files at the top of AUDFILES.SCR.

Step 10. Creating the Installation Diskette

Create a diskette that contains the following files:

CONTROL.SCR

AUDFILES.SCR

MIDIMAP.SCR (if you created one)

MIDIMAP.DLL (if you created one)

CARDINFO.DLL

AUDHELP.HLP

GENIN.DLL

GENINMRI.DLL

Your device drivers

Step 11. Using MINSTALL to Install Your Adapter

You can test your installation diskette before sending it to your customers by running MINSTALL.

Before installing the audio adapter, the base MMPM/2 that comes with OS/2 2.1 (or later) must be installed.

After installing the base MMPM/2, you can install your adapter. The following steps describe how to use MINSTALL:

Place the installation diskette in drive A.
Type MINSTALLon the OS/2 command line.
Change the source drive to A.
Select the adapter.
If errors occur, check the MINSTALL.LOG file in the \MMOS2\INSTALL subdirectory for error messages.

Video Adapter Installation

MMPM/2 allows installation of device drivers developed for video adapters into the MMPM/2 video subsystem using a generic video installation program.

This DDK provides a generic video installation program that performs the following functions:

Asks the user for any information needed to install your adapter, such as the interrupt level.

Updates the CONFIG.SYS file with your DEVICE= statements and any other necessary statements.

Updates the MMPM2.INI file so that MMPM/2 recognizes your device driver.

Copies the files needed by your adapter, such as device drivers.

The following steps provide an overview of how to install a device driver into the MMPM/2 video subsystem so that it can be used by the Digital Video Recorder to record software motion video. The \MMOS2\MMTOOLKT\SAMPLES\ VIDINST subdirectory provides the generic video installation sample files. For more information about the VIDINST files, see Source Code section below.

Source Code

The \MMOS2\MMTOOLKT\SAMPLES\VIDINST subdirectory provides the installation sample files for a video device driver. These sample files illustrate how to install a video device driver into the MMPM/2 video subsystem. The sample files include:

Sample File	Description
MAKEFILE	Creates the resource DLL containing the video adapter information by compiling the CARDINFO.RC file into the CARDINFO.DLL file. This file also compiles the VIDHELP.ITL file into the VIDHELP.HLP help file.
CARDINFO.RC	Supplies information about the video adapter.
RCSTUB.C	Stub 'C' file for compiling CARDINFO.RC.
VIDHELP.ITL	Contains the help information.
CONTROL.SCR	Contains the control information used by MINSTALL to install the video adapter.
VIDFILES.SCR	Lists the files to be copied by MINSTALL. MINSTALL also copies this file.

Note:Before modifying any of these files, make sure you have a backup copy.

More detailed information about each step is provided in the following sections. The steps must be performed in the order listed.

To add a video capture adapter to the MMPM/2 video subsystem, follow these steps:

Create an OS/2 device driver for the video capture adapter.

For information on creating an OS/2 device driver, refer to the OS/2 Physical Device Driver Reference.
Modify the CARDINFO.RC file.

This file contains specific information about the adapter. MMPM/2 uses this information to interface with the adapter.

For more information, see Step 2. Modifying the CARDINFO.RC File.
If necessary, create a DLL to perform actions not provided by this generic video installation program.

This step is not necessary, unless you want to perform some action that is not supported by the generic video installation program. For more information, see Step 3. Creating a Video Installation DLL.
Modify the VIDHELP.ITL file.

This file contains information that is presented to the user when installing your adapter.

For more information, see Step 4. Modifying the VIDHELP.ITL File.
Run the MAKEFILE.

This file compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles VIDHELP.ITL into a help file called VIDHELP.HLP.

For more information, see Step 5. Running the MAKEFILE.
Modify the CONTROL.SCR file.

This file is the control file used by MINSTALL to determine what subsystems and devices a user can install. For more information, see Step 6. Modifying the CONTROL.SCR File.
Modify the VIDFILES.SCR file.

This file lists the files the adapter uses. It tells MINSTALL which files need to be copied, and into which subdirectories to place them.

For more information, see Step 7. Modifying the VIDFILES.SCR File.
Create an installation diskette.

This diskette must contain all the files necessary to install the adapter into the MMPM/2 video subsystem using MINSTALL.

For more information, see Step 8. Creating the Installation Diskette.
Install your adapter using MINSTALL.

For more information, see Step 9. Using MINSTALL to Install Your Adapter.

Step 1. Creating an OS/2 Device Driver

For information on creating an OS/2 device driver, refer to the OS/2 Physical Device Driver Reference.

Step 2. Modifying the CARDINFO.RC File

The CARDINFO.RC file is located in the \MMOS2\MMTOOLKT\SAMPLES\VIDINST subdirectory. Modify this file so that it contains information relevant to your video adapter. MMPM/2 uses this information to interface with the adapter.

Notes:

The lines in this file that contain RCDATA, BEGIN, and END identify the beginning and ending of specific pieces of data. Do not change these lines.
If more than one adapter is added, increment each RCDATA number by 10 for each additional adapter. For example, the first adapter uses RCDATA 10 through RCDATA 19, the second adapter uses RCDATA 20 through RCDATA 29, and so forth.
If the video adapter does not have a value corresponding to one of the CARDINFO.RC file parameters, use a null string "/0" in the parameter.

The CARDINFO.RC parameters are:

RCDATA 1: Indicates the number of adapters described in this CARDINFO.RC file. In most cases, this is 1. To install more than one type of video adapter, place that number in this parameter.; For example, in the CARDINFO.RC file, the Video Blaster adapter is:



RCDATA 1

BEGIN

   "1"           /* Number of adapters in this rc file   */



END

RCDATA 10: Contains two parameters, the ID number and type of adapter used in the CONTROL.SCR file. The ID number can be any number. However, it must match the ssdllinputparmskeyword in the CONTROL.SCR file that is modified in Step 6. Modifying the CONTROL.SCR File. For the type of adapter, the only valid value is "vca."

For example, in the CARDINFO.RC file, the Video Blaster adapter is:



RCDATA 10

BEGIN

   "33",            /* ID number of this adapter */

   "vca"            /* Type of adapter           */



END

RCDATA 11

Contains parameters that indicate:

The maximum number of this type of video adapter that can be installed at one time. The maximum is six adapters.; The name of the help file that describes the video adapter. This name defaults to VIDHELP.HLP if the MAKEFILE provided to create the help file is used.; The name of the video-adapter-specific DLL you wrote to perform functions not provided by this generic video installation program. This DLL is described in Step 3. Creating a Video Installation DLL. If you did not write a DLL, specify "\0."; The name of the video-adapter-specific DLL entry point into the DLL in the previous field. If you did not write a DLL, specify "\0."; The number of CONFIG.SYS lines to add to the user's CONFIG.SYS file to support the video adapter. The maximum is six lines.; The CONFIG.SYS line format of the lines added to the user's CONFIG.SYS file. Tokens in this line are replaced with the appropriate values at runtime. The following list describes the tokens and their data substitutions:
PATH*: Indicates the path where MMPM/2 was installed (for example, c:\MMOS2 ).
*ORD*: Indicates the device ordinal of this adapter.
*SEQ*: Indicates the sequential number of this adapter. For example, if the user installs two IBM video capture adapters, the first will have a number of 1 and the second a number of 2.
*PDD*: Indicates the PDDName of this adapter.
*VAL*: Indicates the values that the user gives when prompted by the installation program. You can have more than one of these tokens if the user is asked for more than one item.; Note:Later in the CARDINFO.RC file, you specify which questions the install program should ask.
*SPEC*: Indicates special values passed from your adapter-specific DLL.

For example, the line in the sample CARDINFO.RC file is:




"DEVICE=*PATH*\\VIDVBC.SYS /*VAL* /*VAL* /*VAL* /*SEQ*"

After the real values are substituted, the CONFIG.SYS line is similar to:




DEVICE=C:\MMOS2\VIDVBC.SYS /0F00000 /2AD6 /I5 /1

The number of drivers to install into the MMPM/2 system. For a video capture adapter, this would normally be 1 because a Digital Video driver is the only driver installed. The maximum is six drivers.

The name of the adapter as it is displayed to the user.

The version number of the device driver.

The physical device driver name (PDDName) used to identify the device driver. The sequential number of the adapter and a "$" is added to this name to form the final PDDName. For example, if the user installs two Video Blaster** Adapters, the PDDNames are VIDVBC1$ and VIDVBC2$.

The name of the MCD command table used by the drivers. In most cases, this is the IBM MCD command table 'MDM'.

The name of the VSD command table used by the drivers. In most cases, this is blank.

For example, in the CARDINFO.RC file, the Video Blaster adapter is:

RCDATA 11
BEGIN
   "1",                        /* Max number of adapters (2 chars)  (6 max)  */
   "vidhelp.hlp",              /* Helpfile name (19 chars)                   */
   "\0",                       /* Adapter specific dll name (19 chars)       */
   "\0",                       /* Adapter specific dll entry point (39 chars)*/

   /**** Data for CONFIG.SYS **/
   "1",                        /* Number of CONFIG.SYS lines (1 char)        */
   "DEVICE=*PATH*\\VIDVBC.SYS /*VAL* /*VAL* /*VAL* /*SEQ*",
                               /* CONFIG.SYS Line 1                          */
                               /* (255 chars after token substitution)       */

   /**** Data for INI File ****/
   "1",                        /* Number of Drivers to Install (1 char)      */
   "Video Blaster",            /* Product name (39 chars)                    */
   "1.0.0",                    /* Version of the adapter's software (6 chars)*/
   "VIDVBC",                   /* PDD Name  (5 chars)                        */
   "MDM",                      /* MCD table name (19 chars)                  */
   "\0"                        /* VSD table name (19 chars)                  */
END

RCDATA 12

This group of parameters is repeated for each driver you want to install. The repeated groups should start with RCDATA 13, RCDATA 14, and so forth. These parameters indicate:

The InstallName of this driver. This must be a unique name. Consider using a name that is a combination of a company name, device type, and device model. The sequential number of this adapter is added to the name (for example, IBMDIGVIDCVB01).

The device type encoding. These codes are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

The numeric device flag of this driver. Specifies the LONG INT with the flags set. This determines whether or not the device is controllable. The device flags are defined in the MCIOS2.H file located in the \MMOS2\ MMTOOLKT\H subdirectory.

The name of the media control driver (MCD) used by this driver. In most cases, this is the IBM MCD 'SVMC'.

The name of the vendor-specific driver (VSD) used by this driver. In most cases, this is the IBM VSD 'VIDVCI'.

The numeric share type. Specifies an encoding of the valid types of sharing supported. These codes are defined in the MMDRVOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

The name to be given to this driver's resources. Specifies a unique name for the management for the driver resources. The sequential number of the adapter is added to this name so that resources of different drivers are not mixed. If you have more than one driver, be sure to use a different name for each driver. For more information, see Resource Units and Classes.

The number of resource units supported by this driver. For more information, see Resource Units and Classes.

The number of resource classes supported by this driver. The maximum is nine resource classes. These classes are listed in the next field. For more information, see Resource Units and Classes.

The resource classes. For more information, see Resource Units and Classes.

The number of valid combinations of resource classes. For more information, see Resource Units and Classes.

The valid resource class combinations. Resource class combinations are always listed in pairs.

Note: This field is not in the sample because Video Blaster does not have any valid resource class combinations. If it did, the combination would be listed similar to this:

"1","2", (One combines with two)

"2","1", (Two combines with one)

For more information, see Resource Units and Classes.

The number of connectors. These are listed in the next field. The maximum is 10 connectors. Each implementation of a media driver defines the paths of information flow into and out of the device. These paths are known as connectors. Connectors have defined connector types, and each connector type has an associated connector-type name.

The connectors. Each connector has three values:

-Numeric type of connector. Connection types are defined in the MCIOS2.H file located in the \MMOS2\MMTOOLKT\H subdirectory.

-InstallName of the driver to which it connects. If left blank, a default connector is used.

-Sequential number of the connector to which it connects.

The sample CARDINFO.RC file uses:

"3","","1"

where:

3

Indicates the wave stream connector.

""

Indicates the default WaveAudio device.

1

Indicates the first connector of the WaveAudio device.

The number of file-name extensions associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the file extension. For example, if the .AVI extension is associated with an internal driver name, that driver will be used if a file ending in .AVI is opened.

The file-name extensions associated with this driver.

Note: This field is not used in the sample because no extensions are associated with the driver for Video Blaster. If there were extensions, they would be listed like the following:

"AVI", "AVS"

The extended attribute associated with this driver. When an element name is specified as the device name on an MCI_OPEN message and no device type is specified, the device type is identified by the files extended attribute. For example, if the "Digital Video" extended attribute is associated with an internal driver name, that driver will be used if a file with an extended attribute of "Digital Video" is opened.

The AliasName given to the driver. This is an alternate name given to the driver. The device ordinal is added to this name if the ordinal is greater than 1. For example, the second DigitalVideo device would be given an AliasName of Digital Video 2.

Any device specific parameters. These parameters allow you to provide additional information about the driver to the MCD. In most cases, this is blank.

For example, in the CARDINFO.RC file, the Video Blaster adapter is:

RCDATA 12
BEGIN
   /**** DIGITAL VIDEO Driver ****/
   "IBMDIGVIDCVB",             /* Installname (17 chars)                     */
   "12",                       /* Device type (3 chars)                      */
   "1",                        /* Device flag (3 chars)                      */
   "SVMC",                     /* MCD driver name (19 chars)                 */
   "VIDVCI",                   /* VSD driver name (19 chars)                 */
   "3",                        /* Share Type (3 chars)                       */
   "Video Blaster",            /* Resource name (17 chars)                   */
   "10",                       /* # of Resource units (2 chars)              */
   "2",                        /* # of Resource classes (2 chars)            */
   "10","1",                   /* Resource classes (2 char each)             */
   "0",                        /* # Valid resource class combos (2 chars)    */
   /* No combos */             /* Valid resource class combos (2 chars each) */
   "1",                        /* # of connectors  (2 chars)                 */
   "3","","1",                 /* Connectors (2 chars), (17 chars), (2 chars)*/
   "0",                        /* # of extensions (2 chars)                  */
   /* no extension names */    /* Extension names  (3 chars each)            */
   "\0",                       /* Extended attribute (255 chars)             */
   "Digital Video",            /* Alias Name (17 chars)                      */
   "\0"                        /* Device Specific Parameters (255 chars)     */
END

RCDATA 19

This group of parameters indicate:

The number of prompts that should be presented to the user. This number is used to gather configuration-specific information about the user's adapter. The maximum is 10 prompts.

The title of the prompt text as it is displayed to the user.

The number of valid answers to the prompt. The maximum is 25 answers. You supply the valid answers in the next field.

The valid answers to your prompt. These answers are displayed to the user. The user can select one.

The values that are put in your CONFIG.SYS line. These values replace the *VAL* tokens that you placed in your CONFIG.SYS line format previously in this CARDINFO.RC file. These values correspond to the valid answers in the previous field. For example, if the user selects answer number three from the list of valid answers, then value number three is placed into your CONFIG.SYS line. This allows you to ask the user questions in a user-friendly fashion and then place a more cryptic value in the CONFIG.SYS line.

For example, you can ask the user if they want to run a hardware test on startup with the following prompt:

Run hardware test on startup?

The valid answers that you present to the user could be:




Yes

No

The valid values that could be put into the CONFIG.SYS line could be "test" or "notest."

The default answer to the prompt. This is an index into the list of valid answers. For example, if the first answer is the default, specify "1." For an example of how to specify the RCDATA 19 parameters for this example, see Startup Example.

For example, in the CARDINFO.RC file, the Video Blaster adapter is:

RCDATA 19
BEGIN
   // Prompts for the User
   "3",                        /* # Number of prompts to ask user (3 chars)  */
                               /* (max 10 prompts)                           */
   // Prompt 1
   "Frame Buffer Base Address",/* Title of Prompt (max 50 chars)             */
   "8",                        /* # of valid values (2 chars)                */
   "0F00000",                  /* Valid values  (20 chars each)              */
   "0E00000",
   "0D00000",
   "0C00000",
   "0B00000",
   "0A00000",
   "0900000",
   "0800000",
   "1",                        /* Default value - Index into valid values    */
                               /* (2 chars)                                  */

   // Prompt 2
   "Base I/O Address",         /* Title of Prompt (max 50 chars)             */
   "3",                        /* # of valid values (2 chars)                */
   "2AD6",                     /* Valid values (20 chars each)               */
   "2A90",
   "2AF0",
   "1",                        /* Default value - Index into valid values    */
                               /* (2 chars)                                  */

   // Prompt 3
   "Interrupt",                /* Title of Prompt (max 50 chars)             */
   "4",                        /* # of valid values (2 chars)                */
   "I5",
   "I10",                      /* Valid values (20 chars each)               */
   "I11",
   "I12",
   "2"                         /* Default value - Index into valid values    */
                               /* (2 chars)                                  */
END

Startup Example

The following is an example of how to specify RCDATA 19 parameters to ask a user if they want to run a hardware setup test:

RCDATA 19
BEGIN
   // Prompts for the User
   "1",                        /* Number of prompts to ask user (3 chars)    */
                               /* (max 10 prompts).                          */
   // Prompt 1
   "Run hardware test on startup",/* Title of Prompt (max 50 chars).         */
   "2",                        /* Number of valid values (2 chars).          */
   "yes"                       /* Valid values  (20 chars each).             */
   "no"

   "test"                      /* Corresponding CONFIG.SYS values            */
   "notest"                    /* (20 chars each).                           */

   "1",                        /* Default value - Index into valid values    */
                               /* (2 chars).                                 */
END

Step 3. Creating a Video Installation DLL

In some cases, you might want to perform some action that is specific to your adapter, and thus not provided by this generic video installation program. For example, you might want to query the user's hardware setup to determine values, such as interrupt level, rather than prompting the user for those values. In this case, you can create your own DLL to perform these functions.

The video installation program calls your DLL and allows it to return values that can be added to the CONFIG.SYS file. The following steps describe how to use your DLL:

1.Write and compile the DLL.

The entry point to your DLL must accept the following parameters:




CardSpecDLLEntry (USHORT usCardNum,






CHAR   achSpec[5][259])

where:

usCardNum

Is the sequential number of this adapter.

For example, if the user chooses to install two of these adapters, the DLL is called twice. The first time the DLL is called, usCardNum is 1, and the second time the DLL is called, usCardNum is 2.

achSpec[5][259]: Is a two dimensional array that can hold up to five strings of 259 characters each. Your DLL can put values into these five strings. The video installation program then puts these strings into lines in the CONFIG.SYS file as specified in CARDINFO.RC. If there is more than one of these values, they are put into the CONFIG.SYS in sequential order. For example, your DLL fills in the following values:





achSpec[0]="rec"

achSpec[1]="3"

achSpec[2]="11"

achSpec[3]=""

 achSpec[4]=""

The format of your CONFIG.SYS line in CARDINFO.RC is:

DEVICE=*PATH*\\VIDVBC.SYS *SPEC* *SPEC* *SPEC*

The line that is put into CONFIG.SYS is:

DEVICE=D:\MMOS2\VIDVBC.SYS rec 3 11

2.Put the name of the DLL and the name of the DLL's entry point into CARDINFO.RC.

Step 4. Modifying the VIDHELP.ITL File

VIDHELP.ITL is a help file that gives information to the user when the user installs the video adapter. Use this file to describe any prompts that ask the user for information. Be careful when modifying this file, because the basic format of the file must remain the same for the help to work correctly. If you do not prompt the user for any information, then modify only the first section of the file that explains to the user how many adapters can be installed.

Step 5. Running the MAKEFILE

The MAKEFILE compiles CARDINFO.RC into a resource DLL called CARDINFO.DLL. It also compiles VIDHELP.ITL into a help file called VIDHELP.HLP.

Step 6. Modifying the CONTROL.SCR File

Modify the CONTROL.SCR file so that it contains information relevant to your adapter. This file is the main control file used by MINSTALL, MMPM/2's installation program. CONTROL.SCR tells MINSTALL which subsystems and devices that the user can install.

Modify the following fields in the Video Adapter Group:

Note: Do not change the fields not listed here.

ssgroup: Specifies the video adapter group number. The only reason to change this number is if you are installing more than one video adapter. If you install more than one type of adapter, you must duplicate the entire video adapter group and change the group number on the second group. If you add one or more groups, you must increment the group count at the top of this file.
ssname: Specifies the video adapter's name.
ssversion: Specifies the version number of your device driver.
sssize: Specifies the total size (in KB) of your device drivers and the VIDHELP.HLP help file.
ssdllinputparms: Matches the ID number used in CARDINFO.RC.

Step 7. Modifying the VIDFILES.SCR File

Modify the VIDFILES.SCR file so that it lists all the files the adapter uses. VIDFILES.SCR tells MINSTALL which files need to be copied, and into which subdirectories those files should be copied.

After changing the list of files in VIDFILES.SCR, change the "Total Number of Files to Copy" in VIDFILES.SCR to match the number of files you have listed.

Step 8. Creating the Installation Diskette

Create a diskette that contains the following files:

CONTROL.SCR

VIDFILES.SCR

CARDINFO.DLL

VIDHELP.HLP

Your device drivers

Step 9. Using MINSTALL to Install Your Adapter

You can test your installation diskette by running MINSTALL. Before installing the video adapter, you must install:

OS/2 Version 2.1 (or later)

MMPM/2

The files that came with this DDK.

After installing the base MMPM/2, you can install your adapter. The following steps describe how to use MINSTALL:

Place the installation diskette in drive A.
Type MINSTALL.
Change the source drive to A.
Select the adapter.
If errors occur, check the \MMOS2\INSTALL\MINSTALL.LOG file.

Resource Units and Classes

Device contexts are managed by the Media Device Manager (MDM), using an abstract concept of resource units, resource classes, and valid class combinations.

Resource units provide a measurement for the resource manager to determine how many device contexts can be active at any given time. Each device specifies how many resource units it can process concurrently.

In addition to a total resource number, each resource class has a maximum number of resource units available to it. This allows the MDM to determine how many device contexts from a particular class can be active concurrently. During the installation procedure the maximum numbers are provided.

On the MCI_OPEN of a device context the required resource units and class for the device context is returned in the MMDRV_OPEN_PARMS structure. The required resource units and resource class of a device context can be changed by the MCD by calling the MDM with the MCIDRV_CHANGERESOURCE message. For example, if a waveaudio device allocated one resource unit for a mono wave and two units for a stereo wave, then a load command might change the required units for that device context.

The final piece of resource management is provided during installation. This piece is the valid class combinations. A certain device might have multiple classes but might not allow certain classes to have active device contexts concurrently.

For further information on Resource Units and Classes, refer to the OS/2 Multimedia Subsystem Programming Guide.

MMPM/2 Device Driver Reference:Adding Support for Audio and Video Adapters

Contents

Audio Adapter Installation

Source Code

Step 1. Creating an OS/2 Device Driver for an Audio Adapter

Step 2. Writing a Vendor-Specific Driver

Resource File Layout

Step 3. Modifying the CARDINFO.RC File

Songs Example

Step 4. Creating an Audio Installation DLL

Step 5. Modifying the AUDHELP.ITL File

Step 6. Running the MAKEFILE

Step 7. Modifying the CONTROL.SCR File

Step 8. Modifying the AUDFILES.SCR File

Step 9. Creating a MIDI Map

Step 10. Creating the Installation Diskette

Step 11. Using MINSTALL to Install Your Adapter

Video Adapter Installation

Source Code

Step 1. Creating an OS/2 Device Driver

Step 2. Modifying the CARDINFO.RC File

Startup Example

Step 3. Creating a Video Installation DLL

Step 4. Modifying the VIDHELP.ITL File

Step 5. Running the MAKEFILE

Step 6. Modifying the CONTROL.SCR File

Step 7. Modifying the VIDFILES.SCR File

Step 8. Creating the Installation Diskette

Step 9. Using MINSTALL to Install Your Adapter

Resource Units and Classes

Navigation menu

Personal tools

Namespaces

Variants

Views

Actions

Search

Navigation

Tools