Jump to content

MMPM/2 Device Driver Reference: Difference between revisions

From EDM2
← Older editNewer edit →
No edit summary
No edit summary
Line 3,796: Line 3,796:




=== AP2/P2STRING Tool ===
[[MMPM/2 Device Driver Reference:AP2/P2STRING Tool]]
 
This chapter describes the AP2 and P2STRING tools.
 
 
 
 
 
=== AP2 ===
 
AP2 is the easiest and most complete automated method of testing the audio and video device driver. AP2 provides an easy to use PM interface to the P2STRING tool with a complete set of test scripts for the audio and video device driver. AP2 queries the device driver to determine the functions it supports by using the capability MCI (media control interface) string command. Based on these compatibilities, AP2 will create a list of test scripts that are supported by the default device drivers. You can run any combination of these scripts.
 
The AP2 tool consists of the file AP2.EXE, AP2.HLP, and AP2.INI and P2S_ DESC.TXT. AP2 also requires the P2STRING tool consisting of P2STRING.EXE AND P2S_DLL.DLL. These files are located in the ''IBM Developer Connection Device Driver Kit for OS/2''. The AP2 script files are located in a subdirectory under AP2 called SCRIPTS, and the data files are located in another subdirectory called DATA.
 
AP2 does not require any parameters If AP2 is entered from the command line , AP2 will run, test the device capabilities and display all scripts that can be tested. The file P2S_DESC.TXT file contains the descriptions for all the AP2 test scripts. The results of the capability test are placed in the file CAPABLTY.TXT.
 
The following table shows the parameters that are available for AP2. The AP2 parameters include:
 
<pre class="western">/-------------------------------------------------------------\
|Parameter                |Description                        |
|-------------------------+-----------------------------------|
|[script_file]            |Specifies the script files to be  |
|                        |used. The default is *.P2S.        |
|                        |Wildcards *,? are supported.      |
|-------------------------+-----------------------------------|
|[-AMPMIX]                |Specifies that the Ampmix scripts  |
|                        |will be selected when AP2 is      |
|                        |started. Ampmix scripts are denoted|
|                        |by an 'A' in the first character in|
|                        |the filename.                      |
|-------------------------+-----------------------------------|
|[-CD]                    |Specifies that the CD scripts will |
|                        |be selected when AP2 is started. CD|
|                        |scripts are denoted by a 'C' in the|
|                        |first character in the filename.  |
|-------------------------+-----------------------------------|
|[-CDXA]                  |Specifies that the CDXA scripts    |
|                        |will be selected when AP2 is      |
|                        |started. CDXA scripts are denoted  |
|                        |by an 'X' in the first character in|
|                        |the filename.                      |
|-------------------------+-----------------------------------|
|[-MIDI]                  |Specifies that the MIDI scripts    |
|                        |will be selected when AP2 is      |
|                        |started. MIDI scripts are denoted  |
|                        |by an 'M' in the first character in|
|                        |the filename.                      |
|-------------------------+-----------------------------------|
|[-WAVE]                  |Specifies that the Wave scripts    |
|                        |will be selected when AP2 is      |
|                        |started. Wave scripts are denoted  |
|                        |by a 'W' in the first character in |
|                        |the filename.                      |
|-------------------------+-----------------------------------|
|[-VIDEO]                |Specifies that the Video scripts  |
|                        |will be selected when AP2 is      |
|                        |started. Video scripts are denoted |
|                        |by a 'V' in the first character in |
|                        |the filename.                      |
|-------------------------+-----------------------------------|
|[-MPEG]                  |Specifies that the MPEG scripts    |
|                        |will be selected when AP2 is      |
|                        |started. MPEG scripts are denoted  |
|                        |by &quot;_M&quot; as the first two characters|
|                        |in the filename.                  |
|-------------------------+-----------------------------------|
|[-INTERACTIVE]          |Specifies that the Interactive    |
|                        |scripts will be selected when AP2  |
|                        |is started. An interactive script  |
|                        |requires some form of user input  |
|                        |during the execution of the script.|
|                        |A script is denoted as interactive |
|                        |by an 'I' in the seventh character |
|                        |in the filename.                  |
|-------------------------+-----------------------------------|
|[-ALL]                  |Specifies that all loaded scripts  |
|                        |will be selected.                  |
|-------------------------+-----------------------------------|
|[-BATCH]                |Specifies that testing will be in a|
|                        |batch mode. One or more of the    |
|                        |above selection parameters is      |
|                        |required to specify which scripts  |
|                        |are to be tested. In batch mode AP2|
|                        |will automatically start testing,  |
|                        |log any messages to an output file |
|                        |and terminate when complete. If the|
|                        |interactive switch is used in      |
|                        |conjunction with batch, interactive|
|                        |will be ignored, and no interactive|
|                        |scripts are tested in batch mode.  |
|                        |All output and failed scripts are  |
|                        |logged to an output file. If an    |
|                        |output file is not specified, the  |
|                        |default is AP2.OUT.                |
|-------------------------+-----------------------------------|
|[-oOUT_FILE]            |If this parameter is specified, all|
|                        |scripts that FAIL will also be    |
|                        |logged to this file.              |
|-------------------------+-----------------------------------|
|[-TEST]                  |Specifies that AP2 will            |
|                        |automatically test device          |
|                        |capabilities at startup.          |
|-------------------------+-----------------------------------|
|[-NOTEST]                |Specifies that AP2 will preform no |
|                        |testing of device capabilities at  |
|                        |startup.                          |
|-------------------------+-----------------------------------|
|[-DATAPATH]              |Specifies the data path to be used |
|                        |by AP2. This is the same as        |
|                        |selecting the Data Path button.    |
\-------------------------------------------------------------/</pre>
 
 
 
 
=== Starting and Running AP2 ===
 
When running AP2 for the first time, it is necessary to set the Data Path. The Data Path points to the directory where all the data files for AP2 are located. Every AP2 script that requires a data file uses an environment variable AP2PATH, which is set by AP2.
[Artwork not shown]
The '''Start Test'''button tests the selected scripts. To test scripts, highlight the selected scripts and click on the '''Start Test'''button. After each script is completed, the status for that script is displayed. The output for every script is located in the OUT directory. The output file has the same name as the script with the extension of &quot;OUT&quot;.
 
The '''View Output''' button allows the viewing of the files that are generated from the execution of the *.P2S files. To view the output for a specific script, highlight the script, and click on the '''View Output'''button.
 
The '''Data Path''' button displays a dialog box and allows you to select the location of the AP2 data directory. AP2 will not run correctly if the data path is not set to the directory containing the AP2 data files.
 
 
 
 
 
=== P2STRING ===
 
Use the P2STRING script processing tool to test media control interface string commands in the MMPM/2 environment.
 
The P2STRING tool processes script files (containing string commands and tool directives) to test string commands in your application programs. The P2STRING tool tests your low-level components at the Ring 3 level (as compared to the PMADDE tool, which tests code at the Ring 0 level). P2STRING extracts the strings from the script files and processes the commands through the mciSendString function. Messages and error conditions of the processes included in the scripts are logged to an output file and displayed in windows. P2STRING comes with a set of predefined scripts to test audio and video functions. These tests are a group of test files called ''test suites''. For more information about test suites, see [[00127.htm|Testing Device Drivers]].
 
Each process logs to its own display window, but all processes log to the same output file. In addition, if you close the display window, the string execution thread is immediately destroyed and the entire process ends.
 
<pre class="western"> [Artwork not shown] </pre>
Output messages include all non-comment lines read from the script (for example, script directives, command strings, expected return values, expected and received notify messages, and status lines). In addition, errors and debugging statements of unsuccessful string commands are logged to a file named P2STRING.LOG file.
 
 
 
 
 
=== Setting Font Size and Type ===
 
Before you start the P2STRING tool, you can change the size and type of font displayed in the P2STRING window on the desktop. For example, to specify Times Roman font with a 10 point font size, type:
 
<pre class="western">SET P2STRING_FONTFACE=TIMES
SET P2STRING_FONTSIZE=10</pre>
You can specify either font face, font size, or both. Possible FONTFACE values include SYSTEM, COURIER, TIMES, or HELVETICA (default). Possible FONTSIZE values include 8 (default), 10, 12, 14, or 18.
 
 
 
 
 
=== Starting P2STRING ===
 
The P2STRING tool consists of two files: P2STRING.EXE and P2S_DLL.DLL. These files are located in the ''IBM Developer Connection Device Driver Kit for OS/2''. The following example displays the syntax used to start the P2STRING program. Associated parameters are described in the following table.
 
<pre class="western">P2STRING inp_file [-a]out_file [-eerr_file] [-d|-D] [-E] [-t]</pre>
'''Note:'''The parameters are case sensitive.
 
The following list describes the parameters associated with the P2STRING program.
 
'''Parameter Description'''
 
''script_file''Specifies the script file name you want to process.
 
'''Note:'''Refer to [[00118.htm|P2STRING Script Language]]for information on the contents of a script file and how to interpret the script language.
 
[-a]''out_file''Specifies the output file name containing the results of the test. This file contains only the results of the test you are running, unless you specify the optional -a parameter. For example, to append the output of a script file named SAMPLE.SCR to output currently in a file named MDM.OUT, type:
 
<pre class="western">P2STRING SAMPLE.SCR -aMDM.OUT</pre>
[-e''err_file''] Specifies the optional error file name that receives messages from string commands that completed unsuccessfully. For example, to create an error file named MDM.ERR, type:
 
<pre class="western">P2STRING SAMPLE.SCR MDM.OUT -eMDM.ERR</pre>
[-d|-D] Specifies one of the following optional parameters:
 
<pre class="western">-d    Instructs P2STRING to end after processing a script file.
      Use this parameter when you are running test cases automatically  .
      There is no change in the output.
      When the script file has completed processing, P2STRING prompts
      you with a message requiring you to end the test.
-D    Behaves identically to the -d parameter except that the script
      directives requiring user input are ignored.</pre>
'''Note:'''Refer to [[00120.htm|Tool Directives]]for information on how to add execution directives (which require user input) in a script file.
 
-E Causes the script file to exit after the first error. By default, script files run to completion regardless of errors. For example, the following command ends the processing of SAMPLE.SCR after an error is encountered:
 
<pre class="western">P2STRING SAMPLE.SCR -aMDM.OUT -d -eMDM.ERR -E</pre>
-t Records time stamps for strings and MM_MCIPASSDEVICE notification messages.
 
 
 
 
 
=== P2STRING Script Language ===
 
This section describes the contents of a script file and how to interpret the script language. Script files can contain several types of lines including:
 
�[[00119.htm|Comments]]<br />�[[00120.htm|Tool Directives]]<br />�[[00121.htm|MMPM/2 String Commands]]<br />�[[00122.htm|Expected Return Strings]]<br />�[[00123.htm|Expected Error Messages]]<br />�[[00124.htm|Expected Notification Messages]]
 
The following example displays an example of how a script file appears.
 
<pre class="western">@ PROCESSES = 2
@ EVENTS = { HASCTRL1 = 1 , HASCTRL2 = 0 }
#
#
#
@ PROCESS  1
;
;  set  masteraudio  level  for  session  to  10 %  -  will  affect  all
;  3  processes
;
masteraudio  volume  10
;
;  open  waveaudio  device  non - exclusively
;
open  waveaudio  alias  wav1  shareable  notify
+ MM _ MCINOTIFY  MCI _ NOTIFY _ SUCCESSFUL  MCI _ OPEN  # 1
@ WAIT _ NOTIFY  1  60000
@ WAIT _ PASSDEVICE  wav1  60000
@ WAIT _ NOTIFY  21  60000 </pre>
 
 
 
 
=== Comments ===
 
Script comment lines must start with either a ''semi-colon''(;) or ''comment sign''(#) in the first column. These comment lines are neither displayed nor echoed in the output file. If you want a remark to appear in the output, use the @REM directive.
 
P2STRING allows for a variable number of lines to be displayed in its window. Regular comment lines (header lines) are not displayed nor written to the output file.
 
 
 
 
 
=== Tool Directives ===
 
The P2STRING tool supports either multithreaded or multiprocess execution, but not both. You can use tool directives to test either @PROCESSES or @ THREADS in a script file.
 
Tool directives start with an ''at sign''(@) in the first column. These directives affect the execution and appearance of the output. The following classes of directives are recognized:
 
�Initialization <br />�Execution
 
Initialization Directives
 
Use initialization directives to set up the content of the script file. These directives must appear before execution directives because the tool preprocesses the script file and builds process command buffers.
 
The @THREADS and @PROCESSES directives are mutually exclusive. In other words, the P2STRING tool supports either multithreaded or multiprocess execution in a script file (not both). In addition, there is a limit of 10 processes or threads per script file.
 
The following table lists the supported initialization directives.
 
'''Directive Description'''
 
 
 
<pre class="western">@PROCESSES=x</pre>
Specifies the number (''x'') of processes the script file will be running. For example:
 
<pre class="western">@PROCESSES=2</pre>
 
 
<pre class="western">@THREADS=x</pre>
Specifies the number (''x'') of threads the script file will be running.
 
 
 
<pre class="western">@EVENTS={n[=0|1] [,n[=0|1]]}</pre>
Specifies one or more ''n''ames of events. Events are user-defined with a maximum of 15 characters. Events can be set to 1 or 0. Set an event to 1 for an event that is set with the @SET_EVENT execution directive. Set an event to 0 to clear or reset the event. If no initialization values are specified, the event is initialized to 0. For example:
 
<pre class="western">@EVENTS={brad=1,john=1,test=0}</pre>
 
 
Execution Directives
 
Use execution directives to process the script file. Again, the @THREAD and @PROCESS directives are mutually exclusive.
 
The following table lists the supported execution directives.
 
'''Note:'''Timing out on the @WAIT_EVENT and @WAIT_NOTIFY directives is ''not''considered a failure.
 
'''Directive Description'''
 
 
 
<pre class="western">@THREAD x</pre>
Specifies that the script lines following this directive belong to thread number ''x''until the next @THREAD directive is encountered.
 
 
 
<pre class="western">@PROCESS x</pre>
Specifies that the script lines following this directive belong to process number ''x''until the next @PROCESS directive is encountered.
 
 
 
<pre class="western">@SET_EVENT name 0|1</pre>
Sets the event ''name''to either 1 or 0. Use 1 to mark that the event has happened. Use 0 to clear or reset the event.
 
'''Note:'''The event must be declared through the @EVENTS directive.
 
 
 
<pre class="western">@WAIT_EVENT name [to]</pre>
Waits until the event ''name''is set to 1. @WAIT_EVENT does not cause a change of the event state. If you need a reusable event, use this directive.
 
The timeout (''to'') is specified in milliseconds. If omitted, it defaults to 3 minutes.
 
 
 
<pre class="western">@WAIT_NOTIFY x [to]</pre>
Waits for a specific number (''x'') from an expected MM_ MCINOTIFY notification message. This number must match the index used in the MM_MCINOTIFY reference line. The @WAIT_NOTIFY events are not reusable because there are no events that logically reset it.
 
The timeout (''to'') is specified in milliseconds. If omitted, it defaults to 3 minutes.
 
If the associated mciSendString function fails, the event is posted to prevent delays for notifications that are never going to be sent.
 
 
 
<pre class="western">@WAIT_PASSDEVICE alias [to]</pre>
Waits until the device instance with an alias of ''alias''gains use. This assumes that the alias names used within a script file are unique. The maximum alias name length is 20 characters.
 
'''Note:'''Use a unique alias for every OPEN command.
 
The timeout (''to'') is specified in milliseconds. If omitted, it defaults to 3 minutes.
 
The tool assumes that a unique alias is specified on each OPEN string command. If unique aliases are not used, errors conditions might occur.
 
 
 
<pre class="western">@REM comment</pre>
Echoes the ''comment''to the screen and the output log file. All other script comment lines (those starting with ''';'''or '''#''') are neither transferred nor displayed.
 
 
 
<pre class="western">@PAUSE to</pre>
Pauses processing of the current thread or process in the input script file for the specified time. It does not stop the processing of the notifications or window functions. Other threads or processes are not affected by this directive.
 
 
 
<pre class="western">@BREAK  [ message ] </pre>
Causes a message box to appear with ''message''text. Script processing is halted until the user responds with the correct action . For example:
 
<pre class="western">@BREAK [replace the CD]</pre>
 
 
<pre class="western">@CHECK [message]</pre>
Grades the success of the previous command based on the user's response. A pop-up window displays the ''message''and prompts the user with Yes or No push buttons. The status is passed if the user selects Yes, or failed if No is selected. For example:
 
<pre class="western">@BREAK The music will play for 5 seconds.  Ready to time it?
play cdaudio notify
@PAUSE 5000
@CHECK Did it play?</pre>
 
 
 
 
 
 
=== MMPM/2 String Commands ===
 
All lines that do not fall into any of the other categories are interpreted as MMPM/2 string commands. These lines are passed to the Media Device Manager (MDM) through the mciSendString function after the environment variables have been substituted.
 
Any token in the string command line bracketed by question marks (such as ? FOO?) is interpreted as an environment variable. The actual value of the environment variable is substituted into the string before it is passed to the mciSendString function. If the variable is not found, a warning is issued and the token is replaced with a null string. For example, assuming the environment string MMDATA is set to D:\DATA, open ?mmdata?\temp.wav alias a is equal to open d:\data\temp.wav alias a.
 
 
 
 
 
=== Expected Return Strings ===
 
Many MMPM/2 commands return strings. It is possible to check these strings against an expected value with an expected return string line.
 
An expected return string line has the format:
 
<pre class="western">=result</pre>
The ''equal sign''(=) must be in column 1 and should have no trailing spaces. If an empty string is expected, nothing should follow the = (not even spaces). For example:
 
<pre class="western">status cdaudio ready wait
=TRUE
status cdaudio mode wait
=stopped</pre>
The expected result is always interpreted as a string. This might produce some unusual outputs for commands that return binary data.
 
Where the return is a textual numerical value, it can be matched to a tolerance range of +/-10% using a ''tilde''(~) before the number. This is typically used when the exact value cannot be known. For example:
 
<pre class="western">set foo time format milliseconds wait
play foo notify
@PAUSE 1000
stop foo wait
status foo position wait
=~1000</pre>
Thus, the status command is considered successful if the returned string is in the range 900 - 1100.
 
 
 
 
 
=== Expected Error Messages ===
 
When an MMPM/2 string command is expected to fail with an error, use the expected error line to specify the expected error. The expected error line has the format:
 
<pre class="western">=!error</pre>
The =! must start in column 1. If any error is acceptable, then use the keyword ERROR. If a specific error is expected, type the exact error message after the =!. For example:
 
<pre class="western">open sequencer alias mymidi wait
load mymidi nofile.foo
=!File not found.</pre>
Be careful about extra blanks in the expected-error and expected-result lines. The case of the strings is unimportant; however, the comparison will fail if the spacing or punctuation does not match exactly.
 
 
 
 
 
=== Expected Notification Messages ===
 
Many MMPM/2 string commands cause notification messages to be sent to the P2STRING tool. The system uses notification messages to respond to applications. For example, notification messages indicate system status regarding completion of a media device function or passing of the ownership of a media control device from one process to another.
 
It is possible to verify that the proper notifications are received by using an expected-notify line. Each expected notification line begins with a ''plus sign''(+) in column 1. The following types of notification lines are possible:
 
�Command completion/error notifications <br />�Event notifications <br />�Position change notifications
 
'''Note:'''Any or all notification messages might be expected for a single MMPM /2 string command.
 
Command Completion/Error Notifications
 
A MM_MCINOTIFY line notifies an application when a device successfully completes the action indicated by a media message or when an error occurs.
 
<pre class="western">+MM_MCINOTIFY  notify-code [#x]</pre>
 
 
<pre class="western">/-------------------------------------------------------------\
|Keyword          |Description                              |
|------------------+------------------------------------------|
|notify-code      |Specifies the notification message code,  |
|                  |for example, MCI_NOTIFY_SUCCESSFUL. The  |
|                  |spelling must be the same as the #defines |
|                  |in the OS2ME.H file for the notify codes. |
|------------------+------------------------------------------|
|message          |Specifies the media control interface    |
|                  |message that caused the notification, for |
|                  |example, MCI_PLAY. The spelling must be  |
|                  |the same as the #defines in the OS2ME.H  |
|                  |file for media control interface messages.|
|------------------+------------------------------------------|
|x                |Specifies a unique number (x) used to    |
|                  |associate @WAIT_NOTIFY directives with    |
|                  |particular notifications. This number has |
|                  |nothing to do with the order in which    |
|                  |strings are sent. The number must be      |
|                  |unique and in the range 1-99.            |
\-------------------------------------------------------------/</pre>
Event Notifications
 
A MM_MCIPOSITIONCHANGE line notifies an application of the current media position.
 
<pre class="western">+MM_MCIPOSITIONCHANGE position %user-parameter #x</pre>
 
 
<pre class="western">/-------------------------------------------------------------\
|Keyword          |Description                              |
|------------------+------------------------------------------|
|position          |Specifies the expected MMTIME position of |
|                  |the first position-change message.        |
|------------------+------------------------------------------|
|user-parameter    |Specifies the user parameter to be        |
|                  |returned. This should be the same as the  |
|                  |return value specified in the            |
|                  |SETPOSITIONADVISE string command. Note    |
|                  |that the return value must be a unique    |
|                  |integer in the range of 1 - 99.          |
|------------------+------------------------------------------|
|x                |Specifies the number (x) of position      |
|                  |change messages expected. For further    |
|                  |information, refer to Limitations of      |
|                  |MM_MCIPOSITIONCHANGE Verification.        |
\-------------------------------------------------------------/</pre>
Position Change Notifications
 
A MM_MCICUEPOINT line notifies an application that the playlist processor has encountered a ''message''instruction.
 
<pre class="western">+MM_MCICUEPOINT position %user-parameter</pre>
 
 
<pre class="western">/-------------------------------------------------------------\
|Keyword          |Description                              |
|------------------+------------------------------------------|
|position          |Specifies the expected MMTIME position of |
|                  |the first position-change message.        |
|------------------+------------------------------------------|
|user-parameter    |Specifies the user parameter to be        |
|                  |returned. This should be the same as the  |
|                  |return value specified in the            |
|                  |SETPOSITIONADVISE string command. Note    |
|                  |that the return value must be a unique    |
|                  |integer in the range of 1 - 99.          |
\-------------------------------------------------------------/</pre>
'''Note:'''Other notifications cannot be compared because they do not allow for a ''user-parameter''as part of the message, which is essential for the tracking of related notifications.
 
 
 
 
 
=== Limitations of MM_MCIPOSITIONCHANGE Verification ===
 
There are limitations to what you can verify in the P2STRING tool using event notification lines. The MM_MCIPOSITIONCHANGE line requires the use of the &quot;return ''value''&quot; item in the respective string commands. This line also does not provide for timing start point, for example, playing has started. The P2STRING tool can only count the number of messages received for a specific user parameter (used as a key) and check if subsequent messages have positions approximate to the given expected position interval. The script writer has the responsibility to determine how many POSITIONADVISE messages are expected, taking into account the duration of playing, time format, and start position of the play/record. The reference ''position''given in the expected notification line must be in MMTIME units. If the &quot;expected number of messages&quot; parameter is omitted, the tool verifies only the position interval (not the number). In case of scripts where play, seek, or record are used to cover non-monotonic ranges, the tool might report failures on position-advises because it expects each positionadvise to be in the next position interval from the previous message. If the script makes a jump to a position that does not conform to this, the status will be logged as failed.
 
For example:
 
<pre class="western">setpositionadvise SomeDevice every 10000 on return 5
+MM_MCIPOSITIONCHANGE 10000 %5
play SomeDevice from 35000 to 55000 notify (produces 3 positionchange messages)
seek SomeDevice to 30000 wait
play SomeDevice notify (produces a number of messages starting at 30000)</pre>
The position-change messages are logged as failed, because of the lapse in position interval. A way to handle this situation is to disable the position-change before an explicit position jump is made and enable the same position-advise with a different user parameter.
 
For example:
 
<pre class="western">setpositionadvise SomeDevice every 10000 on return 5
+MM_MCIPOSITIONCHANGE 10000 %5
play SomeDevice from 35000 to 55000 notify (produces 3 positionchange messages)
setpositionadvise SomeDevice every 10000 off
seek SomeDevice to 30000 wait
setpositionadvise SomeDevice every 10000 on return 6
+MM_MCIPOSITIONCHANGE 10000 %6
play SomeDevice notify (produces a number of messages starting at 30000)</pre>
 
 
 
 
=== Processing Logic ===
 
A string command line can be followed by zero to one return value lines, or zero to three notification lines. Note that this is an exclusive OR, meaning that specifying both expected return value and expected notification is not going to give reliable results due to the fact that returned buffer does not become valid prior to the end of the notify message. Also, in case of notify flags, return values are in the procedural interface format rather than in the string interface format.
 
The MDM will not be able to convert return values to strings for commands processed with the notify flag because media control drivers will be sending their notify messages directly to the application.
 
Status of each command is determined in two stages. The first stage is at string execution. If the mciSendString function returns an error and there was no =!ERROR reference line in the script following the command string line, the command is considered failed. If a return value was found after mciSendString is processed, the tool will check for expected return and perform comparison of the two. It they do not match, the command is considered failed. In case of an error that is not in the range understood by the mciGetErrorString function, the command is considered failed even if the !ERROR was encountered.
 
The second stage of the comparison is after a notification is received and after all the commands are issued. If a notification was received and it was successfully compared to the expected notification line, the command is considered successful. If there was no reference notification line, status of the command will not be assigned, unless notify-error was returned. After all the scripts are processed, expected reference notifications will be used to determine if all the notifications were received. The commands that did not receive a notification, and had an expected notification line of the type, are marked failed. Note that command strings are not examined for presence of a notify flag and it is the writer's responsibility to create an expected notify line if it is of importance. In case of expected NOTIFY_SUCCESSFUL messages, all codes other than NOTIFY_ERROR are considered valid. This includes NOTIFY_SUCCESSFUL, NOTIFY_ABORTED and NOTIFY_SUPERSEDED. If any other notify code was specified as expected, and exact match will be checked for. If NOTIFY_ERROR is expected, all errors in the range are verified as passed. There is no facility for verification of an exact error code returned in the notification.
 
 
 
 
 
=== Testing Device Drivers ===
 
Test suites have been provided with this release of the DDK to assist in certifying audio and video device drivers. The test suites provided consist of several test cases. The following sections describe how to:
 
�Set up the environment for running the test suites
 
�Run the test suites
 
�Analyze the test
 
 
 
 
 
=== Setting Up the Environment for Running Test Suites ===
 
Before using the audio or video test suites with the P2STRING tool, do the following:
 
1.Make sure that OS/2 2.1 and the adapter to be tested are installed.
 
2.Update the CONFIG.SYS file.
 
All the test suites use environment variable to determine the location of the input data files. Add the following SET statements to the CONFIG.SYS file.
 
<pre class="western">SET MMDATA=&lt;path&gt;
SET MMDATA-AUD=&lt;path&gt;
SET TESTDATA=&lt;path&gt;</pre>
The path for MMDATA and MMDATA-AUD must specify the path to the audio input files. For example, your .WAV or .MID files. The path for TESTDATA must specify a path to a temporary working directory that you create.
 
The following files must be loaded, and their path must be specified in the CONFIG.SYS file:
 
SETENV.CMD <br />RESETINI.CMD <br />HWCODE.CMD <br />P2STRING.EXE <br />P2S_DLL.DLL
 
3.Shut down and restart your workstation so the CONFIG.SYS parameters will take effect.
 
4.Run HWCODE.CMD for each test suite to be tested.
 
This file is in the ''IBM Developer Connection Device Driver Kit for OS/2''HWCODE.CMD is a REXX command that determines each test case's exact hardware needs and displays the results. The test case's name contains information that HWCODE.CMD uses to make these determinations, so it is important not to change the name of the test case.
 
The syntax for HWCODE.CMD is:
 
<pre class="western">HWCODE &lt;Test Case Name&gt;</pre>
'''Note:'''The Test Case Name must include the file name extension. HWCODE.CMD displays the brand and model of audio and video adapters currently supported by OS/2 2.1. The adapter being tested is not listed if it is new , but this information is useful for comparing results based on expected compatibility with other manufactures.
 
HWCODE.CMD also displays audio and video hardware codes.
 
 
 
 
 
=== Hardware Codes ===
 
The hardware codes are two digit codes. The hyphen (-) in the tables indicate the position of the unspecified digit in the code. For example, if you receive the hardware code 84, you would look in the 8- column and the - 4 column to decipher the hardware code.
 
Audio Hardware Codes
 
'''Audio Capture Playback Adapters'''
 
 
 
<pre class="western">/--------------------------------------------------------------\
|Hardware Code      |ACPA                |Number of Cards    |
|                    |                    |Unspecified        |
|--------------------+--------------------+--------------------|
|0-                  |                    |                    |
|--------------------+--------------------+--------------------|
|1-                  |1                  |                    |
|--------------------+--------------------+--------------------|
|2-                  |2                  |                    |
|--------------------+--------------------+--------------------|
|3-                  |3                  |                    |
|--------------------+--------------------+--------------------|
|8-                  |                    |1                  |
|--------------------+--------------------+--------------------|
|9-                  |1                  |1                  |
|--------------------+--------------------+--------------------|
|A-                  |2                  |1                  |
|--------------------+--------------------+--------------------|
|B-                  |3                  |1                  |
|--------------------+--------------------+--------------------|
|G-                  |                    |2                  |
|--------------------+--------------------+--------------------|
|H-                  |1                  |2                  |
|--------------------+--------------------+--------------------|
|I-                  |2                  |2                  |
|--------------------+--------------------+--------------------|
|J-                  |3                  |2                  |
|--------------------+--------------------+--------------------|
|O-                  |                    |3                  |
|--------------------+--------------------+--------------------|
|P-                  |1                  |3                  |
|--------------------+--------------------+--------------------|
|Q-                  |1                  |3                  |
|--------------------+--------------------+--------------------|
|R-                  |3                  |3                  |
\--------------------------------------------------------------/</pre>
'''OEM'''
 
<pre class="western">/--------------------------------------------------------------\
|Hardware Code      |OEM                |Number of CDROMs    |
|--------------------+--------------------+--------------------|
|-0                  |                    |                    |
|--------------------+--------------------+--------------------|
|-1                  |OPL0 (original Sound|                    |
|                    |Blaster chipset)    |                    |
|--------------------+--------------------+--------------------|
|-4                  |Sound Blaster 16    |                    |
|--------------------+--------------------+--------------------|
|-5                  |ProAudio Spectrum 16|                    |
|--------------------+--------------------+--------------------|
|-6                  |Sound Blaster Pro  |                    |
|--------------------+--------------------+--------------------|
|-7                  |Any Sound Blaster  |                    |
|--------------------+--------------------+--------------------|
|-8                  |                    |1                  |
|--------------------+--------------------+--------------------|
|-9                  |OPL0 (original Sound|1                  |
|                    |Blaster chipset)    |                    |
|--------------------+--------------------+--------------------|
|-C                  |Sound Blaster 16    |1                  |
|--------------------+--------------------+--------------------|
|-D                  |ProAudio Spectrum 16|1                  |
|--------------------+--------------------+--------------------|
|-E                  |Sound Blaster Pro  |1                  |
|--------------------+--------------------+--------------------|
|-F                  |Any Sound Blaster  |1                  |
|--------------------+--------------------+--------------------|
|-G                  |                    |2                  |
|--------------------+--------------------+--------------------|
|-H                  |OPL0                |2                  |
|--------------------+--------------------+--------------------|
|-K                  |Sound Blaster 16    |2                  |
|--------------------+--------------------+--------------------|
|-L                  |ProAudio Spectrum 16|2                  |
|--------------------+--------------------+--------------------|
|-M                  |Sound Blaster Pro  |2                  |
|--------------------+--------------------+--------------------|
|-N                  |Any SB              |2                  |
|--------------------+--------------------+--------------------|
|-O                  |                    |3                  |
|--------------------+--------------------+--------------------|
|-P                  |OPL0 (original Sound|3                  |
|                    |Blaster chipset)    |                    |
|--------------------+--------------------+--------------------|
|-S                  |Sound Blaster 16    |3                  |
|--------------------+--------------------+--------------------|
|-T                  |ProAudio Spectrum 16|3                  |
|--------------------+--------------------+--------------------|
|-U                  |Sound Blaster Pro  |3                  |
|--------------------+--------------------+--------------------|
|-V                  |Any SB              |3                  |
\--------------------------------------------------------------/</pre>
'''Special Hardware Needs'''
 
<pre class="western">/-------------------------------------------------------------\
|Hardware Code      |Special Hardware Needs                  |
|--------------------+----------------------------------------|
|W0                  |Pioneer laser disc V80000              |
|--------------------+----------------------------------------|
|W1                  |Pioneer laser disc V4400                |
|--------------------+----------------------------------------|
|W2                  |Pioneer laser disc V4200                |
|--------------------+----------------------------------------|
|W3                  |Pioneer laser disc V4300D              |
\-------------------------------------------------------------/</pre>
Video Hardware Codes
 
'''VCA'''
 
 
 
<pre class="western">/--------------------------------------------------------------\
|Hardware Code      |VCA                |Number of Cards    |
|                    |                    |Unspecified        |
|--------------------+--------------------+--------------------|
|4-                  |                    |                    |
|--------------------+--------------------+--------------------|
|5-                  |1                  |                    |
|--------------------+--------------------+--------------------|
|6-                  |2                  |                    |
|--------------------+--------------------+--------------------|
|C-                  |                    |1                  |
|--------------------+--------------------+--------------------|
|D-                  |1                  |1                  |
|--------------------+--------------------+--------------------|
|E-                  |2                  |1                  |
|--------------------+--------------------+--------------------|
|K-                  |                    |2                  |
|--------------------+--------------------+--------------------|
|L-                  |1                  |2                  |
|--------------------+--------------------+--------------------|
|M-                  |2                  |2                  |
\--------------------------------------------------------------/</pre>
'''OEM'''
 
 
 
<pre class="western">/--------------------------------------------------------------\
|Hardware Code      |OEM                |Number of CDROMs    |
|--------------------+--------------------+--------------------|
|-0                  |Any video capture  |                    |
|                    |card                |                    |
|--------------------+--------------------+--------------------|
|-1                  |Any video capture  |                    |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
|--------------------+--------------------+--------------------|
|-2                  |Any video capture  |                    |
|                    |card and a ProAudio |                    |
|                    |Spectrum 16        |                    |
|--------------------+--------------------+--------------------|
|-8                  |Any video capture  |1                  |
|                    |card                |                    |
|--------------------+--------------------+--------------------|
|-9                  |Any video capture  |1                  |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
|--------------------+--------------------+--------------------|
|-A                  |Any video capture  |1                  |
|                    |card and a ProAudio |                    |
|                    |Spectrum 16        |                    |
|--------------------+--------------------+--------------------|
|-G                  |Any video capture  |2                  |
|                    |card                |                    |
|--------------------+--------------------+--------------------|
|-H                  |Any video capture  |2                  |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
|--------------------+--------------------+--------------------|
|-I                  |Any video capture  |2                  |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
\--------------------------------------------------------------/</pre>
'''Special Hardware Needs'''
 
 
 
<pre class="western">/-------------------------------------------------------------\
|Hardware Code      |Special Hardware Needs                  |
|--------------------+----------------------------------------|
|X0                  |IBM VCA NTSC                            |
|--------------------+----------------------------------------|
|X1                  |Jovian SuperVia NTSC                    |
|--------------------+----------------------------------------|
|X2                  |Jovian QuickVia NTSC                    |
|--------------------+----------------------------------------|
|X3                  |Video Blaster NTSC                      |
|--------------------+----------------------------------------|
|X4                  |IBM VCA  PAL                            |
|--------------------+----------------------------------------|
|X5                  |Jovian SuperVia  PAL                    |
|--------------------+----------------------------------------|
|X6                  |Jovian QuickVia  PAL (WinMovie)        |
|--------------------+----------------------------------------|
|X7                  |Video Blaster PAL                      |
\-------------------------------------------------------------/</pre>
 
 
 
 
=== Running the Test Suites ===
 
The suites are run using P2STRING. For more information about P2STRING, see [[00112.htm|AP2/P2STRING Tool]].
 
To run a device test, do the following:
 
1.Open an OS/2 window.
 
2.Run SETENV.CMD.
 
'''Note:'''Nothing is displayed when running this command. When the OS/2 command prompt is displayed again, this command is finished.
 
This file is in the ''IBM Developer Connection Device Driver Kit for OS/2''. This command should be run prior to running the first test (each time you open an OS/2 window) because it sets up the audio devices correctly. To run this command, type:
 
<pre class="western">SETENV</pre>
3.Run RESETINI.CMD prior to each test.
 
'''Note:'''Nothing is displayed when running this command. When the OS/2 command prompt is displayed again, this command is finished.
 
This file is in the ''IBM Developer Connection Device Driver Kit for OS/2''. This command resets system connections in the appropriate INI files for audio and video tests to their defaults. To run this command, type:
 
<pre class="western">RESETINI</pre>
4.Run each test. Each test can be run from the command line and the output is saved in a file for analysis. The P2STRING syntax is:
 
<pre class="western">P2STRING inp_file [-a]out_file [-eerr_file] [-d|-D] [-E] [-t]</pre>
 
 
For more information about running tests from the command line, see [[00117.htm|Starting P2STRING]].
 
The tests display messages in a message box and might not automatically close the message box when the test finishes. If the test does not close the message box, you need to manually close it. The message box is not closed if P2STRING is waiting for a return value that might or might not be returned. The test has finished processing if the string &quot;Script completed successfully&quot; is displayed at the bottom of the message box. Allow approximately one minute after this message is displayed before manually closing the message box to allow for any late return codes.
 
'''Note:'''The &quot;Script completed successfully&quot; message does not indicate that all the tests passed. It only indicated the script has finished processing .
 
 
 
 
 
=== Analyzing a Device Driver Test ===
 
After an audio or video test is run, the results of the test are stored in a file with a .IND extension appended to the file name. The media control interface strings that passed are flagged with a PASSED keyword in the return string, and failed strings are flagged with a FAILED keyword.
 
Those that are flagged as FAILED can be analyzed further. When all strings are passed successfully, the device driver is handling all conditions specified by the test correctly.
 
'''Note:'''If a string command is supposed to fail and does, the return string is considered PASSED, because the return string matches the expected results.
 
The following example illustrates how to compare the results file with the test script.
 
<pre class="western">  TEST SCRIPT  (AUDIO1.P80)
 
 
        ############################################
        #                                          #
        #  OPEN THE MIDIPLAYER                    #
        #  WAIT FOR SUCCESSFUL OPEN              #
        #                                          #
        ############################################
        #
/---&gt;  open sequencer alias midiplayer notify
|/--&gt;  +MM_MCINOTIFY MCI_NOTIFY_SUCCESSFUL MCI_OPEN #1
||      @WAIT_NOTIFY 1 45000
||      @WAIT_PASSDEVICE midiplayer
||      ############################################
||      #                                          #
||      #  LOAD AND CUE TYPE1. MID FILE          #
||      #  PLAY jesu.mid  FILE AND EXPECT AN      #
||      #  ABORT FROM A PAUSE                    #
||      #                                          #
||      ############################################
||      #
||  /-&gt; load midiplayer ?MMDATA-AUD?\jesu.mid  wait
||  |  cue midiplayer output wait
||  |  play midiplayer from 100 to 60000 notify
||  |  +MM_MCINOTIFY MCI_NOTIFY_ABORTED MCI_PLAY
||  |  #
||  |
||  |
||  |                TEST OUTPUT FILE (AUDIO1.LOG)
||  |
||  |
||  |          ****************Opening script file
||  |
||  |
||  |          Thread 1 executing 21 commands.
\|--|--------&gt; T:1 send string #  1 open sequencer alias midiplayer notify
  \--|--------&gt; EXPECTED NOTIFY FOR #1: MM_MCINOTIFY SUCCESSFUL by MCI_OPEN script param= 1
    |    |--&gt; T:1 Notify received for #  1 MM_MCINOTIFY SUCCESSFUL by command MCI_OPEN ID 1
    |    \--&gt; NOTIFY STATUS FOR #1: PASSED
    |          T:1 Notify received MM_MCIPASSDEVICE MCI_GAINING_USE Device ID 1
    |          returned string for #  1: 1
    |          T:1 @WAIT_NOTIFY 1 45000
    |          T:1 @WAIT_PASSDEVICE MIDIPLAYER
    \--------&gt; T:1 send string #  2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid  wait
          |--&gt;  no returned string for #  2.
          \--&gt; NOTIFY STATUS FOR #2: FAILED
                  .
                  .
                  .
 
                END OF SCRIPT FILE REACHED. 14 COMMANDS SENT
 
                Waiting for late notifications for 30 sec
                T:1 Notify received for # 14 MM_MCINOTIFY SUCCESSFUL by command MCI_CLOSE ID 1
                NOTIFY STATUS FOR #14: PASSED
 
                Script completed successfully</pre>
The first command &quot;open sequencer alias midiplayer notify&quot; in the test expects the following results:
 
<pre class="western">+MM_MCINOTIFY MCI_NOTIFY_ABORTED MCI_PLAY</pre>
Following the first and second line down in the previous example, you can see that this command passed successfully:
 
<pre class="western">EXPECTED NOTIFY FOR #1: MM_MCINOTIFY SUCCESSFUL by MCI_OPEN script param= 1
T:1 Notify received for #  1 MM_MCINOTIFY SUCCESSFUL by command MCI_OPEN ID 1
NOTIFY STATUS FOR #1: PASSED</pre>
The following lines in the test script are not expecting returned information:
 
<pre class="western">@WAIT_NOTIFY 1 45000
@WAIT_PASSDEVICE midiplayer</pre>
Therefore, the test output echoes these commands to show they were received .
 
<pre class="western">T:1 @WAIT_NOTIFY 1 45000
T:1 @WAIT_PASSDEVICE MIDIPLAYER</pre>
However, the &quot;load midiplayer ?MMDATA-AUD?\jesu.mid wait&quot; command did not receive the expected message, and the following is logged to the test file:
 
<pre class="western">T:1 send string #  2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid  wait
no returned string for #  2.
NOTIFY STATUS FOR #2: FAILED</pre>
The bottom of the test output file indicates how many commands were processed, it also indicates if it is waiting for late notifications. Depending on the test, and the devices being tested, expected notifications might not always arrive on time or in the order expected. If a notification does not arrive when expected, it can arrive later if the device driver has not failed.
 
This is especially important on multi-threaded or multi-process processing. The more complicated the test (for example stress testing the device driver with multiple devices), the more difficult it is to decipher the output file. You will have to keep track of each thread or process separately to determine the results of the test.


[[MMPM/2 Device Driver Reference:Ultimotion Data Stream Specification]]
[[MMPM/2 Device Driver Reference:Ultimotion Data Stream Specification]]

Revision as of 00:21, 8 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
 01-257-0111 * Dominican Republic | 566-5161 * El Salvador | 02-98 5011 * Honduras | 32-2319 * Paraguay | 021-444 094 * Urugruay | 02-923 617 02-633-4400 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
* All except Japan |(61) 2-354-7684 * Japan |(81) 3-3495-2045(Fax) |Fax request to: |DAP-J, IBM Japan
(021) 800-6120(Voice)| (021) 800-6936(Fax) |
* 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 Installationor 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.

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

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

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

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

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

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

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

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

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

This field must be a USHORT.

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 units supported by this driver. For more information, see Resource Units and Classes.

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

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

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

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

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


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

For more information, see Resource Units and Classes.

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

�The connectors. Each connector has three values:

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

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

-Sequential number of the connector to which it connects.

The sample CARDINFO.RC file uses:

"3","","1"

where:

3 Indicates the wave stream connector.

"" Indicates the default WaveAudio device.

1 Indicates the first connector of the WaveAudio device.

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

�The file-name extensions associated with this driver.

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

"AVI", "AVS"

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

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

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

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

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

RCDATA 19 This group of parameters indicate:

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

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

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

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

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

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

Run hardware test on startup?

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

Yes
No

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

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

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

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

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

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




Startup Example

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

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

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

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

Step 3. Creating a Video Installation DLL

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

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

1.Write and compile the DLL.

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

CardSpecDLLEntry (USHORT usCardNum,
                  CHAR   achSpec[5][259])

where:

usCardNum Is the sequential number of this adapter.

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

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

achSpec[0]="rec"
achSpec[1]="3"
achSpec[2]="11"
achSpec[3]=""
achSpec[4]=""

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

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

The line that is put into CONFIG.SYS is:

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

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



Step 4. Modifying the VIDHELP.ITL File

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



Step 5. Running the MAKEFILE

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



Step 6. Modifying the CONTROL.SCR File

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

Modify the following fields in the Video Adapter Group:

Note:Do not change the fields not listed here.

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

ssname Specifies the video adapter's name.

ssversion Specifies the version number of your device driver.

sssize Specifies the total size (in KB) of your device drivers and the VIDHELP.HLP help file.

ssdllinputparms Matches the ID number used in CARDINFO.RC.



Step 7. Modifying the VIDFILES.SCR File

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

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



Step 8. Creating the Installation Diskette

Create a diskette that contains the following files:

�CONTROL.SCR
�VIDFILES.SCR
�CARDINFO.DLL
�VIDHELP.HLP
�Your device drivers



Step 9. Using MINSTALL to Install Your Adapter

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

�OS/2 Version 2.1 (or later)

�MMPM/2

�The files that came with this DDK.

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

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



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

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 Referenceprovided 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, DDCMDEntryPointand SHDEntryPoint. DDCMDEntryPointallows the stream handler device driver to call to the PDD, and SHDEntryPointallows 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 Messagesare defined from the 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 SHDEntryPointcontains 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_INTThe 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_EVENTThe 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_CONTROLmessage, 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_CONTROLhas 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 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. 

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



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

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

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 hStreamand ulSysFileNum. The hStreamcomes from the stream handler during stream registration while the ulSysFileNumcomes 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. 

                        IOCtl
                        ulSysFileNum
                           |
                           |
                           �
                hstream  sysfile#  state  data  pData
               /--------------------------------------\
  IDC          |   1    |  6B    |      |     |       |
  hStream      |--------|--------|------|-----|-------|
  ---------�   |   2    |  7C    |      |     |       |
               |--------|--------|------|-----|-------|
               |   3    |  8D    |      |     |       |
               \--------------------------------------/




Roadmaps

The following figures illustrate the routines and IOCtls included in the audio physical device driver files.



STARTUP.ASM

                           STARTUP.ASM File
                        /---------------------\
OS/2 IOCtls ----------� |   AUDIODD.C         |
                        |                     |
Stream Handler IDC ---� |   MMDDCMDS.C        |
                        |                     |
VDD IDC --------------� |   AUDIOVDM.C        |
                        |                     |
VDD �----------------   |    CallVDD()        |
                        \---------------------/



AUDIODD.C

    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()                              |
   \------------------------------------------/



MMDDCMDS.C

    MMDDCMDS.C File
   /------------------------------------------\
   | DDCMDInternalEntryPoint()                |
   |  |                                       |
   |  |-� DDCMDSetup()                        |
   |  |-� DDCMDRead()                         |
   |  |-� DDCMDWrite()                        |
   |  |-� DDCMDStatus()                       |
   |  |-� DDCMDControl()                      |
   |  |-� DDCMDRegister()                     |
   |  \-� DDCMDDeRegister()                   |
   |                                          |
   | GetStreamEntry()                         |
   \------------------------------------------/



AUDIOVDM.C

    AUDIOVDM.C File
   /------------------------------------------\
   | PDDInternalEntryPoint()                  |
   |                                          |
   | VDMInterruptTime ()                      |
   |  |                                       |
   |  \-� CallVDD()                           |
   |                                          |
   | VDMClose()                               |
   |  |                                       |
   |  \-� CallVDD()                           |
   \------------------------------------------/



AUDINTR.C

    AUDINTR.C File
   /-------------------------------------------------\
   | InterruptHandler()                              |
   |  |                                              |
   |  |-� VDMInterruptTime()                         |
   |  |-� WriteDatatoCard()                          |
   |  |-� SHDEntryPoint() call back to stream handler|
   |  \-� EOI()                                      |
   \-------------------------------------------------/



CDEVHLP.ASM

    CDEVHLP.ASM File
   /------------------------------\
   | DevHlp_AllocGDTSelector()    |
   | DevHlp_AllocPhys()           |
   | DevHlp_PhysToGDTSelector()   |
   | DevHlp_PhysToVirt()          |
   | DevHlp_VirtToLin()           |
   | DevHlp_ABIOSCall()           |
   | DevHlp_GETLIDEntry()         |
   | DevHlp_FreeLIDEntry()        |
   | DevHlp_RegisterPDD()         |
   | DevHlp_AttachDD()            |
   \------------------------------/



Audio Virtual Device Driver Template

The IBM Developer Connection Device Driver Kit for OS/2includes full source for the MMPM/2 provided Virtual Device Driver, VBSAUDIO.SYS. Use VBSAUDIO.SYS to serialize DOS application access to audio hardware in the MMPM/2 environment. This VDD can communicate with multiple audio PDDs through the Inter-Device Driver Communication (IDC) Interface. However, where the services of VBSAUDIO.SYS are not sufficient, you can modify the audio VDD template to meet your device driver requirements.

You can code your Physical Device Driver to meet the interfaces of VBSAUDIO .SYS as an initial step toward virtualization. You can expand this functionality by copying and changing VBSAUDIO.SYS to take advantage of your hardware and private interfaces which can be established between the VDD and DOS or WIN-OS/2 audio device drivers.

Note:For further information on when to use a VDD and how it operates, see the online OS/2 Virtual Device Driver Referenceprovided in this package. This reference describes the types of virtual device drivers, their interfaces, and available kernel services.



Source Code

The VDD template is written using Watcom C and linked with the 32-bit OS/2 linker. Source code for the audio VDD sample is located in the \DDK\BASE\ SRC\VDEV\MME\VBSAUDIO subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines incorporated within the module.



VDD Architecture

The VBSAUDIO.SYS virtual device driver is a Ring 0, 32-bit device driver responsible for controlling multiple virtual DOS sessions. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely.

VDD architecture usually calls for a device driver pair: a PDD and VDD working together to serialize and control a common piece of hardware, called shared hardware. The PDD controls access to the hardware and OS/2 sessions; the VDD controls DOS sessions and communicates with the PDD to serialize access. That is, the PDD and VDD communicate to make sure DOS sessions and OS/2 sessions cannot concurrently access the shared hardware.

Without a VDD, DOS sessions have complete access to system hardware. Most DOS visible hardware resources are controlled by system VDDs, preventing DOS sessions from interfering with each other and protecting OS/2 applications from DOS sessions.

When a PDD exists with no VDD, the hardware device is visible to the OS/2 side (through the PDD) and to all DOS sessions (through the VDM Manager). This presents an opportunity for DOS sessions to take control of a hardware resource owned by an OS/2 PDD. Writing a virtual device driver corrects this situation, resulting in system-wide protected access to the hardware resource.

This PDD-VDD pair usually results in a VDD (like a PDD) being written to the specifications of a specific hardware device. VBSAUDIO.SYS supports multiple adapters by using a protocol for PDD-VDD communication where the PDD defines the characteristics of its device at system startup. [Artwork not shown]

The key to supporting multiple PDDs is communication at system startup to attain a description of the physical characteristics of each adapter. PDDs are loaded and initialized prior to VDDs. When the PDD loads, it registers itself as willing to communicate with VDDs by providing its IDC name and entry point for this communication. When the VDD loads, it calls a Virtual DevHlp service (VDHOpenPDD) to resolve the IDC entry point of the PDD. On this call, the operating system calls the PDD to deliver the VDD IDC entry point. When the PDD and VDD exchange entry points, the drivers are free to communicate through whatever private protocol is chosen including exchanging register-based entry points.

For these calls to function, the VDD must know the name by which the PDD registered. In a non-generic implementation, this is not a problem as the two device drivers can refer to the name from a common include file. This "generic" VDD takes the PDD names as DEVICE=VBSAUDIO.SYS parameters on the CONFIG.SYS statement.

In the case where a single PDD supports multiple devices, the PDD should register its IDC name and entry point (specifying the name on the DEVICE= VBSAUDIO.SYS statement). During initialization, the VDD calls the PDD to establish communication and to query the hardware resources that the PDD controls. The VDD will use this information to trap DOS session attempts to access the adapter. When a DOS session takes control of a PDD-owned resource, the VDD traps the DOS session pending permission to use the hardware. As the PDD controls access, the VDD queries the PDD for permission to use the hardware. If permission is granted, the VDD disables further traps and allows the DOS session to continue uninterrupted. Traps are disabled to give maximum performance. Because the VDD does not keep track of port accesses (and does not know the details of supported adapters ), it is unable to remember the state of the adapter. That is, as soon as a DOS session owns the hardware, ownership cannot be relinquished and restored, because the VDD does not know how to restore the state of the device. The VDD supports serialization (not virtualization).

If access is denied by the PDD, or if another DOS session already owns the hardware, a pop-up message is displayed asking the user for direction. The user can give instruction to terminate the session, suspend the session, or pretend the hardware does not exist. Based on this response, the VDD executes Virtual DevHlp services to perform the necessary actions. Semaphores are used to block DOS session execution when they are suspended awaiting access to hardware. When the last DOS session releases the hardware, the VDD returns hardware ownership to the PDD.

Note:See VDD Operationsfor further information.



VDD Operations

When writing a PDD to control physical hardware, it is common to write a VDD to provide serialization with DOS sessions. Without a VDD, DOS sessions have complete access to system resources. That is, if an adapter has only a PDD, DOS sessions can directly access the adapter resulting in unpredictable consequences.

When DOS sessions are created, the VDD installs hooks for the indicated port ranges. On first access, the DOS session is said to be "requesting hardware access." By convention, the PDD controls hardware access. To gain use, the VDD must ask the PDD for permission to use the hardware. When granted, the DOS session traps are removed and the session is allowed to continue executing. At interrupt time, the PDD calls the VDD IDC entry point where the VDD virtualizes the hardware interrupt for the owning session.

Subsequent DOS session access attempts are denied pending hardware availability. A hard error pop-up window is displayed giving the user three options:

�End - Terminate the DOS session
�Retry - Block until hardware becomes free
�Ignore - Instruct the VDD to ignore the adapter

If retry is chosen, the DOS session is blocked until the hardware becomes available. When the DOS session in use releases the hardware, the next DOS session gains access. This process continues until no more devices are waiting at which point the VDD relinquishes ownership to the PDD.

If ignore is chosen, the DOS session continues execution but with no visibility to the protected adapter. This allows sound-enabled DOS applications to execute under the impression that the system does not have an audio card installed.

For access queues, the PDD uses semaphores and the OS/2 scheduler. The VDD maintains no queues. Instead, 1 mutex and 1 event semaphore are used to control access. Only one DOS session can own the hardware at any one time. When the VDD owns the hardware, the DOS session owning the mutex semaphore is allowed to execute. All others are blocked pending hardware availability. When the owning session releases the hardware (the semaphore ), the OS/2 semaphore routines and scheduler determine which session next gains access.

A DOS session can also be denied access due to OS/2 PDD refusal to relinquish ownership. This would be the case when an OS/2 application is using the services of the PDD before a DOS session attempts access. Here, all pending DOS sessions are queued waiting on an event semaphore. When the OS/2 PDD relinquishes hardware, all blocked sessions are allowed to run by posting the event semaphore. The sessions compete for ownership of the mutex semaphore. One session wins, the others block; serialization is maintained.



Inter-Device Driver Communication (IDC) Interface

Virtual device drivers (VDDs) communicate with physical device drivers ( PDDs) through the inter-device driver communication (IDC) interface provided with the OS/2 operating system. The drivers exchange the address of an entry point and call each other through the exchanged addresses. A VDD communicates with a PDD directly through a callable 16:32 interface or by using the Virtual DevHlp services that map to File System APIs.

Physical device drivers and virtual device drivers use the following OS/2 DevHlp functions to establish inter-device driver communication (IDC).

RegisterPDD This function is called by the PDD during initialization to advertise a 16:16 entry point for VDD-PDD communication. The PDD provides a textual name, which the VDD must supply during its initialization.

VDHOpenPDD This function gets the address of the routine in a physical device driver that the virtual device driver uses to communicate with the physical device driver. The physical device driver's device must have previously registered its name and entry point using the DevHlp service, RegisterPDD. If the function is successful, it returns a pointer to the physical device driver IDC entry point.



MAD16 PDD and VDD Sample Device Drivers (Watcom C)

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

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

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

PDD \ddkx86\mmos2\samples\mad16

VDD \ddkx86\mmos2\samples\vmad16



Board Architecture

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

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

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



MAD16.ADD Device Driver Overview

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

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

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



Boot Sequence

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

Device driver load order is as follows:

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

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



PDD Operation and Architecture

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

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

The following table describes the MAD16.ADD source code. 

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



VDD Operation and Architecture

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

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

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

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

The figure below illustrates the architecture. 

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

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

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

The following table describes the VMAD16.SYS source code. 

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



PDD Sample for Video Capture Adapters

This DDK provides a sample of a video capture physical device driver (PDD) to assist in the creation of physical device drivers (PDDs) for video capture adapters (VCAs).



Source Code

Source code for the physical device driver (PDD) sample is located in the \ MMOS2\MMTOOLKT\SAMPLES\VCADDT subdirectory. Source files include documentation headers, which provide detailed descriptions of the programming concepts and routines used in incorporating the module.

The sample programs require MASM** 5.1 for assembly. 

/-------------------------------------------------------------\
|File                     |Description                        |
|-------------------------+-----------------------------------|
|README                   |Describes how to create the        |
|                         |resource DLL containing the video  |
|                         |adapter information and how to     |
|                         |create the .SYS file containing the|
|                         |VCDD.                              |
|-------------------------+-----------------------------------|
|VCA32.ASM                |Contains the main entry point for  |
|                         |IOCtl parsing.                     |
|-------------------------+-----------------------------------|
|VCACAPT.ASM              |Contains image copy and scale      |
|                         |routines.                          |
|-------------------------+-----------------------------------|
|VCAIDC.ASM               |Contains device specific streaming |
|                         |routines.                          |
|-------------------------+-----------------------------------|
|VCAINIT.ASM              |Contains device initialization     |
|                         |routines.                          |
|-------------------------+-----------------------------------|
|VIDIDC.ASM               |Contains generic device streaming  |
|                         |routines.                          |
|-------------------------+-----------------------------------|
|VIDIDC.INC               |Contains streaming instances       |
|                         |structures.                        |
|-------------------------+-----------------------------------|
|VIDIN.INC                |Contains the open instance         |
|                         |structure.                         |
|-------------------------+-----------------------------------|
|VIDVCI.INC               |Contains the interface for the     |
|                         |IOCtl.                             |
|-------------------------+-----------------------------------|
|VIDVCIT.SYS              |Is the compiled device driver.     |
\-------------------------------------------------------------/



Program Flow

The following figure illustrates the program flow from the Media Device Manager (MDM) through the PDD and finally on to the video capture adapter. 

    /--------------\              /--------------\
    | Media Device | (4)          | SPI          |
    | Manager      |--------------� Interfaces   |
    |              |              | SSM          |
    \--------------/              \------�-------/
    (1)    |                      (5)    |
           |                             |
    /------�-------\              /------�-------\
    | Vendor-      |              | Video Capture|
    | Specific     |              | Stream       |
    | Driver       |              | Handler      |
    \--------------/              \------�-------/
    (2)    |                       (6)   |
           |                             |
    /------�-------\                     |
    | Physical     |                     |
    | Device       �---------------------/
    | Driver       |
    \--------------/
    (3)    |
           |
    /------�-------\
    | Video        |\ �-- Video Input
    | Capture      |/
    | Adapter      |
    \--------------/

1 Media Control Interface functions are passed from the MCD to the vendor- specific driver.

2 The VSD passes information to the PDD.

3 The PDD controls the video capture adapter. The sample provided works with the IBM VCA adapter. To modify the sample to work with a different adapter, you must replace all hardware-specific routines with routines that are specific to your adapter. If you update the PDD sample, make a backup copy first. In order for the generic install to work, you must update the RCDATA 12 parameters so that MINSTALL will install the correct PDD.

4 After the video capture adapter is initialized, the MCD passes control to the Video Capture Stream Handler through the SPI interface.

5 The SPI interface receives video data from the video capture stream handler.

6 The control video data from the Video Capture Stream Handler is passed to and from the PDD.



PDD Architecture

The following figure illustrates how the PDD fits in the overall MMPM/2 subsystem structure. The media device manager (MDM) uses Media Control Interface commands to pass information through the vendor-specific driver and on to the PDD. The PDD directly controls the video capture adapter and passed video adapter request to the video capture stream handler. 

        ÉÍÍÍÍÍÍÍÍ»                  /-------------\
        º        º                  | Multimedia  |
        º        º�--\              | Application |
        ÈÍÍÍÍÍÍÍͼ   |              \---�---------/
        PM Monitor   |    Notifications |     | MCI Commands
                     |           /------+-----+------\
                     |      /----+------------�------+----\
                     |      |    |        MDM        |    |
                     |      \----+-------------------+----/
                     |           |  /----------------+-------------------\
                     |    /-------------\     /------�--------\          |
           mmioOpen  \----|Digital Video|     |Amplifier Mixer|          |
     /--------------------|Media  Driver|-\ /-| Media  Driver |-----\    |
     |    mmioSetHeader   \-----�-------/ | | \--------�------/     |    |
     |                          |         | |          |            |    |
     |                          |   /-----�-�------\   |            |    |
     |                          |   |SPI Interfaces|   |            |    |
     |                          |   |--------------|   |            |    |
     |                          \---|     SSM      |---/            |    |
     |                              \-------------�/�--\            |    |
     |                               audio data   |    |            |    |
     |              /-----------\  /---------\    |  /-�-----\  /-------\|
/---------\mmioWrite|Multi-track�------------/�---+--|Audio  �--|Audio  ||
| MMIO    �---------|Stream     |  /-\            \\ |Stream |  |Adapter||
| Manager |mmioSeek |Handler    �--+-|             | |Handler|  \-------/|
\---------/         \-----------/  |-| uncompressed| \-------/       /---/
multi|track data/---\   compressed |-| /---------\ \�/-------\  /----�--\
/----�----------+-\ |         data |-| \---------/�--|Video  |  |Capture|
|   AVI         | | |              \�/  |   data     |Capture�--|DD     |
|   IOProc      | | |               |   |            |Stream |  |copy   |
\---------------+-/ |               |   \-----\      |Handler|  |scale  |
 | /------------+-\ |               |         |      \-------/  \-------/
 | | Ultimotion | | |               |   /-----�-------\         /---�---\
 | | RT Codec   | | |               \---| Compression |         |Video  |
 | \------------+-/ \-------------------| Stream      |         |Adapter|
 �              \-----------------------� Handler     |         \-------/
raw data               compression      \-------------/



Strategy Commands

There are several generic strategy commands that are supported by all physical device drivers, video or otherwise. These are documented in the OS /2 Physical Device Driver Reference. The generic strategy commands supported by video device drivers are described in the following table. 

/------------------------------------------\
|Functions  |Description                   |
|-----------+------------------------------|
|INIT       |Initializes the device.       |
|-----------+------------------------------|
|OPEN       |Opens an instance of the      |
|           |device and prepares it for    |
|           |use.                          |
|-----------+------------------------------|
|CLOSE      |Closes an instance of the     |
|           |device.                       |
\------------------------------------------/



PDD Sample for MPEG Video Playback Devices

The Developer Connection Device Driver Source Kit for OS/2 provides a sample MPEG Video Playback physical device driver (PDD) to assist in the creation of PDDs for other video playback devices. This sample provides a code base for a new PDD, simplifies development, and illustrates the OS/2 MPEG Video Playback PDD model for a nonshared frame buffer device, also referred to as an overlay device. The ReelMagic card from Sigma Designs, Inc. is an example of such a device.

The code contained in this sample was derived from a working driver. All hardware-specific code and header files have been removed from the sample. Although this device driver was written for a device that uses the split- stream model, it is easily adaptable to the single-stream model.

The split-stream MPEG I/O procedure splits the audio and video packets out of the MPEG file. The audio data packets are passed through the subsystem to the audio DD, and the video data packets are passed through the subsystem to the video DD. As the audio DD returns the buffers that it has played, it also returns the current audio time-which is in turn passed through the subsystem to MPEG hardware compressor/decompressor (CODEC) and from there is sent to the video DD on the next VCAI_PLAY command.

The single-stream MPEG I/O procedure reads the entire MPEG file one buffer at a time-without splitting the video and audio data. As each buffer is read in, it is passed through the subsystem to the video DD. With single stream, every byte in the file is passed to the DD; whereas with split stream, only the video data packets are passed to the video DD. The single- stream video DD and its hardware are then responsible for producing the video and audio along with all synchronization.

Note:From the video DD's perspective, the main difference in the single- stream model is that the SCR, PTS, and Audio PTS fields in the VCAI_PLAY contain zero.



Source Code

Source code for the PPD sample is located on the Developer Connection Device Driver Source Kit for OS/2 CD-ROM. Source files include documented headers, which provide detailed descriptions of the programming concepts and routines. 

/-------------------------------------------------------------\
|File                     |Description                        |
|-------------------------+-----------------------------------|
|MAKEFILE                 |Makefile.                          |
|-------------------------+-----------------------------------|
|INIT.ASM                 |Handles the Device Init message at |
|                         |OS/2 start-up time.                |
|-------------------------+-----------------------------------|
|IOCTL.ASM                |IOCtl message routing and IOCtl    |
|                         |processing.                        |
|-------------------------+-----------------------------------|
|SUBSA.ASM                |Device-specific Assembler routines.|
|-------------------------+-----------------------------------|
|VEND.C                   |Device-specific C routines.        |
|-------------------------+-----------------------------------|
|VIDRMS1.INI              |Device-specific .INI (defaults     |
|                         |settings) file.                    |
|-------------------------+-----------------------------------|
|VIDVCI.INC               |IOCtl interface description/header |
|                         |file.                              |
|-------------------------+-----------------------------------|
|ENDOF.ASM                |Label to mark the end of the code. |
|-------------------------+-----------------------------------|
|INOUTP.C                 |C-callable routines for port IN and|
|                         |OUT.                               |
|-------------------------+-----------------------------------|
|INOUTP.H                 |C interface header file for Port IN|
|                         |and Port OUT routines.             |
|-------------------------+-----------------------------------|
|VIDVCI.H                 |IOCtl interface description/header |
|                         |file for .C.                       |
|-------------------------+-----------------------------------|
|VIDVCI.INC               |IOCtl interface description/header |
|                         |file for .ASM.                     |
|-------------------------+-----------------------------------|
|ARUNTIME.ASM             |Standard C runtime routines written|
|                         |in assembler.                      |
\-------------------------------------------------------------/



Program Flow

1.The application opens the MPEG Digital Video Device through the media control interface (MCI).

2.The media control device (MCD) finds the PDDnameand VSDnamein the MMPM2.INI file and opens the VSD with the PDDname.

3.The VSD opens the PDD, reads in an .INI file, and passes the .INI file to the PDD. The filename is based on the first seven characters of the PDDnamewith the .INI extension. The .INI file is device-dependent. The types of information in the .INI file may include default key color, video alignment offsets, and video quality adjustments.

4.Through the DevInfo IOCTL, the VSD queries the PDD to determine its capabilities.

5.The application loads an MPEG file through the MCI.

a.Through the standard I/O Proc interfaces, the MCD identifies MPGIO as the I/O Proc for the MPEG file.

b.Through the standard compressor/decompressor (CODEC) interfaces, the MPEG I/O Proc (MPEGIO) selects the MPEG hardware decompressor (MPEGDC). The MCD tells the VSD handle to the MPEGDC so that it can call the VSD/PDD to play back the compressed Video MPEG data.

c.Through the VSD and the PDD, the hardware CODEC MPEGDC loads the device with its DSP/MicroCode from a file whose name matches the results of a query of the VSD/PDD.

d.The MCD opens the playback window, queries the VSD/PDD for the transparent/key color, and paints the window with the key color.

e.The MCD tells the VSD/PDD the source movie size and window location.

f.The MCD tells the VSD/PDD to enable the monitor window and color keying.

6.The application issues a play command through the MCI.

7.The MPEG I/O Proc reads part of the MPEG file.

8.The audio data is sent through the system to the audio PDD.

Note:MPEG audio data is passed to the audio device driver via the DDCMD_ READWRITE_PARM structure. Field ulParm1 contains the initial audio system clock reference (SCR), and ulParm2 contains the Presentation Time Stamp ( PTS).

9.The video data is sent through the system to the MPEG CODEC (MPEGDC). If this data is the first packet in the stream, MPEGDC will issue a VCA_ PlayStart IOCtl to the VSD/PDD to set up the device and initialize the stream time. As the data arrives, MPEGDC issues a VCA_PlayData IOCtl to the VSD/PDD.

10.As the audio PDD plays audio buffers, it reports back to the audio stream time, which is eventually sent to MPEGDC.

11.The audio time is passed on the next VCA_PlayData IOCtl to the VSD/PDD.

Note:When playing from the beginning of an MPEG file the audio time will begin at zero regardless of the files initial SCR value.

12.Steps 7 through 11 are repeated until the end of the MPEG data/file is reached-at which time, a VCA_PlayStop is issued indicating that the end of the file has been reached.



Audio and Video Synchronization (Split-Stream Model)

The MPEGDC is a decompressor that does not require the MMPM/2 subsystem to control or time the flow of images to the decompressor, whereas the Ultimotion CODEC allows the MMPM/2 subsystem to control the flow of images to the decompressor, which is not called until it is time to display the image. Data is sent to MPEGDC as fast it can be sent by the system. The PDD and its hardware must control the synchronization between audio and video. When the data is arriving too fast (the hardware data buffers are filled), the PDD must suspend processing on the MPEGDC thread until the hardware can accept more data. The hardware may contain over three-fourths of a second of video data waiting to be decompressed. The hardware will decompress the image when its SCR reaches the presentation time stamp (PTS) of the data packet in the hardware buffer. If the SCR is greater than the PTS, the hardware will speed up or skip images until the PTS and SCR match.

To synchronize the audio with the video, the PDD must know the current audio time. Because the audio and video have separate hardware with different clocks, the video PDD will need the audio time to keep the video synchronized with the audio.

As the audio stream plays the audio buffer, it reports back the current audio time. This time is relayed to the MPEGDC. The MPEGDC will pass down the last reported audio time to the PDD on the VCA_PlayData IOCtl. To get the current audio SCR, the PDD multiplies the audio time by 30 to convert from MMTime to the MPEG 90KHz clock and adds the stream's initial SCR from the VCA_PlayStart IOCtl audio time. The PlayStart audio time is the initial stream SCR. It is required because the audio stream times reported by the audio subsystem are zero-based times and the PTSs in the video stream are based on the initial SCR. The PDD compares the hardware video SCR with the calculated audio SCR to determine if the video is ahead of or behind the audio. If the audio is not synchronized with the video hardware, the video SCR must be updated to match the audio SCR.

Note:The audio time may contain the same value on subsequent PlayData commands until the audio device driver updates the audio stream time. The audio time can be set to zero, meaning no audio in the MPEG file or no audio PDD. In either case, the audio and video synchronization logic may be skipped.



Running the Sample Device Driver

The easiest way to install and run this sample device driver is to install Sigma Designs' ReelMagic through the OS/2 Warp Selective Install and copy this sample device driver over the Sigma Design Reel Magic device driver that has the same name. The file can be found in the MMOS2 subdirectory ( usually \MMOS2\VIDRMS1.SYS).

This device driver will not display images on the screen because it contains no hardware-specific code, but it will allow you to see and follow the commands and data to the device driver.

Reboot the computer after installing this sample device driver.



Audio Sample for Vendor-Specific Drivers

OS/2 Warp, Version 3 provides sample files that assist in the creation of vendor-specific drivers (VSDs). The VSD defines a generic device driver- like interface that effectively decomposes high-level media control interface functions into more fundamental operations at the DLL level.

Note:VSD functionality is available for OS/2 Warp, Version 3 and is not downward compatible.

The following figure illustrates the program flow from the Media Device Manager (MDM) through the VSD and finally on to the audio adapter. 

 [Artwork not shown]


1 Media Control Interface functions are passed from the Media Device Manager to the vendor-specific driver using VSD commands.

2 The VSD passes information to its device driver. This provides a Ring-3 interface to control audio devices. The VSD sample provided with the DDK should be adequate to cover all basic audio functions. If your audio adapter requires special processing, you might have to supplement the sample VSD. To install the VSD, update the VSDDriver= option in the generic install routines (or CARDINFO.RC).

3 The device driver controls the audio adapter.

4 After the audio adapter is initialized, the MDM passes control to the Audio Stream Handler through the SPI interface.

In order to play or record audio data, the audio stream handler sends VSD_ DDCMD messages to the VSD.

5 The SPI interface sends/receives audio data from the audio stream handler .

6 The Audio Stream Handler controls audio data passed to and from the VSD.

7 The VSD reports stream events (such as buffer completion) via the SHC_ REPORT_INT message.



Source Code

Source code for the vendor-specific driver (VSD) sample is located in the IBM Device Driver Source Kit for OS/2. Source files include documentation headers that provide detailed descriptions of the programming concepts and routines used in incorporating the sample. 


/-------------------------------------------------------------\
|AUDIOIF.C                |This module checks for valid VSD   |
|                         |messages and routes them to the    |
|                         |appropriate function. It also      |
|                         |performs flag checking and error   |
|                         |reporting.                         |
|-------------------------+-----------------------------------|
|VSDOPEN.C                |This module retrieves the          |
|                         |VSD_AUDIOOPEN_PARMS structure from |
|                         |the VSD_OPEN message, checks to see|
|                         |if the hardware supports the       |
|                         |requested mode and returns resource|
|                         |management information. VSDs should|
|                         |not allocate hardware resource on  |
|                         |the message. This will happen on   |
|                         |the VSD_RESTORE message.           |
|-------------------------+-----------------------------------|
|VSDSET.C                 |The source file processes the      |
|                         |following VSD_SET messages:        |
|                         |VSD_SETVOLUME                      |
|                         |Changes the volume for the current |
|                         |instance.                          |
|                         |VSD_SETCONNECTOR                   |
|                         |Enable/Disables connectors.        |
|                         |VSD_SETMIXCONNECTIONS              |
|                         |Connects a source to a sink.       |
|                         |VSD_SETAUDIOATTRIBUTES             |
|                         |Sets audio items such as treble,   |
|                         |bass etc.                          |
|                         |VSD_SETMONITOR                     |
|                         |Enables/disables audio monitoring. |
|                         |VSD_SETDATATYPE                    |
|                         |Sets mode (i.e. bits/sample,       |
|                         |channels, sampling rate etc.).     |
|                         |VSD_SETMIXCONTROL                  |
|                         |Sets the attributes for a mixer    |
|                         |line.                              |
|-------------------------+-----------------------------------|
|VSDMAN.C                 |Processes the following messages:  |
|                         |VSD_RESTORE                        |
|                         |Consumes hardware resources. On    |
|                         |some audio cards, it will also load|
|                         |a DSP.                             |
|                         |VSD_SAVE                           |
|                         |Removes hardware utilization (other|
|                         |instances can use it after it is   |
|                         |done).                             |
|                         |VSD_CLOSE                          |
|                         |Closes VSD and frees memory etc.   |
|                         |VSD_RESOURCE                       |
|                         |Returns resource management        |
|                         |information to the caller.         |
|-------------------------+-----------------------------------|
|VSDIOCTL.C               |This C module makes AUDIODD IOCTL  |
|                         |calls. See the AUDIODD reference   |
|                         |for more information.              |
|-------------------------+-----------------------------------|
|VSDCAP.C                 |Processes the VSD_GETDEVCAPS       |
|                         |message. Returns the capabilities  |
|                         |of the VSD to the caller.          |
|-------------------------+-----------------------------------|
|VSDQUERY.C               |Processes the following messages:  |
|                         |VSD_QUERYVOLUME                    |
|                         |Returns the current volume setting.|
|                         |VSD_QUERYCONNECTOR                 |
|                         |Returns the state of a hardware    |
|                         |connector.                         |
|                         |VSD_QUERYMIXCONNECTIONS            |
|                         |Returns the source/sink connection |
|                         |information.                       |
|                         |VSD_QUERYAUDIOATTRIBUTES           |
|                         |Returns the status of audio        |
|                         |attributes.                        |
|                         |VSD_QUERYMONITOR                   |
|                         |Returns if audio monitoring is     |
|                         |available.                         |
|                         |VSD_QUERYDATATYPE                  |
|                         |Returns if a particular datatype is|
|                         |supported in the VSD.              |
|                         |VSD_QUERYMIXCONTROL                |
|                         |Returns the status of audio        |
|                         |attributes for a mixer sink/source.|
|                         |VSD_QUERYMIXLINE                   |
|                         |Returns line capabilities.         |
|-------------------------+-----------------------------------|
|VSDCONN.C                |Handles AUDIODD input/output       |
|                         |connections.                       |
|-------------------------+-----------------------------------|
|VSDDEF.C                 |Processes shared memory for the    |
|                         |VSD.                               |
|-------------------------+-----------------------------------|
|VSDINI.C                 |This file reads a vendor specific  |
|                         |initialization file, determines    |
|                         |resource management information to |
|                         |be returned on VSD_OPEN or         |
|                         |VSD_QUERYDATATYPE.                 |
|-------------------------+-----------------------------------|
|OS2MIXER.C               |Processes AUDIODD mixer IOCtls. For|
|                         |more information, see Mixer IOCtl  |
|                         |Functions Introduction.            |
|-------------------------+-----------------------------------|
|VSDINI2.C                |Main entry point.                  |
|-------------------------+-----------------------------------|
|DDCMD.C                  |Processes streaming related        |
|                         |functions. Communicates with       |
|                         |protect mode device driver to      |
|                         |implement DDCMD processing.        |
\-------------------------------------------------------------/



VSD Architecture

The VSD layer is a device-independent physical device driver-like layer that resides in Ring 3. It passes information between the media control interface subsystem and multimedia devices. [Artwork not shown] A VSD has the following characteristics:

�Does not deal with media control interface notifications.
�Usually uses a single standard time format (milliseconds).
�Usually does not have to deal with file management.



Interface to the VSD

The interface to the Vendor Specific Driver (VSD) uses an entry point called VSDEntry. First a DosLoadModule is issued for the VSD's DLL. The DosLoadModule returns a handle for the VSD. Then with the VSD handle, a DosQueryProcAddr is issued to find the VSD entry point (VSDEntry). From this point on, calls to the VSD are made through the following API: 

ULONG    VSDEntry ( HVSD       hvsd,     // Handle to VSD driver
                    ULONG      ulFunc,   // Function code
                    ULONG      ulFlags,  // Flags for driver
                    PVOID      pRequest) // Request Parameter Block/Value



Events

When the VSD receives VSD_DDCMD with DDCMDREGISTER, it should store the hid , hStream, and pSHDEntryPointfields of the DDCMDREGISTERstructure for use in reporting events. To report an event, the VSD should use the function pointer from the register to call the stream handler.



VSD_DDCMD

DDCMD_STOP (see the ulCmdfield of the DDCMDCONTROLstructure) operates differently for VSDs than for physical device drivers.

When a PDD receives a DDCMD_STOP, it is assumed that the stop is completed.

When a VSD receives a DDCMD_STOP, the stop is not considered complete when it is returned from the call. Rather it is considered complete when it the VSD is sent a STREAM_STOP_NOW (see ulFlagof the SHD_REPORTINTstructure and ulFlagof the MSG_REPORTINTstructure.)

Note:VSDs will receive VSD_DDCMDin the ulFuncparameter of the VSDEntry. To process specific VSD_DDCMDs, you must examine the pRequestparameter.

The following code sample shows how this can be written. 

LONG APIENTRY mixerDDCMDEntryPoint(  HVSD   hvsd,
                                     ULONG  ulFunc,
                                     ULONG  ulFlags,
                                     PVOID  pRequest )
{

  PDDCMDCOMMON  pCommon = (PDDCMDCOMMON) pRequest;

  if (pCommon == NULL)
  {
          return (ERROR_INVALID_BLOCK) ;
  }

  switch (pCommon->ulFunction)
  {
          case DDCMD_SETUP:
                return DDCmdSetup ((PDDCMDSETUP)pCommon, (PMCI_AMP_INSTANCE)hvsd );

          case DDCMD_READ:
                return DDCmdRead ((PDDCMDREADWRITE)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_WRITE:
                return DDCmdWrite ((PDDCMDREADWRITE)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_STATUS:
                return DDCmdStatus ((PDDCMDSTATUS)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_CONTROL:
                return DDCmdControl ((PDDCMDCONTROL)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_REG_STREAM:
                return DDCmdRegister ((PDDCMDREGISTER)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          case DDCMD_DEREG_STREAM:
                return DDCmdDeRegister ((PDDCMDDEREGISTER)pCommon, (PMCI_AMP_INSTANCE)hvsd);

          default:
                return (ERROR_INVALID_FUNCTION);
  }
}



Communication to the Stream Handler

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

SHC_REPORT_INIT The VSD uses this message when it needs data at interrupt time. For example, it uses this message to tell the stream handler that it has used up all the data and needs more.

When the stream handler gets the call, it knows the VSD is passing back a buffer that it might already have consumed. So the stream handler returns on that call, giving the VSD a fresh buffer to consume.

Note:It is possible for the stream handler to call back into the VSD when the stream handler receives an shc_report_init.

SHC_REPORT_EVENT The stream handler uses this message to keep in sync with VSD activities. For example, the stream handler can request the VSD to report back every tenth of a second that data is played. The stream handler has all the logic to handle these events. The VSD examines the request, and during its checks when it realizes a tenth of a second has been played in data, the VSD calls SHD_REPORT_EVENT. The stream handler can do what it wants at this point, and the VSD returns.

The VSD keeps track of the processes. In other words, only the VSD 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 VSD 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_CONTROLmessage, the pointer that comes back to the stream handler is a pointer to the cumulative time that the VSD has recorded in real time. So whenever the stream handler requests the device to stop, the VSD honors that request and informs the stream handler the real time that the VSD 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 VSD, with respect to when that stream was first started at the stream handler's request.



VSD Values

The stream handler passes a pointer to the VSD on DDCMD_STATUS. This points to a value used by the VSD for setting the referenced time of the VSD. It is not always correct for the VSD 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 VSD 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 VSD should start from the 30-second mark in that stream.

DDCMD_CONTROLhas an important NOTIFY subfunction that 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 VSD 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 VSD knows the real time.

For example, suppose the stream handler does a DDCMD_CONTROL NOTIFY at one minute. If the VSD 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 VSD occasionally checks to see whether it is at the one minute mark. When this event occurs, the VSD calls back on an SHD_REPORT_EVENT. Then you can free up the event detection linked list node.

Keep in mind that the VSD 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 VSD 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.



Priorities

When the VSD receives DDCMD_READand DDCMD_WRITEmessages, it will occur on a time-critical thread from the audio stream handler. If other threads are running, the DDCMD thread will always run first because of priority.

Other commands such as VSD_SETand VSD_QUERYmay come simultaneously at a normal priority. (You may be executing one command and then be jumped to a thread of higher priority.)



Device Type Function Table

Because the VSD interface supports commands for numerous data types, it is not necessary for every VSD to support all commands. The only commands that must be supported are those for the particular device type (for example, audio, video, and so on) that the VSD is implementing. This section provides guidelines for which functions and flags must be supported and which functions and flags are optional. The following table shows which functions are Required (R) and Optional (O) by device type. 

/------------------------------------------------------------------\
|Functions/Subfunctions            |Digital|Amp    |Laser  |Fax/Tam|
|                                  |Audio  |Mixer  |Disk   |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_CLOSE                         |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_GETDEVCAPS                    |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_OPEN                          |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_RESOURCE                      |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_RESTORE                       |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_SAVE                          |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERY                         |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_SET                           |R      |R      |R      |R      |
|----------------------------------+-------+-------+-------+-------|
|VSD_ESCAPE                        |O      |O      |O      |O      |
\------------------------------------------------------------------/


Legend:
  R - Required Command 
  O - Optional Command

The flags that must be supported by a VSD for the VSD_SET command vary according to the media types it supports. The following table illustrates which flags are required for the specified media type. 

/------------------------------------------------------------------\
|Functions/Subfunctions            |Digital|Amp    |Laser  |Fax/Tam|
|                                  |Audio  |Mixer  |Disk   |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETVOLUME                     |O      |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETAUDIOATTRIBUTES            |O      |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETMONITOR                    |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETDATATYPE                   |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETCONNECTOR                  |       |       |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETMIXCONNECTIONS             |       |       |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_SETMIXCONTROL                 |       |       |       |       |
\------------------------------------------------------------------/


Legend:
  R - Required Command 
  O - Optional Command 
  <Blank> - Not Applicable

The flags that must be supported by a VSD for the VSD_QUERY command vary according to the media types it supports. The following table illustrates which flags are required for the specified media type. 

/------------------------------------------------------------------\
|Functions/Subfunctions            |Digital|Amp    |Laser  |Fax/Tam|
|                                  |Audio  |Mixer  |Disk   |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYCONNECTOR                |O      |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYDATATYPE                 |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYMONITOR                  |       |O      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYVOLUME                   |O      |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYMIXCONNECTIONS           |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYMIXCONTROL               |       |R      |       |       |
|----------------------------------+-------+-------+-------+-------|
|VSD_QUERYMIXLINE                  |       |R      |       |       |
\------------------------------------------------------------------/


Legend:
  R - Required Command 
  O - Optional Command 
  <Blank> - Not Applicable



Device States

Media devices that transport data are considered to be in one of the following states at any given time:

�Registered
�Deregistered
�Saved
�Restored
�Closed

When a device is opened and restored, the device context is assumed to be in the restoredstate. The closedstate can be viewed as both the initial state and the termination state. Or this state can be thought of as not a state at all, because a device context does not exist before it is opened, and ceases to exist when it is closed.

The following figure lists the allowable device states across the top of the table and indicates the changes in state that occur when the command messages shown in the first column of the table are issued. This table assumes all error conditions keep the device in its current state. For example, a waveform player that is opened without an element remains in the stopped state when a play is issued, and the MCD receives an error code.

The following figure is provided as a guide to application developers and MCD writers. There can be no guarantee that every media device will conform to this table, but every effort should be made to hide the complexity of the device from the application.

[Artwork not shown]

Legend

  • After a restore, the device is considered active and available for use. If the stream has been registered, it is restored to the state it was in before the VSD_SAVE.
    - Error condition.



Install

To manually install the VSD, change the VSDDRIVER= statement for the relevant amp-mixer device to the new DLL name. To permanently install the VSD, see Adding Support for Audio and Video Adapters.



Using the High-Resolution Timer

The high-resolution timer (HRT) is used to provide millisecond-accuracy timing services to device drivers and applications.



Introduction

The high-resolution timer package includes the following files:

TIMER0.SYS the high-resolution timer driver

CLOCK01.SYS a modified CLOCK01.SYS for high-resolution timer support

CLOCK02.SYS modified CLOCK02.SYS for high-resolution timer support

TMR0_IDC.H the header file used to communicate with the high-resolution timer from another PDD

TMR0_IOC.H the header file for IOCtl interface to the high-resolution timer

TIMER0.DDP the DDINSTAL installation script



Installation

To install the high-resolution timer device driver, follow these steps:

1.Remove the readonly attribute from \OS2\BOOT\CLOCK*.SYS with the attrib command, e.g.: 

-r \os2\boot\clock*.sys

where * is the number in the name of your existing clock-system file.
2.Make a backup of \OS2\BOOT\CLOCK*.SYS.
3.Use DDINSTAL to install the driver.
4.Reboot.

Note:The high-resolution timer is intended for use with OS/2 Warp 3.0 and later. It has not been tested and is not supported under any previous version of OS/2. If you do use this timer with any previous version of OS/2 , you do so at your own risk.



Information for Microsoft C 6.0 Users

The header files were designed for Watcom C/C++ 10.0. If you are using Microsoft C 6.0, the only change that should be needed is to change the __ far, __cdecl, and __loadds keywords to _far, _cdecl, and _loadds-i.e., replace the double underscores with single underscores. To date, however, this has not been verified.



Ring-0 Usage

The high-resolution timer provides the following two services:

callback every nmilliseconds where nis an integer >= 1. This first option allows your device driver to register itself with the high-resolution timer . The device driver provides a 16:16 address of a function that the high- resolution timer calls every nmilliseconds. Registration (and deregistration) cannot occur during interrupt time.

If a device driver re-registers itself-by calling the registration function with the same 16:16 pointer-the high-resolution timer simply changes the count. This can occur at interrupt time.

query the current time This second option is used to obtain a 16:16 pointer to the current count variable. This variable can then be read by the device driver to obtain the current time. Note that this variable is only updated if the high-resolution timer is active-which is only true if at least one driver or application has registered itself with the high-resolution timer. Also note that this variable can be synchronized to another timeclock.

To call the high-resolution timer, call DevHelp_AttachDD with the first parameter as "TIMER0$ ". Remember, DDTable must be allocated in the default data segment. If you make it a local non-static variable (i.e., it is on the stack), the DevHelp_AttachDD call will fail. For example: 

TIMER0_ATTACH_DD DDTable;
PTMRFN ptmrfn;

DDTable.pfn=NULL;
if( DevHelp_AttachDD( ( NPSZ ) "TIMER0$ ", ( NPBYTE )  &DDTable ) )
{
    // TIMER0.SYS not loaded
}

if( !DDTable.pfn )
{
    // Something wrong with TIMER0.SYS
}

ptmrfn=DDTable.pfn;


To register your driver with TIMER0.SYS, do something like this: 

#define N    10                              // Call me every N milliseconds

void __far __loadds InterruptHandler( void )
{
   // This function is called every N milliseconds
}

if( ptmrfn( TMR0_REG, ( ULONG ) InterruptHandler, N ) )
{
   // Registration failed
}


A ptmrfn() call mustoccur at ring 0. This means that it cannot be made from your strategy INIT routine. The DevHelp_AttachDD call can be made from the INIT routine.

The ptrmfn() call cannot be made from INIT COMPLETE either. Attempts to do so will result in a return code of 6.



Ring-3 Usage

The IOCtl interface provides the ability to:

obtain a pointer to the clock counter The pointer returned is a 16:16 pointer, which should be converted to a 0:32 pointer for use with 32-bit applications.

query and set the resolution Currently, the resolution is always 1 millisecond. Attempts to set it to another value will be ignored, and querying the driver will always return 1 millisecond. You should set the resolution anyway-in the future, the driver may actually use a lower resolution to conserve resources.

block until a certain time has elapsed

Use the following code as an example of reading the current time. The compiler used is C-Set++ 2.1. If you use a different compiler, you may need another technique for handling 16:16 pointers. 

#include "tmr0_ioc.h"

APIRET rc;
HFILE  hfile;
ULONG  ulAction;
ULONG  ulOpenFlag = OPEN_ACTION_OPEN_IF_EXISTS;
ULONG  ulOpenMode = OPEN_FLAGS_FAIL_ON_ERROR |
                    OPEN_SHARE_DENYNONE |
                    OPEN_ACCESS_READWRITE;

ULONG  ulResolution = 1;
ULONG  ulSize1=sizeof( ulResolution );

ULONG  * _Seg16 pulTimer16;
ULONG  ulSize2=sizeof( pulTimer16 );
ULONG  *pulTimer;


rc=DosOpen( "TIMER0$ ", &hfile, &ulAction, 0, 0, ulOpenFlag, ulOpenMode, NULL );
if( rc )
{
   printf( "Couldn't open TIMER0$.\n" );
   return;
}

printf( "TIMER0$ opened.  File Handle is %lu\n",hfile );


rc=DosDevIOCtl( hfile, HRT_IOCTL_CATEGORY, HRT_SET_RESOLUTION,
                &ulResolution, ulSize1, &ulSize1, NULL, 0, NULL );
if( rc )
{
   printf( "Couldn't set resolution.\n" );
   DosClose( hfile );
   return;
}


rc=DosDevIOCtl( hfile, HRT_IOCTL_CATEGORY, HRT_GET_POINTER,
                NULL, 0, NULL, &pulTimer16, ulSize2, &ulSize2 );
if( rc )
{
   printf( "Couldn't get pointer.\n" );
   DosClose( hfile );
   return;
}

pulTimer=pulTimer16;                // Converts a 16:16 pointer to a 0:32 pointer
if( !pulTimer )
{
   printf( "NULL pointer.\n" );
   DosClose( hfile );
   return;
}

// At this point, pulTimer is now a pointer to the timer 0 counter variable

rc=DosClose( hfile );


DosOpen( "TIMER0$" ) registers the application as a client. At this point, the high-resolution timer driver is taking interrupts; so make sure the driver is open only when you need timer services. The pointer is valid for the life of the process; and each call to HRT_GET_POINTER allocates another selector-therefore, this call should be made only once.

To block until a certain time has elapsed, use the following code as an example. For brevity, the details (such as checking return codes) have been omitted. 

ULONG  ulDelay=1;                     // Number of milliseconds to wait
ULONG  ulSize2=sizeof( ulDelay );

DosOpen( "TIMER0$  ", &hfile, &ulAction, 0, 0, ulOpenFlag, ulOpenMode, NULL );
DosSetPriority( 0, PRTYC_TIMECRITICAL, 0, 0 );
DosDevIOCtl( hfile, HRT_IOCTL_CATEGORY, HRT_BLOCKUNTIL,
             &ulDelay, ulSize2, &ulSize2, NULL, 0, NULL );


Using a time-critical thread is important.



Common Problems

The following problems might occur due to the nature of the high-resolution driver.

trap D This is usually caused by using the wrong version of CLOCK0x.SYS. If the old CLOCK0x.SYS is in \OS2, for example, and the new one is in \OS2\ BOOT, the kernel will load the old driver. A quick way to check is to use the command "dir \clock0?.sy? /s" on the boot partition. This will search the entire hard drive for the clock drivers.

clock driver will not load Either some performance tool is running, or you are using the Warp GA version of CLOCK0x.SYS.



Caveats

The following should be considered when using the high-resolution timer:

�Only the first parameter to PTMRFN is checked; no other parameters are checked.

�It is possible to write to the timer count variable from another PDD and disrupt the high-resolution timer.

�While TIMER0 is active (i.e., while it is taking interrupts), DOS sessions do not have access to timer 0.

�Performance tools such as C Set's DDE4XTRA.SYS and Visual Age's CPPOPA3. SYS are incompatible with this driver.

�Device drivers should not depend on having the first tick occur at any particular time.

If a driver registers for 1 millisecond, for example, the first tick might occur less than 1 millisecond after the registration.



Anomalies

The following anomalies currently exist in the use of the high-resolution timer:

�Having multiple device driver's attached to the high-resolution timer has not been tested.

�The high-resolution timer sets interrupts at 1 millisecond even if a slower rate would suffice. If one driver wants callbacks every 2 milliseconds and another wants them at 4 milliseconds, the driver could program IRQ 0 for 2-millisecond ticks, but it does not.

�HRT_FREE_POINTER does not currently do anything.

�While the high-resolution timer is taking interrupts, DOS sessions (VDMs) will not receive INT 8 or INT 1Ch calls. Only one device driver can receive interrupts on a given IRQ in OS/2; and VTIMER.SYS-the VDD that provides INT 8 and INT 1Ch services to VDMs-expects CLOCK0x.SYS to deliver IRQ 0 interrupts. Because the high-resolution timer gets IRQ 0 interrupts, CLOCK0x.SYS-and therefore VTIMER.SYS-cannot get them.



Real-Time MIDI Subsystem

The real-time MIDI subsystem (RTMIDI) provides real-time processing of MIDI data within the driver itself. The following sections describe how device drivers communicate with RTMIDI:

�IDC Interface
�Type-A Drivers
�Registering a Type-A Driver

Refer to the Multimedia Subsystem Programming Guide(included with the IBM Developer's Toolkit for OS/2) for more information on the real-time MIDI subsystem.



IDC Interface

IDC stands for inter-device-driver communication. It is a technique for making function calls from one driver to another, thereby allowing the two drivers to communicate with one another. For more information on IDC, refer to the OS/2 Physical Device Driver Reference.

Function prototypes and other declarations are found in MIDI_IDC.H. Note that "function pointers" and "entry points" are synonymous. All pointers, function or otherwise, are 16:16 (far) pointers.



Supported IDC Interfaces

The RTMIDI IDC interface is designed to support multiple "types" of client device drivers. An RTMIDI client device driver is a 16-bit physical device driver that registers itself with RTMIDI as a particular type. Currently, only Type A drivers are supported. The Type A drivers send and receive single MIDI bytes. This type is primarily intended for supporting the UART MIDI port on standard sound cards.

An individual physical device driver can be of multiple types and it can register itself with RTMIDI as many times as necessary. For instance, a sound card with four physical MIDI ports would make four Type-A registrations. RTMIDI would not realize that these four devices actually existed on one physical sound card and are handled by one driver.

The header file MIDI_IDC.H contains the function prototype for the entry points of RTMIDI. The initial call to the RTMIDI's main IDC entry point is used to obtain additional function entry points, one of each type.



Initializing IDC Communication

To initialize communication between your driver and RTMIDI:

Use the following code segment to obtain the main IDC entry point to RTMIDI and the entry points used to register the driver with RTMIDI. DevHelp_ AttachDD is used to obtain the main entry point, and DDTable.pfn retrieves the registration entry points.

This routine is normally executed when processing the init_complete strategy call. Make sure that DDTable is located in the current data segment (DS) and not on the stack (SS). 


MIDI_ATTACH_DD  DDTable;
MIDI_REGISTER  reg;

if (DevHelp_AttachDD("MIDI$ ", (NPBYTE) &DDTable ) )
{
  // Error
  // Return
}

reg.usSize=sizeof( MIDI_REGISTER );
DDTable.pfn(&reg);



Type-A Drivers

Type-A drivers send and receive single bytes to and from RTMIDI. They are typically used for simple UART MIDI ports or simple synthesizers, such as those found on most sound cards.



Type-A Driver Capabilities

When Type-A drivers register with RTMIDI, they must provide information on their capabilities by setting the appropriate bits in the flCapabilitiesfield of the MIDIREG_TYPEA structure that is passed for registration. (See Registering a Type-A Driverfor an example of registering a Type-A driver.) Flags marked with an asterisk (*) are not currently supported and should not be set. The flags are:

MIDICAPSA_INPUT Set this flag to indicate that this device can receive MIDI messages from RTMIDI. If set, then the pfnRecvByte and pfnRecvString fields in the MIDIREG_TYPEA structure must be properly initialized. If not set, then the corresponding hardware node cannot be enabled for receive.

MIDICAPSA_OUTPUT Set this flag to indicate that this device can send MIDI messages to RTMIDI. If not set, then the corresponding hardware node cannot be enabled for send.

MIDICAPSA_USES_BRIDGE * Set this flag to indicate that the device is a candidate for the MMPM/2 bridge.

MIDICAPSA_NOT_DEFAULT * Set this flag to indicate that this device should be selectable as the default device used by MIDISimpleOpen.

MIDICAPSA_RUNNING_STATUS Set this flag to tell RTMIDI that the device or the driver, or both, support running status.



Registering a Type-A Driver

The following is an example of registering a Type-A driver: 

USHORT __far __loadds __cdecl Open( USHORT  usPort, USHORT  usMode )
{
  // Open hardware
  // For example:  grab IRQ, send I/O commands to initialize the chips
}

USHORT __far __loadds __cdecl Close( USHORT  usPort, USHORT  usMode )
{
  // Close hardware
  // For example:  detach IRQ
}


USHORT __far __loadds __cdecl RecvByte( USHORT  usPort, BYTE  b )
{
  // Send byte bData to hardware
  // For example:  via an outp() command
}

USHORT __far __loadds __cdecl RecvString( USHORT  usPort, BYTE __far *pb,
                                          USHORT  usLength )
{
  // Send byte bData to hardware
  // For example:  via an outp() command
}


void __far __loadds __cdecl *Ioctl( PIOCTL_RP  pioc )
{
  // Process MMPM/2 IOCtl commands here, like volume change
  // pioc is a pointer to the actual IOCtl request packet
}


HW_REGISTER  hwreg;
ULONG  ulHandle;
PFNSENDBYTE  pfnSendByte;

hwreg.usSize=sizeof( HW_REGISTER );
hwreg.in.flCapabilities = MIDICAPSA_INPUT | MIDICAPSA_OUTPUT;
hwreg.in.pszDeviceName="My Device";
hwreg.in.pfnOpen=Open;
hwreg.in.pfnClose=Close;
hwreg.in.pfnRecvByte=RecvByte;
hwreg.in.pfnRecvString=RecvString;


if( !reg.pfnHWRegister( &hwreg ) )
{
  // Error
  // Return
}

ulHandle=hwreg.out.ulHandle;
pfnSendByte=hwreg.out.pfnSendByte;




Audio Device Driver Exerciser (PMADDE) Tool

The Audio Device Driver Exerciser (PMADDE) is a PM-interface tool you can use to test code for low-level MMPM/2 components, such as audio device drivers or stream handlers. Using PMADDE, you can test various stages of your code at the Ring 0 level. This is useful when you want to verify that individual functions are working in your device driver without testing media control interface code (which might not be written yet). Each time you complete a function, you can test the function to see that it works, and then continue with the development of your driver.



Setting Up the Program

Before using PMADDE, OS/2 2.xwith MMPM/2 must be installed on your computer. The PMADDE source files are located in the DDK\MMOS2\MMTOOLKT\ NEATSTUF\PMADDE subdirectory. To build the PMADDE program, change to the PMADDE subdirectory, type NMAKE, and press Enter. Your output is the executable file (PMADDE.EXE). You can then type PMADDEfrom the command line to start the program. The Audio Device Driver Exerciser window is displayed. [Artwork not shown]

The PMADDE program defaults to the first waveform audio device it locates. To change the default option, select Options. Select Change Deviceto display the Change Audio Device window. [Artwork not shown]

This window contains information about each installed audio device including the logical device name, physical device name, and product information. Select the audio device you want to test.



PMADDE Functions

The PMADDE tool uses Stream Programming Interface Functionsto test your audio device driver. The Data Streammenu on the Audio Device Driver Exerciser window includes the following choices: (See Stream Setup and Controlfor additional information on SPI functions.)

SpiGet Handler

This option sends an SpiGetHandler function to return a stream handler ID and ensure the stream handler is loaded. Although this function does not perform any actions on the audio device driver, you must complete this function before creating a stream.

SpiCreate

This option sends an SpiCreateStream function to the stream handler to create a data stream of a given data type. The data is then passed to the audio device driver using a DDCMD_REG_STREAMmessage, which establishes a communication link and registers a stream instance with the device driver.

SpiAssociate

This option sends an SpiAssociate function to link a stream objectwith a given stream source or target. A data object must be identified for use with a stream before the stream can be started.

SpiStart

This option sends an SpiStartStream function to start data streaming for a stream instance or group of streams. The device driver receives several calls including DDCMD_SETUP, DDCMD_WRITE, and DDCMD_CONTROL(DDCMD_START) messages.

SpiStop

This option sends an SpiStopStream function to the stream handler, which is translated to the audio device driver as a DDCMD_CONTROL(DDCMD_STOP) message.

SpiInstall Protocol

This option sends an SpiInstallProtocol function to install stream protocolin the stream handler. It also generates an internal Stream Protocol Control Block (SPCB) key, which is used to differentiate between multiple SPCBs of the same data stream type. If your device driver can perform using a type of data format that the MMPM/2 subsystem currently does not use as its default, use this option to install new protocol that your device driver supports.

SpiDestroy

This option sends an SpiDisableSync function to destroy the stream you created with SpiCreate. SpiDestroy calls the DDCMD_CONTROL(DDCMD_STOP) and DDCMD_DEREG_STREAMmessages at the inter-device driver communication (IDC) level. (See Inter-Device Driver Communication (IDC) Interface.)

SpiSeek

This option sends an SpiSeekStream function to set the time within the audio device driver. You can seek the stream to a certain position, back to 0, or position it forward.

SpiQuery Time

This option sends an SpiGetTime function to the stream handler, which issues a DDCMD_STATUSmessage to the audio device driver to report the current stream time in milliseconds.



PMADDE Scenario

The following test scenario uses the PMADDE program to play back a waveform audio file from the source file system stream handler (FSSH) to the target audio system stream handler (AUDIOSH$). See Stream Setup and Controlfor detailed information on the phases of operation for a data stream.



Step 1

To get a handler ID, select Data Stream. Select SpiGet Handlerfor a list of MMPM/2 installed handlers. [Artwork not shown]

Select AUDIOSH$ (audio stream handler) and FSSH (file system stream handler ), and select OK.

Note:AUDIOSH$ and FSSH are the only handlers that can be tested using the PMADDE program. The source code can be modified to create tools that test stream handlers other than AUDIOSH$ and FSSH.

The Active Handlers window then lists the handler names and classes and the IDs for AUDIOSH$ and FSSH. [Artwork not shown]

A handler ID is provided for an active handler to be a source (producer) and a target (consumer). After you have both a producer and consumer stream handler, you can advance to step 2 to create the stream.



Step 2

To create the stream, select Data Stream. Select SpiCreateto display the Create Data Stream window. [Artwork not shown]

Enter the input source and target stream handler IDs. For example, enter the FSSH source ID (4) and the AUDIOSH$ target ID (2). Select a stream data type, and select OK.

The Stream State field in the Active Streams window displays information about the stream that has been created. The audio device driver has accepted the audio IOCtls and the IDC APIs to create the stream.



Step 3

To associate the stream with an audio file, select Data Stream. Select SpiAssociateto display the Associate Data Stream window. [Artwork not shown]

Type the input stream number, an audio file name, and select OK. You can now start the stream you created, or you can create several streams.



Step 4

To start the stream, select Data Stream. Select SpiStartto display the Start Stream window. [Artwork not shown]

Type the stream number and select a start flag. The SpiStartStream function starts data streaming in a specific stream or in a synchronized group of streams. Select the Start flag to start the stream immediately. Select the Preroll flag to cause the source stream handler to start and fill the buffers. An event is generated by the Sync/Stream Manager when a stream is prerolled. The application can then start the stream (or streams) for improved real-time response and initial synchronization of streams.

You can perform a stop at any time on the waveform audio file. To stop a stream, select Data Stream. Select SpiStopto display the Stop Stream window. [Artwork not shown]

Type the stream number and select the appropriate stop flag. There are three types of stops. The first is the regular stop or pause, which pauses the data stream but does not disturb any data. The second type of stop is a discard stop, which stops the stream immediately and discards any data left in the stream buffers. The third type is a flush stop, which stops the source stream handler, but the target stream handler continues until the last buffer held when the stop was requested is consumed by the target stream handler.

For a discard or flush stop, the Sync/Stream Manager detects when the stream handlers have stopped and return all buffers. At this point, the Sync/Stream Manager notifies the application with an EVENT_STREAM_STOPPED event in the Event Monitor window.

Streams can be restarted after a stop or end-of-stream (EOS). For the EOS case, the stream would need to be reassociated with another object or a seek backward to some point in the stream would need to be performed to actually start streaming again. A flush stop after a pause stop causes the stream to flush the existing buffers to the output device.

Note:Typically, data streaming continues until the end of the stream. When this happens, the Sync/Stream Manager sends an EVENT_EOS event to the event routine of the application. To restart the stream after you have paused or stopped it, select SpiStartfrom the Data Streammenu. The program restarts the stream and informs you when an end-of-stream (EOS) is reached.



Step 5

To get the stream time, select SpiQuery Timefrom the Data Streammenu. [Artwork not shown]

Type the input stream number and select OK. The stream time is displayed in milliseconds.



PMADDE Script Interface

To pipe a test script that already exists into the program, select Run Script Filefrom the Optionsmenu. [Artwork not shown]

Select the script file you want to pipe into the PMADDE program, and select OK. If the script file exists, the user interface of the PMADDE program is disabled and commands are accepted from the script file only. The following figure is an example of a PMADDE test script. 

;*****************************************************
;**  Audio Device Driver Exerciser V 1.0
;**    Test Script File.
;*****************************************************
BEGIN                 ;
DEVICENAME AUDIO1$    ; device name
GETHANDLER  AUDIOSH$  ; stream handler name
GETHANDLER  FSSH      ;
CREATE  3  2  3       ; Source ID, Target ID & Data type index
SLEEP 1000            ; Sleep for 1000 milliseconds
CREATE  3  2  3       ;
SLEEP 1000            ;
ASSOCIATE  1  WELCOM.WAV  ; stream number & Audio file
SLEEP 1000            ;
ASSOCIATE  2  PMADDE.WAV  ;
SLEEP 1000            ;
START  1  0           ; stream number & flag (0=Start, 1=Preroll)
SLEEP 5000            ;
START  2  0           ;
END                   ;

The following information describes the syntax associated with the PMADDE script language.

Syntax Description

BEGIN Starts the script file.

DEVICENAME device nameSpecifies the physical device name.

CREATE hidSource hidTarget datatypeCreates a data stream of datatypefrom hidSourceto hidTarget. Select SpiCreatefrom the Data Streammenu to view the stream data types available. The data types listed correspond to a number beginning with 0. The second data type in the list is 1, the third is 2, and so on. To create a data stream from FSSH to AUDIOSH$ of data type PCM, 16-bit, 44 kHz, and mono, type the following: 

CREATE 4 2 3;

ASSOCIATE stream # filenameAssociates a data stream with a data object.

START stream# startflagsStarts a data stream. The startflagscan be one of the following:

�PREROLL
�START

STOP stream# stopflagsStops a data stream. The stopflagscan be one of the following:

�FLUSH
�DISCARD
�PAUSE

SEEK stream# mode units positionSeeks to the specified positionin the data stream using the specified unitsand specified mode.

DESTROY stream#Destroys the specified stream.

QRYTIME stream#Queries the stream time of the specified stream.

SLEEP sleepintervalSuspends execution of the script file for the duration of the

END Ends the script file.

You can also create a test script by recording your keystrokes to be piped into the PMADDE program at a later time. You must specify a name for the script file you want to create when starting the PMADDE program. If the script file exists, the user interface is disabled and commands are accepted from the script file only. If the script file specified does not already exist, all actions are recorded and a script file is created. For example, to create a script file named TEST.SCR, use the following syntax: 

PMADDE TEST.SCR logfile

Note:You must specify a logfile(for example, TEST.LOG) when creating a test script. If you are using the command-line interface to execute a test script that already exists, you must also specify a logfile.



Stream Setup and Control

There are five phases of operation for a data stream:

1.Configuration
2.Creation
3.Association
4.Streaming/Synchronization
5.Destruction

Each of these five phases involves specific operational steps that an application can control. In any phase, the program can take action to modify certain options. The five phases are described below.

Phase 1. Configuration

After installation, each system has predefined or default connection configurations that allow applications to operate according to general default parameters chosen by the user or by the installation program. An example of stream configuration is where waveform audio data is configured to stream to the Line 1 Output on the IBM Audio Playback and Capture Adapter. This is a default connection that determines which hardware output resource the waveform audio stream will connect to. These configuration options are established when you run the Multimedia Setup program of the MMPM/2 system. Application installation utility programs can also set up connection defaults. Note that the source and target stream handler, as well as the source and target device association, must be specified when the stream is created. 

 [Artwork not shown]

Phase 2. Creation

When a media control driver (or other multimedia application) determines that data will be streamed between devices, it can invoke SpiCreateStream, which results in the stream being created. The caller specifies the source and target stream handler IDs, source and target device-specific information, and the stream data type. (Use the SpiEnumerateHandlers function to return a list of stream handler names. You can then use the SpiGetHandler function to return a handler ID given a handler name. Use the SpiEnumerateProtocols function to determine which data types a given stream handler can process.) 

 [Artwork not shown]

The Sync/Stream Manager notifies each of the two stream handlers that a stream is being created, and each stream handler must return a valid stream protocol control block (SPCB) to the Sync/Stream Manager. The Sync/Stream Manager will negotiate the parameters of the stream and notify the handlers by a SHC_NEGOTIATE_RESULT call to each handler. Negotiation consists of determining which SPCB parameters both stream handlers can accept. This includes stream buffer sizes and the number of buffers needed to maintain continuous streaming of data.

Typically, the Sync/Stream Manager allocates buffers for the stream, but it is possible to use the application buffer directly. The SPCBBUF_ USERPROVIDED flag in the SPCB indicates whether to use provided buffers or to allocate buffers. This is useful for streaming to or from the memory stream handler. In a split stream situation, a particular stream might not allocate its own buffers but use the buffers of another stream. In other words, it might share buffers. This is useful for interleaved data coming from one source but going to more than one destination.

For Sync/Stream Manager-allocated buffers, stream buffer allocation is done during stream creation. The number of buffers to allocate is taken from the "negotiated" SPCB. The buffers are allocated and then locked, so that they will not be paged out to disk. The buffers are unlocked and freed upon an SpiDestroyStream request. These buffers are available at Ring 3 in the process linear space and Ring 0 in global linear system memory. The Sync/Stream Manager will provide global descriptor table (GDT) selectors to allow Ring 0 stream handlers to access the buffer memory. The stream handler can assume that the Sync/Stream Manager manages the GDT selectors used. The maximum buffer size is 64KB.

Both handlers (source and target) share access to the buffers allocated by the Sync/Stream Manager. Note that if the minimum buffer space (specified in the SPCB) is not available, the stream creation will fail. The allocation of memory when the stream is created prevents the need to perform allocations of physical memory when the stream is active, which could result in disruption of data flow affecting the real-time performance of the stream. Therefore, it is advantageous to allow the Sync/Stream Manager to allocate buffers and lock them at stream creation time instead of providing buffers to the Sync/Stream Manager that probably cannot be locked when the stream is created.

Phase 3. Association

After a stream is created, and before it is possible to start the stream, it is necessary to make sure that a data resource, or stream object, is identified for use with the stream. For example, if the application wishes to stream waveform data from application memory (the application dynamically creates the waveform), then the application must make an association between the stream and the memory object. This is accomplished using the SpiAssociate function. 

 [Artwork not shown]

An association for a specific stream handler must match the type of the stream handler as well as the data type of the stream. Each stream handler will list supported object types in response to calling SpiEnumerateProtocols. Note that only one data object can be associated with a stream once the stream is created, and it is specific to a particular stream handler (that is, source or target). Associations can be changed, but the stream cannot be active; it must be stopped first (discard stop, flush stop, or EOS). The SpiAssociate function can be used to " reassociate" data objects for a stream handler as long as the stream handler is the type that the stream was created to handle.

Note:Devices should be associated with stream handlers only when the stream is created.

Phase 4. Streaming/Synchronization

There are several stream operation functions, and each can be used in conjunction with stream synchronization. 

 [Artwork not shown]

The following paragraphs contain outlines of the function descriptions.

SpiStartStream Starts data streaming in a specific stream or a synchronized group of streams, depending on the flags for this function. This function also allows a stream or group of streams to be prerolled. Preroll allows the source stream handlers to start and fill the buffers. An event is generated by the Sync/Stream Manager when the streams are prerolled. The application can then start the streams for better real-time response and initial synchronization of streams.

If multiple streams are involved, when the synchronization master is started or prerolled, all slavestreams can also be started or prerolled. This synchronization relationship can be set up by using the SpiEnableSync function after all streams are created.

The active stream protocol governs the amount of data buffered and the rate of data flow maintained. Both source and target stream handlers are controlled by the stream protocol (SPCB). Both handlers contribute to the contents of the SPCB when the stream is created. Stream events such as cue points are detected by the appropriate stream handler and an event notification is sent to the process that owns the stream.

SpiStopStream Stops data streaming in a given stream or streams. There are three types of stops for this command. The first is the regular stop or pause, which pauses the data stream, but does not disturb any data. The second kind of stop is a discard stop, which requests that the stream be stopped immediately and the data left in the stream buffers be discarded. The third type is a flush stop. This stop requests that the source stream handler be stopped, but that the target stream handler continue until the last buffer held at the time the stop was requested is consumed by the target stream handler.

For a discard or flush stop, the Sync/Stream Manager will detect when the stream handlers have stopped and return all buffers. At this point, the Sync/Stream Manager notifies the application with an EVENT_STREAM_STOPPED event.

Streams can be restarted after a stop or end-of-stream (EOS). For the EOS case, the stream would need to be reassociated with another object or a seek backward to some point in the stream would need to be performed to actually start streaming again. A flush stop after a pause stop causes the stream to flush the existing buffers to the output device.

Note:Typically, data streaming continues until the end of the stream. When this happens, the Sync/Stream Manager sends an EVENT_EOS event to the applications event routine.

SpiSeekStream Seeks to a specific point in the stream source object. Depending on the type of object associated with the stream at a source or target, this function directs the appropriate stream handler to relocate the current stream index, or position, to the specified location. The object types that support this function are memory, file, CD track, and library object. Use this function to reposition the stream forward or backward from its current position. This can be performed only on a newly created, unstarted stream or a stopped stream (discard stop, flush stop, or EOS).

SpiEnableSync Establishes stream synchronization between multiple streams. Stream synchronization is automatically handled by the stream protocol, depending on whether a given stream is the synchronization masteror slave. Once a synchronization relationship is established, synchronization is maintained according to real-time events detected at the master and passed on to the slaves. The application does not have additional stream events to process due to synchronization. Only one stream can be a master.

SpiDisableSync Stops stream synchronization for a given stream or streams. A previously designated stream master is disabled, and all synchronization under that master is deactivated.

SpiGetTime Fills in the current stream-specific time information. This allows an application to query the stream time. This function is supported for any stream that is active or stopped, and will not disrupt data transport in the stream. A more accurate method to determine the stream time is to enable stream time events, which will report stream time continuously and in real-time to the application.

Phase 5. Destruction

When a stream is no longer to be used by an application, it must be destroyed. Note that the stream handlers involved can remain active with other streams, and will remain available to create additional streams ( without additional calls to SpiGetHandler). The application will receive no further stream events in its event handling routine after calling the SpiDestroyStream function. All system resources allocated to the stream are released, including the physical memory used to create stream buffers. After the stream is destroyed, the stream handler state reverts back to its condition immediately prior to the creation of the stream. If the stream being destroyed is a master stream of a sync group, all synchronization under that master stream will become inactive. If the stream is a slave in a sync group, the stream will be removed from the sync group and will not affect the master or other slave streams in the group.



stream object

A stream object is the data resource or device channel that represents either the data source or target for a stream. In order for a stream to obtain data, it must be associated with a source stream object. This can be a waveform audio data object such as a file on the file system, or it can be a MIDI mapper stream handler from the MIDI hardware adapter. Also, the stream target handler must be associated with a target stream object. This could be a file which will be written to, or it could be an output device that will store, convert, or transmit the data.

Association of a stream with a source stream object, target stream object, or both may be permanent. In other cases, associations must be made whenever the stream is created and before the stream may be manipulated. For example, if there is only one audio adapter with only one input line, then the audio stream handler device driver will always associate a stream with that input line whenever it acts as a source.

Associations are tied to the concept of connections at the media control interface level of the system. Default connections can be made between logical devices and the actual physical device that performs the function of the logical device. Media drivers must use this connection information to determine the source and target handler names to be used on a subsequent SpiGetHandler. The connection information is also used to provide the source and target device or object associations used on an SpiCreateStream function.

Devices may be associated with stream handlers at stream creation time only . An SpiAssociate request can be used, however, to "re-associate" data objects with stream handlers after the stream has been created. The stream must be stopped (discarded, flushed, or EOS) to do this.



stream protocol

A stream protocol defines key parameters that control the behavior of a data stream. The application can query, install, or deinstall a specific SPCB from a stream handler. Each stream handler supports one or more stream protocols. An SPCB is uniquely identified by the value of the stream data type (SPCB key). One field in the SPCB key allows the stream handler to have multiple SPCB's installed for the same data type. This field can be used by an application to specify which SPCB, for any data type, it wants to use. Each application in the system could define multiple SPCB for the same data type (see the ulTypefield in the SPCBKEY data structure). The application can modify a stream protocol by installing a new SPCB and deinstalling the old SPCB.



Stream Programming Interface Functions

The stream programming interface (SPI) contains functions exported by the Sync/Stream Manager to support applications that control real-time data streams. These functions are used to perform stream creation, association, configuration, operation, synchronization, and destruction functions. SPI functions also include enabling applications to modify Stream Protocol Control Blocks (SPCBs) and querying a stream's time information. 

/-------------------------------------------------------------\
|Function                  |Description                       |
|--------------------------+----------------------------------|
|SpiAssociate              |Associates a data object with a   |
|                          |stream handler.                   |
|--------------------------+----------------------------------|
|SpiCreateStream           |Creates a stream instance between |
|                          |a source and a target stream      |
|                          |handler.                          |
|--------------------------+----------------------------------|
|SpiDestroyStream          |Removes a stream instance from the|
|                          |system.                           |
|--------------------------+----------------------------------|
|SpiDetermineSyncMaster    |Determines the best master stream |
|                          |to be used in a sync group.       |
|--------------------------+----------------------------------|
|SpiDisableEvent           |Disables event detection for a    |
|                          |particular event.                 |
|--------------------------+----------------------------------|
|SpiDisableSync            |Removes a group of streams.       |
|--------------------------+----------------------------------|
|SpiEnableEvent            |Enables event detection for a     |
|                          |particular event.                 |
|--------------------------+----------------------------------|
|SpiEnableSync             |Establishes a group of streams to |
|                          |synchronize the streams.          |
|--------------------------+----------------------------------|
|SpiEnumerateHandlers      |Returns a list of the stream      |
|                          |handler names installed in the    |
|                          |SPI.INI file.                     |
|--------------------------+----------------------------------|
|SpiEnumerateProtocols     |Returns a list of stream protocol |
|                          |keys for the specified stream     |
|                          |handler.                          |
|--------------------------+----------------------------------|
|SpiGetHandler             |Returns the handler ID for the    |
|                          |specified stream handler.         |
|--------------------------+----------------------------------|
|SpiGetProtocol            |Queries a stream handler for a    |
|                          |specified stream protocol.        |
|--------------------------+----------------------------------|
|SpiGetTime                |Queries the current stream time.  |
|--------------------------+----------------------------------|
|SpiInstallProtocol        |Installs or removes a specified   |
|                          |stream protocol for a stream      |
|                          |handler.                          |
|--------------------------+----------------------------------|
|SpiSeekStream             |Seeks to a specified point in the |
|                          |stream object or sets the current |
|                          |stream time.                      |
|--------------------------+----------------------------------|
|SpiStartStream            |Starts data streaming for a single|
|                          |stream instance or a group of     |
|                          |streams.                          |
|--------------------------+----------------------------------|
|SpiSendMsg                |Sends a message to a stream       |
|                          |handler.                          |
|--------------------------+----------------------------------|
|SpiStopStream             |Stops data streaming for a single |
|                          |stream instance or a group of     |
|                          |streams.                          |
\-------------------------------------------------------------/



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=25936"