Jump to content

MMPM/2 Device Driver Reference: Difference between revisions

From EDM2
← Older editNewer edit →
No edit summary
No edit summary
Line 1,472: Line 1,472:
For further information on Resource Units and Classes, refer to the ''OS/2 Multimedia Subsystem Programming Guide''.
For further information on Resource Units and Classes, refer to the ''OS/2 Multimedia Subsystem Programming Guide''.


=== Audio Physical Device Driver Template ===
This DDK provides two working samples for writing your own audio physical device drivers for the MMPM/2 environment:
*For wave audio/midi, the Turtle Beach "Tropez Plus" device driver. See the document "Object-oriented OS/2 Audio Device Driver Sample" which resides on the DDK Web page for details.
*For wave audio, the IBM-written AD1848 Business Audio device driver.


These samples include all the code required for communication with MMPM/2 - including establishing communication with MMPM/2, controlling specific hardware devices, and establishing inter-device driver (IDC) communications with the MMPM/2 stream handlers and IOCtl-based communications with the MMPM/2 amplifier-mixer (ampmix) and media control drivers (MCDs).
[[MMPM/2 Device Driver Reference:Audio Physical Device Driver Template]]
 
'''Note:''' For further information on when to use a physical device driver (PDD) and how it operates, see the online ''OS/2 Physical Device Driver Reference'' provided in this package. This reference describes the types of physical device drivers, their interfaces, and available system services.
 
=== PDD Architecture ===
The MMPM/2 audio PDD is a standard OS/2 PDD. Audio PDDs have two entry points for communication with the system. The OS/2 device driver standard strategy entry point is used for open/close and setup operations-received from application-level components. Data movement is done via Ring-0 interdevice driver (IDC) interface. These interfaces provide the foundation for sharing of the audio device by MMPM/2 applications and media drivers.
 
The audio IOCtls are standard OS/2 IOCtls. Definitions follow in this chapter. Media drivers running at Ring 3 use the IOCtl interface to set up the audio device sample rate, for access, to change volume controls, and so on. The IOCtl interface is not meant to be used to send audio data to the device driver.
 
The IDC interface is standard 16:16 to 16:16 for procedure calls, initiated by the OS/2 AttachDD DevHlp function. Stream handler device drivers and audio physical device drivers use the IDC interface to communicate with one another to coordinate their efforts to stream data to and from the audio device.
 
The following graphic shows the audio physical device driver architecture. [Artwork not shown]
 
The IDC Interface
 
Two entry points are provided for the two device drivers participating in the IDC interface, [[DDCMDEntryPoint]]and [[SHDEntryPoint]]. [[DDCMDEntryPoint]]allows the stream handler device driver to call to the PDD, and [[SHDEntryPoint]]allows the audio PDD to call to the stream handler.
 
Note that streaming data buffer pointers are passed by the Sync/Stream Manager to the audio stream handler by means of Sync/Stream Manager Helper (SMH) calls. Then the audio stream handler passes pointers to the PDD using device driver command (DDCMD) messages.
 
The following graphic shows the audio physical device driver modules. [Artwork not shown]
 
Communication to the PDD
 
[[DDCMD Messages]]are defined from the [[00155.htm|DDCMDEntryPoint]]. Each message represents a specific request by the stream handler for the audio PDD to perform an action.
 
Read and write messages allow the stream handler to get and receive data directly from the PDD without any intervention required by the application. The application neither has to send data through an IOCtl nor allocate and lock memory to perform data transfers.
 
Communication to the Stream Handler
 
The [[SHDEntryPoint]]contains the following two messages. These messages are located in the SHDD.H file of the \MMOS2\MMTOOLKT\H subdirectory. SHDD.H contains the data structures, their type definitions, and #define statements for certain values. Note that the messages pass pointers to packets of data, to allow maximum flexibility for the future.
 
[[SHD_REPORT_INT]]The PDD uses this message when it needs data at interrupt time. For example, it uses this message to tell the stream handler it has used up all the data and needs more.
 
When the stream handler gets the call, it knows the PDD is passing back a buffer that it might already have consumed. So the stream handler returns on that call, giving the PDD a fresh buffer to consume.
 
[[SHD_REPORT_EVENT]]The stream handler uses this message to keep in sync with PDD activities. For example, the stream handler can request the PDD to report back every tenth of a second that data is played. The stream handler has all the logic to handle these events. The PDD examines the request, and during its checks when it realizes a tenth of a second has been played in data, the PDD calls SHD_REPORT_EVENT. The stream handler can do what it wants at this point, and the PDD returns.
 
The PDD keeps track of the processes. In other words, only the PDD knows how much data, to the millisecond, has been played out to the device. The stream handler can approximate the data played, using calculations based on how much data has gone by. But the stream handler cannot calculate the data played to the millisecond, or even to the fraction of a millisecond, the way the PDD can.
 
Stream Handler Values
 
There are certain values that the stream handler is expecting. For example , when the stream handler requests a stop or a pause on a [[DDCMD_CONTROL]]message, the pointer that comes back to the stream handler is a pointer to the cumulative time that the PDD has recorded in real time. So whenever the stream handler requests the device to stop, the PDD honors that request and informs the stream handler the real time that the PDD stopped within the stream.
 
Another value the stream handler looks for is returned on [[DDCMD_STATUS]]. This is also a pointer to the cumulative time from the PDD, with respect to when that stream was first started at the stream handler's request.
 
PDD Values
 
The stream handler passes a pointer to the PDD on [[DDCMD_STATUS]]. This points to a value used by the PDD for setting the referenced time of the PDD. It is not always correct for the PDD to start its time at 0 every time the stream handler does a start, because the stream handler might have performed a seek in the stream. The PDD might have played a minute of data and then performed a backwards seek to the 30-second mark in the data. If a start is issued, the PDD should start from the 30-second mark in that stream.
 
[[DDCMD_CONTROL]]has an important NOTIFY subfunction, which is used for cuepoint or event detection. The stream handler supports events in cuepoints-an application request to be notified when a particular location in the file is reached or a specific time period has elapsed. The stream handler uses two methods for detecting how much time has elapsed:
 
*Using DDCMD_CONTROL NOTIFY, the stream handler requests to be notified by the PDD at a particular time and passes a pointer to the cue time.
*The stream handler determines the time internally. This method is not as precise as the first method, because only the PDD knows the real time.
 
For example, suppose the stream handler does a DDCMD_CONTROL NOTIFY at one minute. If the PDD supports precise event detection, it must accept this request and put it into a queue somewhere, preferably a linked list. This linked list will have the time of one minute so that during the streaming process, the PDD occasionally checks to see whether it is at the one minute mark. When this event occurs, the PDD calls back on an [[00220.htm|SHD_REPORT_EVENT]]. Then you can free up the event detection linked list node.
 
Keep in mind that the PDD should have the capability to queue these requests because there might be additional requests. For example, an application might request to be notified at the one-minute mark, next at a minute and a half, and possibly every five minutes.
 
If the PDD does not support event detection, then when it gets called on a DDCMD_CONTROL NOTIFY, it responds with an ERROR_INVALID_REQUEST. This response tells the stream handler that it must do the event-detection itself.
 
=== Source Code for the Object-oriented Audio Device Driver ===
Source code for the object-oriented audio device driver, TROPEZ.SYS, which supports the Turtle Beach "Tropez Plus" audio card is located on the DDK Web page. Documentation describing the driver sample can be viewed with a browser at the following Web page:
http://service.boulder.ibm.com/ddk/
Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module.
 
=== Source Code for AD1848 PDD ===
Source code for the AD1848 device driver is located in the \MMOS2\MMTOOLKT\SAMPLES\AD1848 subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module.
 
<pre class="western">/-------------------------------------------------------------\
|Source File              |Description                        |
|-------------------------+-----------------------------------|
|AD1848.C                |This file contains functions that  |
|                        |interface with the Analog Device  |
|                        |stereo codec AD1848.              |
|-------------------------+-----------------------------------|
|AUDCONT.C                |This file contains functions that  |
|                        |support audio control commands from|
|                        |the DosDevIoctl interface to the  |
|                        |device driver.                    |
|-------------------------+-----------------------------------|
|DMA.C                    |This file contains routines that  |
|                        |support DMA services.              |
|-------------------------+-----------------------------------|
|HEADER.C                |This file contains device driver  |
|                        |header information.                |
|-------------------------+-----------------------------------|
|MEM.C                    |This file contains functions      |
|                        |related to dynamic memory          |
|                        |allocation.                        |
|-------------------------+-----------------------------------|
|PARAM.C                  |This file contains routines that  |
|                        |parse parameters from the device  |
|                        |assignment statement in the        |
|                        |config.sys file.                  |
|-------------------------+-----------------------------------|
|PRINTF.C                |This file contains routines to    |
|                        |implement C printf functions for  |
|                        |writing messages to console during |
|                        |initialization and to COM: port    |
|                        |during execution for debugging.    |
|                        |COM: support is ifdefed out of    |
|                        |driver for production builds.      |
|-------------------------+-----------------------------------|
|STRATEGY.C              |This file contain the routine that |
|                        |services the device driver strategy|
|                        |entry point and routines that      |
|                        |support the vdd interface.        |
|-------------------------+-----------------------------------|
|STRING.C                |This file contains miscellaneous  |
|                        |string utility functions.          |
|-------------------------+-----------------------------------|
|STRMCONT.C              |This file contains functions that  |
|                        |service requests from the audio    |
|                        |stream handler and report events to|
|                        |the audio stream handler.          |
|-------------------------+-----------------------------------|
|STRMHELP.C              |This file contains routines that  |
|                        |support stream related services.  |
|-------------------------+-----------------------------------|
|TIMER.C                  |This file contains miscellaneous  |
|                        |time related functions.            |
|-------------------------+-----------------------------------|
|TRACE.C                  |This file contains routines that  |
|                        |support the data logging facility  |
|                        |used for device driver debugging  |
|                        |and performance analysis.          |
|-------------------------+-----------------------------------|
|AUDCONT.H                |This file contains prototypes for  |
|                        |public functions originating in    |
|                        |AUDCONT.C                          |
|-------------------------+-----------------------------------|
|DEVHELP.H                |This file contains prototypes for  |
|                        |public functions in DEVHLP.ASM.    |
|-------------------------+-----------------------------------|
|DEVICE.H                |This file contains definitions for |
|                        |shared constants and prototypes for|
|                        |public functions that originate in |
|                        |DEVICE.C.                          |
|-------------------------+-----------------------------------|
|DMA.H                    |This file contains prototypes for  |
|                        |public functions and definitions  |
|                        |for shared constants originating in|
|                        |DMA.C.                            |
|-------------------------+-----------------------------------|
|ECHO.H                  |This file contains prototypes for  |
|                        |public functions originating in    |
|                        |ECHO                              |
|-------------------------+-----------------------------------|
|END.H                    |This file contains prototypes for  |
|                        |public functions in END.C.        |
|-------------------------+-----------------------------------|
|DEVHLP.ASM              |This file contains routines that  |
|                        |support device driver helper      |
|                        |services from the operating system.|
|-------------------------+-----------------------------------|
|ENTRY.ASM                |This file contains functions that  |
|                        |support all the entry points into  |
|                        |the driver.                        |
|-------------------------+-----------------------------------|
|UTIL.ASM                |This file contains miscellaneous  |
|                        |utility functions for io port data |
|                        |transfer, memory data transfer, and|
|                        |address manipulation.              |
\-------------------------------------------------------------/</pre>
 
=== Data Transfers ===
Following are the two methods of transferring data:
 
Direct Memory Access (DMA) The most efficient way to transfer data from the host system to the audio adapter's memory is through direct memory access ( DMA). This is a technique for moving data directly between main storage without requiring processing of the data by the CPU. To accomplish this, we create a DMA buffer within the device driver to transfer the data. As the device driver receives the stream buffer data, it copies the stream buffer data into the DMA buffer at interrupt time. When the DMA buffer is full, it can be sent directly to the audio device. A preferable (but unproven) method would be to DMA directly from the stream buffer. Currently, however, a copy operation (which requires time and CPU utilization) is required to get data into the AUDIODD DMA buffer.
 
To perform direct memory access, you are essentially programming the DMA microcontroller on the system board. For each direct memory access, you can DMA transfer data up to the limit of the DMA channel that the audio adapter is using:
 
- 64KB for the 8-bit DMA channels 0, 1, and 3
 
- 128KB for the 16-bit DMA channels 5, 6, and 7
 
Note that this DMA transfer must always be from the same buffer pointer. Unless you decide to change the buffer pointer, you would have to reprogram the microcontroller from the beginning.
 
Therefore, if you want to DMA directly from the stream buffer, your device driver would always require a different pointer which means reprogramming the DMA controller at each interrupt. So, each time you get a new buffer from the stream handler, you would have to look at the pointer, reprogram the DMA controller, and then start the DMA transfer. At this stage, most developers state that there is not enough time to reprogram the DMA controller during interrupt time. Therefore, they are creating one DMA buffer when the device driver is initialized at system startup. The developer programs the DMA controller at that point, informs the controller that this is the pointer, and tells it how much data the device driver is going to transfer. The value is set for the lifetime of the driver.
 
Dual DMA Buffers
 
MMPM/2's stream handler implementation uses two DMA buffers or ''dual DMA buffers''to ensure a smooth flow of audio data.
 
In this implementation, the amplifier-mixer (ampmix) device issues a request through the OS/2 kernel to the audio PDD for it to prepare to process audio data. The audio PDD informs the stream handler that it needs the audio data, and the stream handler informs the file system PDD to fill two 4KB DMA buffers with the appropriate audio data.
 
When the audio PDD processes the first 4KB buffer, it issues a hardware interrupt that signals the file system PDD to replace the first 4KB buffer with the next 4KB of audio data. Meanwhile, the audio PDD is processing the second 4KB buffer. When the audio PDD processes the second 4KB buffer, it issues a hardware interrupt again and the process is repeated.
 
With this process, you only have to track two DMA buffers and the stream handler ensures a smooth flow of audio data to the audio PDD. The following illustration provides an overview of this process.
 
<pre class="western">                1st 4KB DMA    2nd 4KB DMA
              /---------------------------\
          /---�|            |            |
          |    |            |            |
          |    \---------------------------/
          |                  �            �
/----------------------\    \---------------The audio PDD
|                      |                    issues hardware
| /-----------------\  |                    interrupts when it
| | Stream Handler  |  |                    finishes processing
| \---- - ------- - ---- /    |                        each  4KB  DMA  block .
|    �    |        |    �      |
|    |    |        |    |      |
|    |    �        �    |      |        The  stream  handler  manages
|  / - - ----- \    / ---- - -- \  |        the  process  of  the  audio
|  | Audio    |    | File    |  |        PDD  processing  4KB  DMA
|  | PDD      |    | System  |  |        blocks  and  the  file  system
|  |        |    | PDD      |  |        PDD  replacing  the  block  as
|  \ ------- /    \ ------- /  |        it  is  processed .
\ ---------- ---------- -- / </pre>
Programmed I/O Programmed I/O involves copying the stream buffer's data directly to the adapter's buffer.
 
=== Stream Descriptions ===
Each physical device driver supports the following:
 
Multiple Opens A PDD must be able to handle multiple open operations. In other words, the OS/2 operating system should be able to open your device driver as many times as necessary. However, resource should only be allocated at the audio initialization stage (IOCtl stage).
 
Multiple Streams A PDD must be able to handle multiple streams. For example, there might be ten multimedia programs on the desktop that have the device open. However, only one program can own the device. For that one program, a stream is created and resources are used. However, if that one program gets put to sleep or the audio is paused, a second program can take its place and use that resource. The Media Device Manager will save pointers to the stream instance that is currently paused, point to the next program, and allow the program to use the resource. At this point, there will be two streams created. If the second program gets initialized, and perhaps paused, the third program will be initialized, and so on.
 
Many streams can be created, however, the program that has focus is the program using the adapter. In addition, a device driver might have ten streams allocated but only one stream will be active at a given time if the hardware supports only one stream. Some hardware can support more than one active stream at a time. For example, the ACPA card can play two mono streams at the same time but only one stereo.
 
Multiple Streams Implementation A stream table is a collection of streams with each stream having different data-similar to a data instance for DLLs. For example, one stream might be set up for recording using specific data rates and buffer pointers, while another stream might be set up for playback of a different data rate and buffer pointers. The two streams are unaffected by each other. The hardware will react to whichever stream is active.
 
A stream table contains the key indexes to determine which stream to make active. The key indexes are ''hStream''and ''ulSysFileNum''. The ''hStream''comes from the stream handler during stream registration while the ''ulSysFileNum''comes from both the DDCMD_REGISTER message and the AUDIO_INIT IOCtl. For example, in the following table, stream #1 has a system file number of 6B and stream #2 has a system file number of 7C. When the AUDIO_INIT IOCtl comes in to start the second instance, the IOCtl requests that you start the stream with the matching ''ulSysFileNum''. Next, across the inter-device driver communications interface, the stream handler will tell you to start stream #2. To start stream #2, search the stream table for a match with system file number #7C. If you find a match, make the stream active. If you do not find a match, the operation fails.
 
<pre class="western">                        IOCtl
                        ulSysFileNum
                          |
                          |
                          �
                hstream  sysfile#  state  data  pData
              /--------------------------------------\
  IDC          |  1    |  6B    |      |    |      |
  hStream      |--------|--------|------|-----|-------|
  ---------�  |  2    |  7C    |      |    |      |
              |--------|--------|------|-----|-------|
              |  3    |  8D    |      |    |      |
              \--------------------------------------/</pre>
 
=== Roadmaps ===
The following figures illustrate the routines and IOCtls included in the audio physical device driver files.
 
=== STARTUP.ASM ===
<pre class="western">                          STARTUP.ASM File
                        /---------------------\
OS/2 IOCtls ----------> |  AUDIODD.C        |
                        |                    |
Stream Handler IDC ---> |  MMDDCMDS.C        |
                        |                    |
VDD IDC --------------> |  AUDIOVDM.C        |
                        |                    |
VDD <----------------  |    CallVDD()        |
                        \---------------------/</pre>
 
=== AUDIODD.C ===
<pre class="western">    AUDIODD.C File
  /------------------------------------------\
  | Strategy.C()                            |
  |  |                                      |
  |  |-> IOCTL_Init()                        |
  |  |-> IOCTL_Invalid()                    |
  |  |-> IOCTL_Read()                        |
  |  |-> IOCTL_NondestructiveRead()          |
  |  |-> IOCTL_ReadStatus()                  |
  |  |-> IOCTL_FlushInput()                  |
  |  |-> IOCTL_Write()                      |
  |  |-> IOCTL_WriteStatus()                |
  |  |-> IOCTL_FlushOutput()                |
  |  |-> IOCTL_Input()                      |
  |  |-> IOCTL_Output()                      |
  |  |-> IOCTL_Open()                        |
  |  |-> IOCTL_Close()                      |
  |  \-> IOCTL_GenIOCTL()                    |
  |            |                            |
  |            |-> Audio_IOCTL_Init()      |
  |            |-> Audio_IOCTL_Status()    |
  |            |-> Audio_IOCTL_Control()    |
  |            |-> Audio_IOCTL_Buffer()    |
  |            |-> Audio_IOCTL_Load()      |
  |            |-> Audio_IOCTL_Wait()      |
  |            \-> Audio_IOCTL_Hpi()        |
  |                                          |
  | InitPos()                                |
  | InitStreams()                            |
  | AllocDMABuffer()                        |
  | ParseArgs()                              |
  \------------------------------------------/</pre>
 
=== MMDDCMDS.C ===
<pre class="western">    MMDDCMDS.C File
  /------------------------------------------\
  | DDCMDInternalEntryPoint()                |
  |  |                                      |
  |  |-� DDCMDSetup()                        |
  |  |-� DDCMDRead()                        |
  |  |-� DDCMDWrite()                        |
  |  |-� DDCMDStatus()                      |
  |  |-� DDCMDControl()                      |
  |  |-� DDCMDRegister()                    |
  |  \-� DDCMDDeRegister()                  |
  |                                          |
  | GetStreamEntry()                        |
  \------------------------------------------/</pre>
=== AUDIOVDM.C ===
<pre class="western">    AUDIOVDM.C File
  /------------------------------------------\
  | PDDInternalEntryPoint()                  |
  |                                          |
  | VDMInterruptTime ()                      |
  |  |                                      |
  |  \-� CallVDD()                          |
  |                                          |
  | VDMClose()                              |
  |  |                                      |
  |  \-� CallVDD()                          |
  \------------------------------------------/</pre>
 
=== AUDINTR.C ===
<pre class="western">    AUDINTR.C File
  /-------------------------------------------------\
  | InterruptHandler()                              |
  |  |                                              |
  |  |-� VDMInterruptTime()                        |
  |  |-� WriteDatatoCard()                          |
  |  |-� SHDEntryPoint() call back to stream handler|
  |  \-� EOI()                                      |
  \-------------------------------------------------/</pre>
 
=== CDEVHLP.ASM ===
 
<pre class="western">    CDEVHLP.ASM File
  /------------------------------\
  | DevHlp_AllocGDTSelector()    |
  | DevHlp_AllocPhys()          |
  | DevHlp_PhysToGDTSelector()  |
  | DevHlp_PhysToVirt()          |
  | DevHlp_VirtToLin()          |
  | DevHlp_ABIOSCall()          |
  | DevHlp_GETLIDEntry()        |
  | DevHlp_FreeLIDEntry()        |
  | DevHlp_RegisterPDD()        |
  | DevHlp_AttachDD()            |
  \------------------------------/</pre>


[[MMPM/2 Device Driver Reference:Audio Virtual Device Driver Template]]
[[MMPM/2 Device Driver Reference:Audio Virtual Device Driver Template]]

Revision as of 21:01, 13 April 2016

By IBM

MMPM/2 Device Driver Reference

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

About This Book

The MMPM/2 Device Driver Reference for OS/2 is for subsystem developers who want to write their own physical device drivers (and associated virtual device drivers) to support audio and video adapters in the Multimedia Presentation Manager/2 system.

Note: Multimedia Presentation Manager/2 (MMPM/2) is also referred to as "OS/2 Multimedia".

The IBM Developer Connection Device Driver Kit for OS/2 (DDK) provides PDD and VDD source code that serves as a template that can be modified easily to meet your hardware requirements. Tools to test your device drivers are also available.

Related Information

You should be familiar with the IBM Developer's Toolkit for OS/2. Related OS/2 and OS/2 multimedia technical information includes:

OS/2 Physical Device Driver Reference Defines what a physical device driver is, and how it operates. It also describes the types of physical device drivers, their interfaces, and available system services.

An online version of this book is provided in this package.

OS/2 Virtual Device Driver Reference Defines what a virtual device driver is, how it operates, and when to use one. It also describes the types of virtual device drivers, their interfaces, and available kernel services.

An online version of this book is provided in this package.

OS/2 Multimedia Technical Library

Online versions of the following books are provided with the OS/2 Developer's Toolkit.

OS/2 Multimedia Subsystem Programming Guide Provides guidelines for developing multimedia subsystems. Each subsystem component is described in detail in individual chapters. Models are used to complement the information provided by component sample program templates.

OS/2 Multimedia Application Programming Guide Provides advisory information on application interfaces to help you select and implement functions for your OS/2 multimedia applications. Code examples from fully documented sample programs accompany the descriptions of the functions.

OS/2 Multimedia Programming Reference Provides detailed information on multimedia functions, messages, and data structures to enable you to write code for your multimedia application programs and subsystems.

Using the Online Reference

Before you begin to use this reference, it would be helpful to understand how you can:

  • Expand the Contents window to see all available topics
  • Obtain additional information for a highlighted word or phrase
  • Use action bar choices

How to Use the Contents

When the Contents window first appears, some topics have a plus (+) sign beside them. The plus sign (+) indicates that additional topics are available.

To expand the Contents if you are using a mouse, click on the plus sign. If you are using a keyboard, use the Up or Down Arrow key to highlight the topic, and press the plus key (+).

To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press Enter).

How to Obtain Additional Information

After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words in the following paragraph are highlighted in green letters. These are called "hypertext terms". If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word and then press Enter. Additional information will appear in a window.

To return to the window you were viewing before you selected a hypertext term, press Esc.

How to Use Action Bar Choices

Several choices are available for managing information presented in the online MMPM/2 Device Driver Reference. There are three pull-down menus on the action bar: the Services menu, the Options menu, and the Help menu.

The actions that are selectable from the Services menu operate in the active window currently displayed on the screen. These actions include the following:

Bookmark Sets a place holder so you can retrieve information of interest to you.

When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty.

To set a bookmark, do the following:

  1. Select a topic from the Contents.
  2. When that topic appears, choose the Bookmark option from the Services menu.
  3. If you want to change the name used for the bookmark, type the new name in the field.
  4. Select the Place radio button (or press the Up or Down Arrow key to select it).
  5. Select OK. The bookmark is then added to the bookmark list.

Search Finds occurrences of a word or phrase in the current topic, selected topics, or all topics.

You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list.

To search for a word or phrase in all topics, do the following:

  1. Choose the Search option from the Services pull-down.
  2. Type the word or words to be searched.
  3. Select All sections.
  4. Select Search to begin the search.
  5. The list of topics where the word or phrase appears is displayed.
Print
Prints one or more topics. You can also print a set of topics by first marking the topics in the Contents list.

You can print one or more topics. You can also print a set of topics by first marking the topics on the Contents list.

To print the document Contents list, do the following:

  1. Select Print from the Services menu.
  2. Select Contents.
  3. Select Print.
  4. The Contents list is printed on your printer.
Copy
Copies a topic you are viewing to a file you can edit.

You can copy a topic you are viewing into a temporary file named "TEXT.TMP". You can later edit that file by using an editor such as the System Editor.

To copy a topic, do the following:

  1. Expand the Contents list and select a topic.
  2. When the topic appears, select Copy to file from the Services menu.

The system copies the text pertaining to that topic into the temporary TEXT.TMP file.

For information on any of the other choices in the Services menu, highlight the choice and press the F1 key.

Options
Changes the way the Contents list is displayed.

You can control the appearance of the Contents list.

To expand the Contents and show all levels for all topics, select Expand all from the Options menu.

For information on any of the other choices in the Options menu, highlight the choice and press the F1 key.

What's New

  • Discussion of and pointers to the PAS16 audio sample have been removed.
  • Pointers to the new object-oriented audio driver sample, TROPEZ.SYS have been included.
  • References to the AUDIOVDD.SYS virtual driver have been removed. The VBSAUDIO.SYS driver serves as its replacement.

For information on any items discussed in this reference that have been added to OS/2 (beginning with Warp) and their compatibility with different versions of OS/2, see OS/2 Version Compatibility Considerations.

Assistance

Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS). You are encouraged to use the DDSC to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.

To access the DDSC BBS, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.

Additional assistance is available through the IBM Solution Developer Program. For membership information:

Internet: ibmsdp@vnet.ibm.com
US/Canada: 800-627-8363
International: 770-835-9902
International Fax: 770-835-9444

Ordering Information

In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, it also includes the following DDK reference books in online format.

  • The Physical Device Driver Reference
  • The Storage Device Driver Reference
  • The Input/Output Device Driver Reference
  • The Pen for OS/2 Device Driver Reference
  • The Virtual Device Driver Reference
  • The Presentation Device Driver Reference
  • The Display Device Driver Reference
  • The Printer Device Driver Reference
  • The Graphics Adapter Device Driver Reference
  • The MMPM/2 Device Driver Reference (Multimedia)

To order the DDK call:

U.S.A.: 1-800-633-8266
Canada: 1-800-561-5293
When calling from Europe, the Middle East, or Africa, the number depends on the language you use to place the order: English (+45) 48101500
French (+45) 48101200
Italian (+45) 48101600
German (+45) 48101000
Spanish (+45) 48101100
Dutch (+45) 48101400
Danish (+45) 48101300
Finish (+45) 48101650
Swedish (+45) 48101150
Norwegian (+45) 48101250
FAX (+45) 48142207
When ordering from Latin America or South America, the number depends on the country from which you are calling: Bolivia 02-35 1840
Columbia 01-257-0111
Dominican Republic 566-5161
El Salvador 02-98 5011
Honduras 32-2319
Paraguay 021-444 094
Urugruay 02-923 617
Chile 02-633-4400
Costa Rica 223-6222
Ecuador 02-56 5100
Guatemala 02-31 5859
Panama 02-639 977
Peru 014-36 6345
Venezuela 02-908-8901
Argentina 01-313-0014
To order from Asia/Pacific: All except Japan (61) 2-354-7684
Japan (81) 3-3495-2045(Fax)
Fax request to: DAP-J, IBM Japan
To order from SE Brazil: (021) 800-6120(Voice)
Brazil: (021) 800-6936(Fax)
To order from Mexico: Mexico City 627-2444
Country 91-800-00639

Adding Support for Audio and Video Adapters

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 following illustration for a video adapter. [Artwork not shown]

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:

  1. 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.

  1. 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.

  1. 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.

  1. 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. 5.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.

  1. 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.
  1. 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.
  1. 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.

  1. 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.

  1. 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.

  1. 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:

[Artwork not shown]

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: 

BEGIN
RCDATA  <Device Number>
<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, 0,

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, 0,

This field must be a USHORT.

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:

1.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.

2.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.

3.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 notlisted 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 uStylefield 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:

  1. Place the installation diskette in drive A.
  2. Type MINSTALLon the OS/2 command line.
  3. Change the source drive to A.
  4. Select the adapter.
  5. 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.

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:

1.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.

2.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.

3.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.

4.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.

5.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.

6.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.

7.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.

8.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.

9.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:

1.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.

2.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.

3.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 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 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:

  1. Place the installation diskette in drive A.
  2. Type MINSTALL.
  3. Change the source drive to A.
  4. Select the adapter.
  5. 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:Audio Physical Device Driver Template

MMPM/2 Device Driver Reference:Audio Virtual Device Driver Template

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

MMPM/2 Device Driver Reference:PDD Sample for Video Capture Adapters

MMPM/2 Device Driver Reference:PDD Sample for MPEG Video Playback Devices

MMPM/2 Device Driver Reference:Audio Sample for Vendor-Specific Drivers

MMPM/2 Device Driver Reference:Using the High-Resolution Timer

MMPM/2 Device Driver Reference:Real-Time MIDI Subsystem

MMPM/2 Device Driver Reference:Audio Device Driver Exerciser (PMADDE) Tool

MMPM/2 Device Driver Reference:AP2/P2STRING Tool

MMPM/2 Device Driver Reference:Ultimotion Data Stream Specification

MMPM/2 Device Driver Reference:DDCMD Messages

MMPM/2 Device Driver Reference:SHD Messages

MMPM/2 Device Driver Reference:Vendor-Specific Driver Commands

MMPM/2 Device Driver Reference:IOCtl Functions

MMPM/2 Device Driver Reference:Data Types

MMPM/2 Device Driver Reference:Types of MIDI Messages

Addendums

OS/2 Version Compatibility Considerations

The following table lists items discussed in this reference that have been added to OS/2 since OS/2 Warp Version 3.0 and discusses their compatibility with different versions of OS/2.

Item Added or Changed Date Item Added or Changed Compatibility of Addition or Change
MIDI Driver November 1995 OS/2 Warp, Version 3.0 and Later
Timer Device Driver November 1995 OS/2 Warp, Version 3.0 and Later
VSD Updates November 1995 OS/2 Warp, Version 3.0 and Later

MMPM/2 Device Driver Reference:Notices

MMPM/2 Device Driver Reference:Glossary

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

Retrieved from "https://www.edm2.com/index.php?title=MMPM/2_Device_Driver_Reference&oldid=26245"