

                                AUDIO DEVICE DRIVERS FOR IBM PERSONAL COMPUTERS
                                                                   VERSION 1.02




                                                                    May 8, 1992


                                                                      Ron Lisle
                                                             Multimedia Systems


                                                                IBM Corporation
                                                              11400 Burnet Road
                                                                 Mail Stop 3109
                                                              Austin, TX  78758
                                                             PAN userid IBMMIDI





  SUMMARY


  NOTE:  Beta release information is experimental in nature and is is always
         subject to change.

  The Audio Device Drivers for IBM Personal Computers (AUDIO DD) is a set of
  computer programs for IBM and compatible computers that present a common
  audio interface to an application program.  Each individual Audio DD program
  provides the unique software required for a specific hardware audio inter-
  face.  The software developer thus creates one program which is written to
  operate with this Audio DD and the user installs the specific Audio Device
  Driver for their computer hardware.  A different user would take the same
  software and install the specific Audio Device Driver for their computer
  hardware.  When a new Audio interface comes onto the market, the developer
  supplies an Audio Device Driver for the new interface and the original appli-
  cation need not be changed.

  This document addresses the IBM Personal System/1 and IBM Personal System/2
  environments, referred to collectively in this document as "PC"s.  A com-
  panion document exists for the IBM RS/6000; "AIX Audio Device Driver Specifi-
  cation version 1.2".

  If you are preparing to write an Audio Device Driver, please refer to
  Appendix I, "Notes on designing a new Audio Device Driver" on page I-1 before
  proceeding any further.

  For information, contact the IBM Industry Support Center, phone (800)
  241-1620.


                                                                    Summary  ii


  CONTENTS

  CHAPTER 1.  INTRODUCTION   . . . . . . . . . . . . . . . . . . . . . . .  1-1
  1.1  Audio and Personal Computers  . . . . . . . . . . . . . . . . . . .  1-1
  1.2  Operating Systems   . . . . . . . . . . . . . . . . . . . . . . . .  1-1
  1.3  Programmable Audio Adapters   . . . . . . . . . . . . . . . . . . .  1-2
  1.4  Future Direction  . . . . . . . . . . . . . . . . . . . . . . . . .  1-2
  1.5  Notes to the Reader   . . . . . . . . . . . . . . . . . . . . . . .  1-2
  1.6  Programming examples and demonstration programs   . . . . . . . . .  1-3

  CHAPTER 2.  TECHNICAL DESCRIPTION  . . . . . . . . . . . . . . . . . . .  2-1
  2.1  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2-1
  2.2  Installing an Audio Device Driver   . . . . . . . . . . . . . . . .  2-1
  2.3  Standard File I/O Interface   . . . . . . . . . . . . . . . . . . .  2-2
  2.4  Shared Buffer Interface   . . . . . . . . . . . . . . . . . . . . .  2-3
  2.5  Minimal Audio Device Driver   . . . . . . . . . . . . . . . . . . .  2-3
  2.6  IOCTL functions   . . . . . . . . . . . . . . . . . . . . . . . . .  2-4
    2.6.1  AUDIO_INIT IOCTL  . . . . . . . . . . . . . . . . . . . . . . .  2-5
    2.6.2  AUDIO_STATUS IOCTL  . . . . . . . . . . . . . . . . . . . . .   2-11
    2.6.3  AUDIO_CONTROL IOCTL   . . . . . . . . . . . . . . . . . . . .   2-12
    2.6.4  AUDIO_BUFFER IOCTL  . . . . . . . . . . . . . . . . . . . . .   2-19
    2.6.5  AUDIO_LOAD IOCTL  . . . . . . . . . . . . . . . . . . . . . .   2-20
    2.6.6  AUDIO_WAIT IOCTL  . . . . . . . . . . . . . . . . . . . . . .   2-20
    2.6.7  AUDIO_HPI   . . . . . . . . . . . . . . . . . . . . . . . . .   2-21
    2.6.8  AUDIO_UPDATE  . . . . . . . . . . . . . . . . . . . . . . . .   2-24
    2.6.9  AUDIO_DIAG8_READ IOCTL  . . . . . . . . . . . . . . . . . . .   2-25
    2.6.10  AUDIO_DIAG8_WRITE IOCTL  . . . . . . . . . . . . . . . . . .   2-26
    2.6.11  AUDIO_DIAG16_READ IOCTL  . . . . . . . . . . . . . . . . . .   2-26
    2.6.12  AUDIO_DIAG16_WRITE IOCTL   . . . . . . . . . . . . . . . . .   2-26
  2.7  IOCTL Examples  . . . . . . . . . . . . . . . . . . . . . . . . .   2-27

  CHAPTER 3.  MUSICAL INSTRUMENT DIGITAL INTERFACE (MIDI)  . . . . . . . .  3-1
  3.1  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . . .  3-1
  3.2  MIDI Event Timing   . . . . . . . . . . . . . . . . . . . . . . . .  3-1
    3.2.1  MIDI Output Synchronization   . . . . . . . . . . . . . . . . .  3-2
    3.2.2  MIDI System Real Time message   . . . . . . . . . . . . . . . .  3-2
  3.3  MIDI System Exclusive Messages  . . . . . . . . . . . . . . . . . .  3-3
    3.3.1  General format of IBM System Exclusive Messages   . . . . . . .  3-3
    3.3.2  Timing Compression messages   . . . . . . . . . . . . . . . . .  3-3
    3.3.3  Timing Compression  . . . . . . . . . . . . . . . . . . . . . .  3-3
    3.3.4  Device Specific System Exclusive Messages   . . . . . . . . . .  3-3
    3.3.5  Device Specific   . . . . . . . . . . . . . . . . . . . . . . .  3-4
    3.3.6  Device Driver Control System Exclusive messages   . . . . . . .  3-4
    3.3.7  Device Driver Query System Exclusive messages   . . . . . . . .  3-7
    3.3.8  Device Driver Response System Exclusive messages  . . . . . . .  3-8
    3.3.9  Timbre parameter messages   . . . . . . . . . . . . . . . . . .  3-9
  3.4  Generic MIDI Sounds   . . . . . . . . . . . . . . . . . . . . . .   3-11

  APPENDIX A.  COMPATIBILITY BETWEEN AUDIO DEVICE DRIVER VERSIONS  . . . .  A-1
  A.1  Changes made between different version levels   . . . . . . . . . .  A-1


                                                                  Contents  iii


    A.1.1  Version .5  . . . . . . . . . . . . . . . . . . . . . . . . . .  A-1
    A.1.2  Version 1   . . . . . . . . . . . . . . . . . . . . . . . . . .  A-1
    A.1.3  Version 1 build 3   . . . . . . . . . . . . . . . . . . . . . .  A-1
    A.1.4  Version 1 build 4   . . . . . . . . . . . . . . . . . . . . . .  A-1
    A.1.5  Version 1 build 5   . . . . . . . . . . . . . . . . . . . . . .  A-2
    A.1.6  Version 1 build 6   . . . . . . . . . . . . . . . . . . . . . .  A-2
    A.1.7  Version 1 build 7   . . . . . . . . . . . . . . . . . . . . . .  A-2
    A.1.8  Version 1 build 8   . . . . . . . . . . . . . . . . . . . . . .  A-2

  APPENDIX B.  IBM MIDI SYSTEM EXCLUSIVES SUMMARY  . . . . . . . . . . . .  B-1

  APPENDIX C.  MIDI MESSAGE SUMMARY  . . . . . . . . . . . . . . . . . . .  C-1

  APPENDIX D.  GENERAL MIDI VOICES   . . . . . . . . . . . . . . . . . . .  D-1

  APPENDIX E.  GENERIC SOUNDS  . . . . . . . . . . . . . . . . . . . . . .  E-1

  APPENDIX F.  SUPPORTED AUDIO DEVICE DRIVERS  . . . . . . . . . . . . . .  F-1
  F.1  DOS Audio Device Drivers  . . . . . . . . . . . . . . . . . . . . .  F-1
  F.2  OS/2 Audio Device Drivers   . . . . . . . . . . . . . . . . . . . .  F-1

  APPENDIX G.  DEVICE SPECIFIC INFORMATION & CAPABILITIES  . . . . . . . .  G-1
  G.1  ACPA specific information   . . . . . . . . . . . . . . . . . . . .  G-1
  G.2  PS1 specific information  . . . . . . . . . . . . . . . . . . . . .  G-6
  G.3  Sound Blaster DD specific information   . . . . . . . . . . . . . .  G-8
  G.4  DigiSpeech specific information   . . . . . . . . . . . . . . . .   G-10
  G.5  MPU specific information  . . . . . . . . . . . . . . . . . . . .   G-13
  G.6  IBM Music Feature specific information  . . . . . . . . . . . . .   G-15

  APPENDIX H.   MPM/2 DEVICE DRIVER COMMANDS (IDC)   . . . . . . . . . . .  H-1
    H.1.1  DDCmd Definitions   . . . . . . . . . . . . . . . . . . . . . .  H-1
  H.2 DDCMD_SETUP  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  H-2
  H.3 DDCMD_READ   . . . . . . . . . . . . . . . . . . . . . . . . . . . .  H-3
  H.4 DDCMD_WRITE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  H-5
  H.5 DDCMD_STATUS   . . . . . . . . . . . . . . . . . . . . . . . . . . .  H-7
  H.6 DDCMD_CONTROL  . . . . . . . . . . . . . . . . . . . . . . . . . . .  H-8
  H.7 DDCMD_REG_STREAM   . . . . . . . . . . . . . . . . . . . . . . . .   H-10
  H.8 DDCMD_DEREG_STREAM   . . . . . . . . . . . . . . . . . . . . . . .   H-12
  H.9   Stream Handler Device Helper Functions   . . . . . . . . . . . .   H-13
    H.9.1  SHD Definitions   . . . . . . . . . . . . . . . . . . . . . .   H-13
  H.10 SHD_REPORT_INT  . . . . . . . . . . . . . . . . . . . . . . . . .   H-14

  APPENDIX I.  NOTES ON DESIGNING A NEW AUDIO DEVICE DRIVER  . . . . . . .  I-1

  GLOSSARY   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  X-1

  INDEX  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  X-3


                                                                   Contents  iv


  FIGURES


    2-1.  Example C code to open audio device  . . . . . . . . . . . . . .  2-2
    2-2.  Example DOS or OS/2 CONFIG.SYS.  . . . . . . . . . . . . . . . .  2-2
    2-3.  audio_init structure   . . . . . . . . . . . . . . . . . . . . .  2-8
    2-4.  audio_status structure   . . . . . . . . . . . . . . . . . . .   2-12
    2-5.  audio_control structure  . . . . . . . . . . . . . . . . . . .   2-13
    2-6.  audio_change structure   . . . . . . . . . . . . . . . . . . .   2-15
    2-7.  devid structure  . . . . . . . . . . . . . . . . . . . . . . .   2-16
    2-8.  MIDI mode information structure  (pointed to by
          audio_change.mode_info)  . . . . . . . . . . . . . . . . . . .   2-17
    2-9.  PCM mode information structure  (pointed to by
          audio_change.mode_info)  . . . . . . . . . . . . . . . . . . .   2-17
   2-10.  audio_buffer structure   . . . . . . . . . . . . . . . . . . .   2-19
   2-11.  audio_load structure   . . . . . . . . . . . . . . . . . . . .   2-20
   2-12.  audio_hpi structure  . . . . . . . . . . . . . . . . . . . . .   2-22
   2-13.  iobuf structure  . . . . . . . . . . . . . . . . . . . . . . .   2-23
   2-14.  High Performance Direct Call interface   . . . . . . . . . . .   2-24
   2-15.  diag_regs8 structure   . . . . . . . . . . . . . . . . . . . .   2-25
   2-16.  diag_regs16 structure  . . . . . . . . . . . . . . . . . . . .   2-26
   2-17.  Pseudocode example   . . . . . . . . . . . . . . . . . . . . .   2-27
   2-18.  OS/2 AUDIO_INIT IOCTL example  . . . . . . . . . . . . . . . .   2-28
   2-19.  DOS IOCTL example  . . . . . . . . . . . . . . . . . . . . . .   2-29
    3-1.  Calculating the frequency of MIDI timing clocks  . . . . . . . .  3-2
    G-1.  M-ACPA track_info structure (pointed to by
          audio_change.dev_info)   . . . . . . . . . . . . . . . . . . . .  G-6
    G-2.  Pointed to by audio_change.mode_info in SPV2 modes.  . . . . . .  G-6

                                                                     Figures  v





                                                                              1


  CHAPTER 1.  INTRODUCTION


  1.1  AUDIO AND PERSONAL COMPUTERS

  Nearly every personal computer has the capability to generate audio.  This
  capability may be limited to the ability to generate simple beeps, or it may
  extend up to the ability to record and play back high quality "direct-to-
  disk" digitized audio.  Quite often there are optional features that can be
  added to a computer to increase its audio capability.  For example, An IBM
  Personal System/2 in its most basic configuration is only capable of gener-
  ating simple beeps.  Audio adapter cards are available to allow it to synthe-
  size music or speech, or record and playback digitized audio, or control
  external music synthesizers and sound equipment via MIDI (refer to Chapter 3,
  "Musical Instrument Digital Interface (MIDI)" on page 3-1).


  When software is written to utilize audio, the author must consider which
  audio interfaces will be supported.  Often, multiple audio interfaces are
  supported requiring different code within a program, or different versions of
  a given program for each of the supported audio interfaces.  If a new audio
  interface is developed, audio software authors must decide how to modify
  their program to accommodate the new interface.  This effort is repeated for
  every manufacturer and for every program offered by that manufacturer.



  1.2  OPERATING SYSTEMS

  Computers use different operating systems to accommodate the needs of dif-
  ferent customers.  Each operating system has its own requirements and capa-
  bilities.  For IBM and its compatibles, DOS is the most widely used operating
  system.  DOS has many limitations though and future users will obtain many
  benefits by upgrading to more powerful operating systems.  For example, music
  programs often require a great deal of memory which is very difficult to
  manage under DOS.


  Operating System/2 ((R) IBM), Windows ((TM) Microsoft), and AIX ((R) IBM) are
  very powerful operating systems that will provide great benefit to the musi-
  cian of the future.  Each allows the generation of music software with
  improved capability, usability, and raw power.


  OS/2 ((R) IBM) and Windows are outgrowths of DOS while AIX is derived from an
  UNIX background.  All allow multiple tasks to be concurrently active and be
  readily available to the user from a multi-window screen.


                                                  Chapter 1.  Introduction  1-1




  1.3  PROGRAMMABLE AUDIO ADAPTERS

  A recent trend in personal computers is the use of a programmable digital
  signal processing subsystem to handle audio operations.  The IBM Multimedia
  Audio Capture and Playback Adapter (M-ACPA) is one such example.  This card
  contains 8k words of RAM which is used to program the Digital Signal
  Processor (DSP) contained on it.  The host PS/2 loads a DSP program into the
  RAM contained on the M-ACPA, thereby instructing the M-ACPA what operations
  to perform.  This approach provides great flexibility, while at the same time
  providing a tremendous amount of extensibility.  It is also possible to
  enhance the functional capability of the DSP subsystem by simply adding addi-
  tional DSP programs.  However, there can be serious complications for this
  type of adapter when operating in a multitasking environment.  There must be
  some way to ensure that one application doesn't attempt to load a new program
  into the DSP while another application is still using it.  In addition,
  adding new DSP programs may cause compatibility problems with existing audio
  applications.



  1.4  FUTURE DIRECTION

  An application programming interface (API) for audio is needed that devel-
  opers can use in writing music software.  Such an interface should allow por-
  tability across the diverse hardware and operating system environments
  currently in use, as well as allow applications to move gracefully into new
  environments.  This API must also allow new hardware and DSP programs to
  support the existing software base, thus making it easier and more attractive
  to offer leading edge technology.


  The Audio Device Drivers for IBM Personal Computers is the solution to these
  problems and is the subject of this document.



  1.5  NOTES TO THE READER

  The remainder of this document assumes an understanding of Operating Systems
  and software development.  The second section of this document addresses the
  unique aspects of MIDI.  Computer related data is notated in hexadecimal.

  Questions should be posed to the author at the address and phone number given
  on the title page.

  IBM intends to develop Audio Device Drivers for the specific audio interfaces
  listed as supported in Appendix F, "Supported Audio Device Drivers" on
  page F-1 and to use them within its own products.  IBM also intends to make
  these drivers available for use by other software developers without charge.
  Copies of this document, along with sample code and the currently implemented
  device drivers are available from the IBM Industry Support Center (800)
  241-1620.



                                                  Chapter 1.  Introduction  1-2



  1.6  PROGRAMMING EXAMPLES AND DEMONSTRATION PROGRAMS

  Included with the Audio Device Drivers package is a diskette containing
  several audio device drivers, an audio record and playback DEMO program (with
  full source code), and some helpful programming examples and header files.
  These examples are provided to assist developers in creating programs that
  utilize Audio Device Drivers.


                                                  Chapter 1.  Introduction  1-3



  CHAPTER 2.  TECHNICAL DESCRIPTION


  The Audio Device Drivers for IBM Personal Computers is a method for software
  to communicate with MIDI and audio devices (in this document collectively
  referred to as "Audio devices").  The purpose of this architecture is to
  allow software developers to write software independent of the computer envi-
  ronment or the audio interfaces being supported.

  Developers intending to write an audio device driver to support their own
  unique audio hardware should review Appendix I, "Notes on designing a new
  Audio Device Driver" on page I-1 before designing or writing any code.



  2.1  OVERVIEW

  A standard device driver approach is utilized, allowing DOS, Windows, OS/2,
  and AIX implementations to easily be realized.  A device driver is a small
  code module linked into the operating system during initialization.  It
  allows an operating system to communicate with a hardware device, without
  needing to know how the device's hardware interface works.  Device drivers
  are currently supported by all three major PC operating systems: DOS
  (including Windows), OS/2 (including Presentation Manager), and UNIX
  (including AIX).  Nearly all high level languages provide support for passing
  data to and from device drivers.  Thus, using a device driver is an extremely
  portable method of communicating with audio hardware.  For example, a simple
  MIDI file play program written in C using an IBM Music Feature device driver
  would need absolutely no changes to it in order to work on a similar system
  with a Roland MPU-401 device driver, even though the IBM Music Feature and
  Roland MPU-401 are vastly different.  In addition to providing portability
  across different MIDI and audio devices, the device driver approach also pro-
  vides portability across operating systems (DOS, OS/2, and AIX).



  2.2  INSTALLING AN AUDIO DEVICE DRIVER

  An unique device driver can be built for each audio device, and configured by
  the user (via the CONFIG.SYS file, for example in the DOS or OS/2 environ-
  ments).  The presence of an audio adapter is easily checked by an application
  by a simple "OPEN" function call as shown in Figure 2-1 on page 2-2.  Note
  that in the DOS environment, SHARE must be loaded to properly prevent mul-
  tiple opens to the same device from succeeding.


                                         Chapter 2.  Technical Description  2-1



  +---------------------------------------------------------------------------+
  |                                                                           |
  |      ...                                                                  |
  |      /* Open the audio device */                                          |
  |      if(!(audiostr=fopen("AUDIO1$","rb")))                                |
  |         abort("AUDIO Device Driver not installed.");                      |
  |      ...                                                                  |
  |                                                                           |
  |                                                                           |
  +---------------------------------------------------------------------------+
  Figure  2-1. Example C code to open audio device.  Successful open indicates
               that an audio device is installed.

  Multiple audio device drivers may be assigned by numbering each differently
  in the CONFIG.SYS as shown in Figure 2-2.  The number assigned replaces the
  'n' in the name "AUDIOn$".  Thus the second audio device driver installed is
  opened using the file name "AUDIO2$".

  +---------------------------------------------------------------------------+
  |                                                                           |
  |   DEVICE=C:\DOS\IMFDD.SYS 1 3                                             |
  |   DEVICE=C:\DOS\ACPADD.SYS 2                                              |
  |                                                                           |
  +---------------------------------------------------------------------------+
  Figure  2-2. Example DOS or OS/2 CONFIG.SYS..  This DEVICE entry in the
               CONFIG.SYS file causes the IBM Music Feature device driver to be
               installed, and assigns it to "AUDIO1$" using interrupt level 3.
               The Audio Capture and Playback Adapter device driver is
               installed, assigned to "AUDIO2$".

  2.3  STANDARD FILE I/O INTERFACE

  Communications to and from an audio device is initiated using standard oper-
  ating system file I/O system calls Open, Close, Read, Write, and IOCTL.  Data
  is passed to the audio device using the standard Write call, and read from
  the device using the standard Read call.


  Applications can communicate with the device driver using IOCTL messages,
  and/or a standard set of System Exclusive messages (while in MIDI mode).
  These perform such functions as:

      Controlling generation of Timing Information

      Querying amount of received data

      Setting volume or balance levels


                                         Chapter 2.  Technical Description  2-2


  2.4  SHARED BUFFER INTERFACE

  For the very highest performance, an application can use a 'shared buffer'
  approach.  In this approach, an application passes an iobuf structure to the
  device driver via the AUDIO_HPI function.  The application then performs all
  I/O operations directly to the buffer passed in the iobuf structure.  The
  device driver will utilize the information contained in the iobuf structure
  during its interrupt time.  iobuf.buf is a circular buffer used to perform
  I/O operations to the audio device.  Data is added to iobuf.buf at the point
  pointed to by iobuf.head, and removed from the point pointed to by
  iobuf.tail.  iobuf.count maintains a count of the amount of data contained in
  the queue, and should be updated along with the head or tail pointers when
  adding or removing data to the queue.  Multiple non contiguous buffers may be
  used.  iobuf.buf[] is an array of 1 or more structures containing the address
  and length of each data buffer.  The number of buffers is specified in
  iobuf.num_buffers.  The application should set iobuf.runflags IOBUF_LOCK when
  updating iobuf fields to avoid collision with the device driver interrupt
  handler.


  2.5  MINIMAL AUDIO DEVICE DRIVER

  Specialized audio device drivers can be created to satisfy specific applica-
  tion requirements.  For example, one of the most important functions provided
  by an audio device driver is to serialize access to the audio hardware by
  applications in a multitasking environment (such as OS/2 or MS Windows).  To
  achieve this, every application that uses audio hardware must, at a minimum,
  obtain ownership of the audio hardware during the time that it is using it.
  This is done via the Open, AUDIO_INIT, and Close functions.  Even applica-
  tions that are intended to run as stand-alone DOS applications and perform
  direct I/O operations to the audio hardware should follow this practice. All
  DOS applications can potentially be multitasked by running them in the DOS
  box of OS/2, or as a DOS application under Windows.  For those DOS applica-
  tions that don't require any of the other features of an audio device driver,
  a Minimal Audio Device Driver is available.  This driver implements only the
  Open, AUDIO_INIT, and Close functions.  Successful Open of the audio device
  driver, and AUDIO_INIT function, assure that no other applications are cur-
  rently using the audio hardware.  The CLAIM_HDWR mode is designed for just
  this purpose (refer to 2.6.1, "AUDIO_INIT IOCTL" on page 2-5).  DOS applica-
  tions written to use this driver can thus coexist peacefully with other (and
  possibly higher function) audio applications.


                                         Chapter 2.  Technical Description  2-3



  2.6  IOCTL FUNCTIONS

  Audio Device Drivers are controlled via IOCTL (Input/Output Control) calls.
  These are used to instruct the Audio DD on what type of audio to use (MIDI, 8
  or 16 bit PCM, etc.), and what operation to perform (record, play, start,
  pause, etc.).


  During audio playback, data is written to the audio device driver using
  standard file I/O functions.  MIDI data is written in blocks containing
  timing information which will allow the device driver to synchronize the data
  with its internal time base.  Sampled audio data will be output sample by
  sample, at the specified sample rate.  Data written to the device driver thus
  becomes queued up, waiting to be processed until the correct time.


  Note that for the digitized audio modes (PCM, ADPCM, etc), the default data
  buffer in the audio device driver may not be sufficient.  The AUDIO_HPI func-
  tion should be used to provide a larger buffer (see 2.6.7, "AUDIO_HPI" on
  page 2-21).  Also, some devices will perform I/O on fixed blocks sizes, and
  the buffer must be greater in size than the block size.  A 64k buffer size is
  recommended.


  IOCTL parameters are passed to and from the device driver in a data area con-
  taining one or more 16 bit word parameters.  The first parameter is always
  the request ID.  Subsequent words pass data to, or are used to receive data
  from the device driver.


  The IOCTL functions and their parameters are listed in Table 2-1 on page 2-5.


                                         Chapter 2.  Technical Description  2-4


  +---------------------------------------------------------------------------+
  | Table  2-1. Standard IOCTL functions                                      |
  +-----+----------------------------------+----------------------------------+
  | REQ | DESCRIPTION                      | PARAMETERS                       |
  | ID  |                                  |                                  |
  +-----+----------------------------------+----------------------------------+
  | 0   | AUDIO_INIT                       | struct far audio_init *          |
  +-----+----------------------------------+----------------------------------+
  | 1   | AUDIO_STATUS                     | struct far audio_status *        |
  +-----+----------------------------------+----------------------------------+
  | 2   | AUDIO_CONTROL                    | struct far audio_control *       |
  +-----+----------------------------------+----------------------------------+
  | 3   | AUDIO_BUFFER                     | struct far audio_buffer *        |
  +-----+----------------------------------+----------------------------------+
  | 4   | AUDIO_LOAD                       | struct far audio_load *          |
  +-----+----------------------------------+----------------------------------+
  | 5   | AUDIO_WAIT                       | none                             |
  +-----+----------------------------------+----------------------------------+
  | 6   | AUDIO_HPI                        | struct far audio_hpi *           |
  +-----+----------------------------------+----------------------------------+
  | 7   | AUDIO_UPDATE                     | struct far audio_update *        |
  +-----+----------------------------------+----------------------------------+

  +---------------------------------------------------------------------------+
  | Table  2-2. Specialized IOCTL functions                                   |
  +-----+----------------------------------+----------------------------------+
  | REQ | DESCRIPTION                      | PARAMETERS                       |
  | ID  |                                  |                                  |
  +-----+----------------------------------+----------------------------------+
  | 12  | AUDIO_DIAG8_READ                 | struct far diag_regs8 *          |
  +-----+----------------------------------+----------------------------------+
  | 13  | AUDIO_DIAG8_WRITE                | struct far diag_regs8 *          |
  +-----+----------------------------------+----------------------------------+
  | 14  | AUDIO_DIAG16_READ                | struct far diag_regs16 *         |
  +-----+----------------------------------+----------------------------------+
  | 15  | AUDIO_DIAG16_WRITE               | struct far diag_regs16 *         |
  +-----+----------------------------------+----------------------------------+


  2.6.1  AUDIO_INIT IOCTL

  The AUDIO_INIT IOCTL allows an application to tell the audio device driver
  which operation and audio type it wants to use.  It does so by initializing
  the appropriate audio_init fields to the desired values and issuing the
  AUDIO_INIT IOCTL request.  If the audio device driver can satisfy the request
  exactly as specified, it will return 0 to the application.  If the request
  can not be performed as specified, the audio device driver will fill in the
  audio_init fields with the supported values that most closely approximate the
  values specified by the user, set the BESTFIT_PROVIDED bit in
  audio_init.flags, and return 0 to the application.

  Note that if the application specifies invalid data in the audio_init fields,
  the device driver will most likely not return an error, but instead return



                                         Chapter 2.  Technical Description  2-5

  with the BESTFIT_PROVIDED bit set in the audio_init.flags, and the fields
  filled in for one of its supported modes.

  If, after examination of the returned values, the application is satisfied
  with the approximation, it can continue; otherwise it should use different
  values and issue another AUDIO_INIT request.


  The application specifies the type of audio to be used by filling in the fol-
  lowing audio_init fields:

      mode

      This field indicates the general audio mode, such as PCM, ADPCM, MIDI,
      etc.

      srate

      indicates the sample rate (if applicable).

      bits_per_sample

      indicates the number of bits per sample (if applicable).

      bsize

      indicates the data block size for blocked data.  Some devices perform i/o
      to their device in fixed block amounts.  For these devices, a full block
      of data must be written to the driver before it will be written to the
      device (during playback).  During record operations, a full blocks worth
      of data must be received before it will be available to the application.
      bsize should be equal to or less than 1024 bytes in size, but can not be
      guaranteed not to exceed that size.

      channels

      indicates the number of audio channels.  For example, mono is 1, stereo
      is 2.

      flags

      indicates several bits of information:

      o   FIXED specifies that the data is fixed, as opposed to variable rate
          or size.

      o   LEFT_ALIGNED specifies that the data is left aligned on a byte
          boundary.  This field is applicable only if bits_per_sample is not a
          multiple of 8.

      o   RIGHT_ALIGNED specifies that the data is right aligned on a byte
          boundary.  This bit is applicable only if bits_per_sample is not a
          multiple of 8.



                                         Chapter 2.  Technical Description  2-6


      o   TWOS_COMPLEMENT specifies that the data is represented using 2's com-
          plement signed format.  If this bit and the SIGNED bit are both zero,
          then the data is in unsigned format.

      o   SIGNED specifies that the data is represented using signed magnitude
          format, where by the highest bit is set to 1 to indicate a negative
          value, and the lower bits specify the absolute value.  If this bit
          and the TWOS_COMPLEMENT bit are both zero, then the data is in
          unsigned format.

      o   BIG_ENDIAN specifies that the most significant bytes precede the
          least significant bytes.  This bit is applicable only if
          bits_per_sample is greater than 8 (multibyte values).

  audio_init.position_resolution is set to indicate the resolution of position
  data returned by the device driver.  For example, the M-ACPA device driver
  may return position data rounded to the nearest 100 milliseconds when playing
  AVC ADPCM (.1 second blocked) data.


  If the digital signal processor (DSP) code must be loaded before the opera-
  tion can be performed, then the device driver will set the LOAD_CODE bit in
  audio_init.flags.  In this case, the name of the DSP file to be loaded will
  be specified in audio_init.loadpath.  The application must issue an
  AUDIO_LOAD IOCTL operation before trying to perform read or write operations.


  It is recommended that a single copy of each DSP load module be maintained,
  grouped together in a single subdirectory.  This subdirectory can then be
  referenced in the DOS APPEND command, or the OS/2 DPATH CONFIG.SYS parameter.


  Some audio devices are capable of performing more than 1 audio operation at a
  time.  The device driver for these devices may thus allow more than one
  application to use the device at one time.  This is done by allowing multiple
  opens to be active at any given time.  As long as the device can perform the
  operations requested by both applications at the same time, it will actually
  appear to be 2 different audio devices.  If, because of the operation being
  performed for the other application, it cannot perform a requested operation,
  it will return the OVERLOADED flag set in the rc field.  Thus, it is critical
  that the application check the returned flags and rc fields before pro-
  ceeding.  If an application is going to perform audio simultaneously on more
  than 1 track, it is recommended that the application perform the OPENs and
  AUDIO_INITs to both devices before issuing the AUDIO_START for either device.
  This will allow the device to select the correct DSP load module in order to
  support both tasks (if possible).


  audio_init.version_level specifies the Audio Device Driver version.  As audio
  device drivers evolve, some changes are bound to occur.  The
  audio_init.version_level is used to allow new function to be added to Audio
  Device Drivers without losing compatibility with existing applications.  When
  an application issues the AUDIO_INIT function, it specifies the version level
  of the driver that it needs.  The Audio Device Driver will compare its own



                                         Chapter 2.  Technical Description  2-7

  version level with that passed by the application, and ensure that it is com-
  patible.  If the Device Driver is 'down-level', it will return an error.  If
  it is newer than the application, then it will ensure that it handles calls
  from the application in a manner consistent with the application's version
  level.  The value specified in audio_init.version_level is the binary coded
  decimal representation of the version and build level.  For example, version
  1.0 build 15 is coded 0x01000015.  The high order byte is the version, the
  next byte is the revision number, and the least significant 2 bytes are the
  build number.


  If successful, the AUDIO_INIT request will return the slot number of the
  device in the field audio_init.slot_number.  Similarly, the type of device
  will be returned in the field audio_init.device_id.


  Before issuing an AUDIO_INIT IOCTL operation, the application must have
  opened the audio device driver.


  +---------------------------------------------------------------------------+
  |                                                                           |
  |   struct audio_init                                                       |
  |   {                                                                       |
  |     long  srate;                  /* the sampling rate in Hz           */ |
  |     long  bits_per_sample;        /* the number of bits per sample     */ |
  |     long  bsize;                  /* block size for this rate in bytes */ |
  |     short mode;                   /* Audio mode, as defined below.     */ |
  |     short channels;               /* # of audio channels (2=stereo)    */ |
  |     long  position_resolution;    /* Resolution of position information*/ |
  |     char  loadpath[LOAD_PATH];    /* path of DSP code to load          */ |
  |     unsigned long flags;          /* fixed, signed, etc.               */ |
  |     unsigned long operation;      /* the desired operation (play, rec) */ |
  |     short rc;                     /* return code for operation         */ |
  |     short slot_number;            /* slot number of this adapter       */ |
  |     short device_id;              /* adapter type identification #     */ |
  |     void far *reserved;           /* reserved for future use           */ |
  |     unsigned long  version_level = 0x01020000; /* Ver & level # of DD  */ |
  |   };                                                                      |
  |                                                                           |
  |                                                                           |
  +---------------------------------------------------------------------------+
  Figure  2-3 (Part 1 of 4). audio_init structure



                                         Chapter 2.  Technical Description  2-8


  +---------------------------------------------------------------------------+
  |                                                                           |
  |   /* These are the defined values for audio_init.mode.                 */ |
  |   #define ADPCM          1             /* AVC type ADPCM               */ |
  |   #define PCM            2             /* PCM                          */ |
  |   #define MU_LAW         3             /* Mu-law                       */ |
  |   #define MIDI           4             /* MIDI                         */ |
  |   #define A_LAW          5             /* A-law                        */ |
  |   #define SOURCE_MIX     6             /* External analog audio source */ |
  |   #define SPV2           7             /* reserved (Speech Viewer/2)   */ |
  |   #define ADPCMXA        8             /* XA CD ROM                    */ |
  |   #define DSSM           9             /* DS201 Standard mode          */ |
  |   #define DSMM           10            /* DS201 Movie mode             */ |
  |   #define CVSD           11            /* CVSD                         */ |
  |   #define SPV2BCPCM      25            /* reserved (Speech Viewer/2)   */ |
  |   #define SPV2PCM        26            /* reserved (Speech Viewer/2)   */ |
  |   #define SPV2NONE       27            /* reserved (Speech Viewer/2)   */ |
  |   #define IDLE           999           /* DeInitialize the track       */ |
  |   #define CLAIM_HDWR     32000         /* Claim hardware for other use */ |
  |                                                                           |
  |   /* This is the maximum path length available for DSP code modules    */ |
  |   /* in audio_init.loadpath                                            */ |
  |   #define LOAD_PATH      260           /* DOS, OS/2 length is 260      */ |
  |                                                                           |
  |                                                                           |
  +---------------------------------------------------------------------------+
  Figure  2-3 (Part 2 of 4). audio_init structure


                                         Chapter 2.  Technical Description  2-9


 +---------------------------------------------------------------------------+
 |                                                                           |
 |   /* These are the defined values for audio_init.flags                 */ |
 |   #define FIXED             ( 1 << 0 )  /* Fixed length data           */ |
 |   #define LEFT_ALIGNED      ( 1 << 1 )  /* Left align bits on byte     */ |
 |                                         /*  boundary                   */ |
 |   #define RIGHT_ALIGNED     ( 1 << 2 )  /* Right align bits on byte    */ |
 |                                         /*  boundary                   */ |
 |   #define TWOS_COMPLEMENT   ( 1 << 3 )  /* 2's complement data         */ |
 |   #define SIGNED            ( 1 << 4 )  /* Signed data (MSB = sign bit)*/ |
 |   #define BIG_ENDIAN        ( 1 << 5 )  /* Multibyte data in MSB first */ |
 |                                         /*  byte first order           */ |
 |   #define TIMER_USED        ( 1 << 17 ) /* System Timer is being used  */ |
 |   #define FOREGROUND        ( 1 << 18 ) /* Foreground operation only   */ |
 |   #define INPUT_GAIN        (1 << 19 )  /* input gain control supported*/ |
 |   #define PITCH             (1 << 20 )  /* pitch control supported     */ |
 |   #define INPUT             (1 << 21 )  /* input select supported      */ |
 |   #define OUTPUT            (1 << 22 )  /* output select supported     */ |
 |   #define MONITOR           (1 << 23 )  /* monitor select is supported */ |
 |   #define VOLUME            (1 << 24 )  /* Volume control "       "    */ |
 |   #define VOLUME_DELAY      (1 << 25 )  /* Volume Delay                */ |
 |   #define BALANCE           (1 << 26 )  /* Balance control             */ |
 |   #define BALANCE_DELAY     (1 << 27 )  /* Balance Delay               */ |
 |   #define TREBLE            (1 << 28 )  /* Treble control              */ |
 |   #define BASS              (1 << 29 )  /* Bass control                */ |
 |   #define BESTFIT_PROVIDED  (1 << 30 )  /* Bestfit returned            */ |
 |   #define LOAD_CODE         (1 << 31 )  /* DSP load needed             */ |
 |                                                                           |
 +---------------------------------------------------------------------------+
 Figure  2-3 (Part 3 of 4). audio_init structure


                                        Chapter 2.  Technical Description  2-10









  +---------------------------------------------------------------------------+
  |                                                                           |
  |   /* These are the defined values for audio_init.operation            */  |
  |   /* (note that in all cases the high order bit is always set)            |    */
  |   #define PLAY              0x80000001                                    |
  |   #define RECORD            0x80000002                                    |
  |   #define PLAY_AND_RECORD   0x80000003                                    |
  |   #define ANALYSIS          0x80000006    /* reserved */                  |
  |   #define DISTANCE          0x80000007    /* reserved */                  |
  |   #define MIGRATION         0x80000008    /* reserved */                  |
  |                                                                           |
  |   /* These are the defined values for audio_init.rc                   */  |
  |   #define NO_PLAY            1   /* Cannot play                        */ |
  |   #define NO_RECORD          2   /* Cannot record                      */ |
  |   #define NO_RECORD_AND_PLAY 3   /* Cannot both play & record          */ |
  |   #define INVALID_REQUEST    4   /* request was invalid                */ |
  |   #define CONFLICT           5   /* Conflicting information was found  */ |
  |   #define OVERLOADED         6   /* Out of DSP MIPS or Memory          */ |
  |   #define DOWNLEVEL_DD       7   /* DD is downlevel with repect to the */ |
  |                                  /*  level requested by the application*/ |
  |                                                                           |
  |                                                                           |
  |   /* These defines are used in audio_init.device_id                    */ |
  |   #define MINIDD             0   /* Minimal Device Driver               */|
  |   #define ACPA               1   /* IBM ACPA                            */|
  |   #define MACPA              2   /* IBM M-ACPA                          */|
  |   #define MPU_401            3   /* Roland MPU-401 or compatible        */|
  |   #define SOUND_BLASTER      4   /* Creative Labs Sound Blaster         */|
  |   #define IMF                5   /* IBM Music Feature                   */|
  |   #define PS1                6   /* IBM Personal System/1 audio feature */|
  |   #define DS201              9   /* DS201 audio adapter                 */|
  |                                                                           |
  |                                                                           |
  +---------------------------------------------------------------------------+
  Figure  2-3 (Part 4 of 4). audio_init structure




  2.6.2  AUDIO_STATUS IOCTL

  The AUDIO_STATUS IOCTL allows an application to obtain the current state of
  the audio hardware for a particular track.

  The values associated with the current audio mode will be returned in the
  fields srate, bits_per_sample, bsize, mode, channels, and flags as described
  in 2.6.1, "AUDIO_INIT IOCTL" on page 2-5.  The audio_change structure
  (Figure 2-6 on page 2-15) contains the current input, output, monitor,
  volume, balance, and tone control settings.


  change.dev_info points to a structure containing device dependent informa-
  tion.  For the M-ACPA card, the change.dev_info points to a track_info struc-
  ture (see Figure G-1 on page G-6).  This field is ignored if NULL.


                                        Chapter 2.  Technical Description  2-11



  The change.mode_info field points to a mode specific structure.  For MIDI,
  this points to a midi_info structure (see Figure 2-8 on page 2-17).  For PCM,
  it points to a pcm_info structure (see Figure 2-9 on page 2-17).  This field
  is ignored if NULL.


  The value associated with the current operation will be returned in the field
  operation.


    struct audio_status
    {
      long  srate;                /* the sampling rate in Hz            */
      long  bits_per_sample;      /* the number of bits per sample      */
      long  bsize;                /* block size for this rate in bytes  */
      short mode;                 /* ADPCM, ADPCMS, ADPCMH, PCM, etc.   */
      short channels;             /* number of audio channels (2=stereo)*/
      unsigned long flags;        /* variable, fixed, etc.              */
      unsigned long operation;    /* the desired operation (play, rec)  */
      struct audio_change change; /* volume, balance, etc.              */
    };

    /* These are the values defined for audio_status.operation    */
    #define STOPPED               0x80000000
    #define PLAYING               0x80000001
    #define RECORDING             0x80000002
    #define PLAYING_AND_RECORDING 0x80000003
    #define UNINITIALIZED         0xffffffff


  Figure  2-4. audio_status structure




  2.6.3  AUDIO_CONTROL IOCTL

  The AUDIO_CONTROL IOCTL operation is used to change the state of the adapter
  or change selected characteristics of the adapter.  State is changed by the
  following ioctl_request values:

  o   AUDIO_START
  o   AUDIO_STOP
  o   AUDIO_PAUSE
  o   AUDIO_RESUME

  Adapter characteristics are changed by the following ioctl_request value:

  o   AUDIO_CHANGE

  audio_control.request_info points to a structure that contains information
  specific to each type of IOCTL request.  See the respective section below for


                                        Chapter 2.  Technical Description  2-12


  each of these requests for specifics on what request_info points to.  All of
  these requests are executed at a particular point in time as specified by the
  caller.  Caller requests are executed audio_control.position number of units
  from the beginning of the first write operation after opening a track.
  Depending on the DSP code loaded and current mode of operation, units could
  be bytes, time, or some other unit of measure.  For example, to increase the
  volume of a track after the first 1,000 milliseconds worth of data have been
  written to the adapter, the caller issues an AUDIO_CHANGE request with
  audio_control.position set to 1000.  (This examples assumes that the track
  information pointed to by audio_control.request_info has been initialized
  appropriately, and that audio_buffer.position_type = POS_MSECS).


  If a request is made for a position number that has already occurred, it will
  be processed immediately.  Requests with a position number of 0 will be proc-
  essed immediately as well.


  NOTE:  The K12 version does not support audio_control.position values of
         other than 0.

  Any pending AUDIO_CHANGE requests are discarded when AUDIO_INIT is issued.


  struct audio_control
  {
    unsigned short ioctl_request; /* the desired IOCTL request to be executed */
    void far      *request_info;  /* the specifics of the request             */
    unsigned long position;       /* # of units before the request should be  */
                                  /*  executed.  Used to specify cue points.  */
    short         return_code;    /* contains any error code.                 */
  };

  /* These are the defined values for audio_control.ioctl_request.        */
  #define AUDIO_CHANGE    0       /* change adapter characteristics       */
  #define AUDIO_START     1       /* start new operation                  */
  #define AUDIO_STOP      2       /* stop current operation               */
  #define AUDIO_PAUSE     3       /* suspend the current operation        */
  #define AUDIO_RESUME    4       /* resume a suspended operation         */

  /* These are the defined values for audio_control.return_code       */
  #define  INVALID_REQUEST     4  /* bad audio_control.ioctl_request */
  #define  INVALID_INPUT_LIST  7  /* A device in input_list isn't supported  */
  #define  INVALID_OUTPUT_LIST 8  /* A device in output_list isn't supported */


  Figure  2-5. audio_control structure


                                        Chapter 2.  Technical Description  2-13


  AUDIO_CHANGE

  An AUDIO_CHANGE request in an AUDIO_CONTROL IOCTL operation allows an appli-
  cation to change adapter characteristics.  It is issued while the audio
  device is open.  The characteristics that are contained in the audio_change
  structure, such as input source, can be changed via an AUDIO_CHANGE request.


  AUDIO_CHANGE requests have the potential to create discontinuities in the
  flow of data.  Some audio devices may require that input, output, and monitor
  selections be performed prior to starting an operation.


  To change an adapter's characteristics, the desired value(s) should be placed
  in the respective field(s) and the request issued.  Note that all possible
  combinations of these fields are not necessarily supported by the device
  driver.  Invalid combinations will result in an error being returned by
  AUDIO_CHANGE.  The effects of issuing this request may vary for each
  requested change.  If a given field is to remain unchanged, then that field
  is set to AUDIO_IGNORE (-1).


  Input devices are specified using an array of devid structures in the
  input_list field listing each requested input device.  Unused entries are set
  to NULL_INPUT.  The devid structure allows specifying devices by type, and
  ordinal number (for those audio adapters which support more than 1 of a spe-
  cific type).  For example, to specify stereo line input, set
  input_list[0].devtype = STEREO_LINE_INPUT, and input_list[0].devnum = 1.


  Output devices are specified using an array of devid structures in the
  output_list field listing each requested output device.  Unused entries are
  set to NULL_OUTPUT.  The devid structure allows specifying devices by type,
  and ordinal number (for those audio adapters which support more than 1 of a
  specific type).  For example, to specify stereo line output, set
  output_list[0].devtype = STEREO_LINE_OUTPUT, and output_list[0].devnum =
  DEVICE_1.


  If a requested input our output device isn't supported by the audio device,
  audio_control.return_code will be set, and an error returned.


  Monitoring refers to the simultaneous playback of audio while it is being
  recorded.  When MONITOR_UNCOMPRESSED is specified, the recorded sound before
  filtering will be heard (i.e., the input source as it is).  When
  MONITOR_COMPRESSED is specified, the recorded sound is heard as it will sound
  upon later playback (i.e.,  having been compressed, then uncompressed, with
  any resultant loss of fidelity).  If the caller needs to hear what is being
  recorded while the record operation is being done, then one of these flags
  must be specified.  Otherwise no sound will be heard during the record opera-
  tion.


                                        Chapter 2.  Technical Description  2-14


  The change.dev_info points to a structure containing device dependent infor-
  mation.  For the M-ACPA card, the change.dev_info points to a track_info
  structure (see Figure G-1 on page G-6).


  The change.mode_info field points to a mode specific structure.  For MIDI,
  this points to a midi_info structure (see Figure 2-8 on page 2-17).


  struct audio_change
  {
    void far *dev_info;          /* pointer to device dependent information   */
    long input;                  /* reserved - used in v0 for input select    */
    long output;                 /* reserved - used in v0 for output select   */
    long monitor;                /* record monitor level                      */
    long volume;                 /* volume setting - linear 0 min to 7fffffff */
    long volume_delay;           /* # of milliseconds over which change occurs*/
    long balance;                /* balance setting 0 = left, ffffffff = right*/
    long balance_delay;          /* # of millisec's over which change occurs  */
    long treble;                 /* Treble tone control setting               */
    long bass;                   /* Bass tone control setting                 */
    long pitch;                  /* Pitch control setting                     */
    struct devid input_list[8];  /* array of 8 input devid's                  */
    struct devid output_list[8]; /* array of 8 output devid's                 */
    struct devid far *more_inputs;  /* Pointer to additional input devid's    */
    struct devid far *more_outputs; /* Pointer to additional output devid's   */
    long input_gain;             /* Input (record) gain control setting       */
    void far *mode_info;         /* pointer to a mode dependent structure     */
  };

  /* This define is used to cause fields to be ignored (no change)            */
  #define AUDIO_IGNORE      -1   /* Ignore this field                         */

  /* These are the defined values for audio_change.monitor                */
  #define MONITOR_OFF           0   /* No monitoring                      */
  #define MONITOR_UNCOMPRESSED  1   /* Uncompressed monitoring on         */
  #define MONITOR_COMPRESSED    2   /* Compressed monitoring on           */


  Figure  2-6. audio_change structure


                                        Chapter 2.  Technical Description  2-15


    struct devid
    {
      unsigned long devtype;
      unsigned long devnum;
    };

    /* These are the defined values for devid.devtype                   */
    /* (0 indicates an empty entry)                                     */

    /* Input devices */
    #define NULL_INPUT                 0
    #define STEREO_LINE_INPUT          1
    #define LEFT_LINE_INPUT            2
    #define RIGHT_LINE_INPUT           3
    #define MIC_INPUT                  4
    #define BOOSTED_MIC_INPUT          5
    #define PHONE_LINE_INPUT           6
    #define HANDSET_INPUT              7
    #define SYNTH_INPUT                8
    #define DIGITAL_PHONE_LINE_INPUT   9
    #define DIGITAL_HANDSET_INPUT      10
    #define MIDI_IN_PORT               11
    #define LOOPBACK                   12
    #define DEFAULT_INPUT              0xffffffff
    /* Values between 0x20000000 and 0xfffffffe are reserved */


    /* Output devices */
    #define NULL_OUTPUT                0
    #define STEREO_LINE_OUTPUT         1
    #define LEFT_LINE_OUTPUT           2
    #define RIGHT_LINE_OUTPUT          3
    #define SPEAKER_OUTPUT             4
    #define HEADPHONES_OUTPUT          5
    #define PHONE_LINE_OUTPUT          6
    #define HANDSET_OUTPUT             7
    #define SYNTH_OUTPUT               8
    #define DIGITAL_PHONE_LINE_OUTPUT  9
    #define DIGITAL_HANDSET_OUTPUT     10
    #define MIDI_OUT_PORT              11
    #define DEFAULT_OUTPUT             0xffffffff
    /* Values between 0x20000000 and 0xfffffffe are reserved */

    /* Defined values for devnum */
    #define DEFAULT_DEVICE      0
    #define DEVICE_1            1
    #define DEVICE_2            2
    #define etc.                ...


  Figure  2-7. devid structure


                                        Chapter 2.  Technical Description  2-16



    struct midi_info
    {
      short tempo;          /* Tempo in 1/10 beats per minute (nominally 120) */
      short cpqn;           /* Timing clocks per quarter note (nominally 96)  */
      short midi_switches;  /* Common MIDI switches                           */
      short reserved[5];  /* reserved for future use                          */
    };

    /* midi_switches definitions */
    #define MIDI_THRU_OUT  1  /* Configure MIDI-Thru connector as MIDI-Out    */
    #define MIDI_THRU_THRU 0  /* Configure MIDI-Thru connector as MIDI-Thru   */


  Figure  2-8. MIDI mode information structure  (pointed to by
               audio_change.mode_info)



    struct pcm_info
    {
      short pcmflags;       /* Control flags                           */
      short reserved[7];    /* reserved for future use                 */
    };

    /* pcmflags definitions */
    #define PCM_DEEMPHASIS 1  /* Enable Redbook deemphasis filter      */


  Figure  2-9. PCM mode information structure  (pointed to by
               audio_change.mode_info)





  AUDIO_START

  An AUDIO_START request in an AUDIO_CONTROL IOCTL operation starts the
  requested audio operation.  It initiates the flow of audio data to or from
  the adapter.  It will cause the internal position and timing values to be set
  to the value contained in audio_control.position.  Thus, an immediate call to
  AUDIO_BUFFER would return a position value equal to the
  audio_control.position value specified in the AUDIO_START.  The audio device
  must have been opened and initialized (via OPEN and AUDIO_INIT requests)
  before issuing AUDIO_START.  Otherwise an error will be returned.

  There is no request_info for the AUDIO_START operation.



                                        Chapter 2.  Technical Description  2-17

  AUDIO_STOP

  This operation stops the current activity in progress on the audio device.
  If the device was recording, for example, the recording activity would be
  stopped.  This operation does not change the current configuration (such as
  sampling rate, input source, etc.) of the device in any way.  It simply ter-
  minates the current operation.  Consequently, it also stops data flow between
  the device driver and the application.  Any data left in the buffers will be
  discarded.  (The write buffers can be drained via the AUDIO_WAIT request.
  See 2.6.6, "AUDIO_WAIT IOCTL" on page 2-20).  Note that the AUDIO_PAUSE oper-
  ation should be used instead of this call if the operation will need to be
  resumed at the point where it left off.

  The audio_control.position value is used to specify when the stop is to
  occur.  A value of zero, or less than the current position will result in the
  stop being executed immediately.

  There is no request_info for the AUDIO_STOP operation.



  AUDIO_PAUSE

  The AUDIO_PAUSE request is used to suspend all data flow between the applica-
  tion and the adapter.  It does not flush the kernel buffers or the adapter
  buffers.  All data flow ceases.  It can be resumed by the AUDIO_RESUME
  request.  If recording, data is lost during the time that the device driver
  is paused.

  The audio_control.position value is used to specify when the pause is to
  occur.  A value of less than the current position will result in an immediate
  pause.

  There is no request_info for the AUDIO_PAUSE operation.



  AUDIO_RESUME

  The AUDIO_RESUME request is used to resume the flow of data that was sus-
  pended by an AUDIO_PAUSE request.

  Note that an audio_control.position value of non-zero is not currently
  defined, and should not be used.

  There is no request_info for the AUDIO_RESUME operation.


                                        Chapter 2.  Technical Description  2-18

  2.6.4  AUDIO_BUFFER IOCTL

  The AUDIO_BUFFER IOCTL request can be used to determine the amount of data
  currently queued, the device driver internal queue sizes, and whether an
  overrun or underrun state has occurred.  If either state has occurred, its
  respective bit will be turned on in the field audio_buffer.flags.

  This call is used to return data from the device driver, and can not be used
  to pass data to the device driver.


  The amount of data is expressed as the number of bytes currently in the
  queues.  Note that the amount of queue data that this call returns is accu-
  rate only at the point in time that this value is determined.  The amount of
  queued data may be different at any other point in time.  If the size of the
  buffer contents can be represented as an amount of time, the amount of time
  represented by data in the buffers will be returned in the fields
  read_buf_time and write_buf_time.  If not, the values returned will be -1.
  To aid in determining the optimal size of the read and write kernel buffer
  queues, the maximum number of bytes that these queues have ever contained
  will be returned in read_buf_max and write_buf_max.


  struct audio_buffer
  {
    unsigned long flags;          /* indicates an error condition occurred    */
    unsigned long read_buf_size;  /* amount of data in read queue in bytes    */
    unsigned long write_buf_size; /* amount of data in write queue in bytes   */
    unsigned long read_buf_time;  /* amount of data in read queue in msecs    */
    unsigned long write_buf_time; /* amount of data in write queue in msecs   */
    unsigned long read_buf_max;   /* maximum number of bytes ever in read q   */
    unsigned long write_buf_max;  /* maximum number of bytes ever in write q  */
    unsigned long position;       /* time count since beginning of operation  */
    unsigned long position_type;  /* specifies the type of position units     */
    long     read_buf_cap;        /* capacity of read queue (-1 if variable)  */
    long     write_buf_cap;       /* capacity of write queue ( "       "   )  */
    long     request_buf_cap;     /* max number of requests that can be q'd   */
  };

  /* These are the possible error states that can be flagged in flags         */
  #define AUDIO_UNDERRUN  1
  #define AUDIO_OVERRUN   2

  /* These are the currently defined position_type values                     */
  #define POS_MSECS   0 /* Position units are in milliseconds since start     */
  #define MIDI_CLOCKS 1 /* Position units are in # of MIDI clocks since start */
  #define POS_BYTES   2 /* Position data is in bytes                          */
  #define SMPTE_24   24 /* Position corresponds with SMPTE 24 frames/seconds  */
  #define SMPTE_25   25 /* Position corresponds with SMPTE 25 frames/second   */
  #define SMPTE_30DF 29 /* Position corresponds with SMPTE 30 drop frame      */
  #define SMPTE_30   30 /* Position corresponds with SMPTE 30 frames/second   */


  Figure  2-10. audio_buffer structure


                                        Chapter 2.  Technical Description  2-19


  2.6.5  AUDIO_LOAD IOCTL

  If the audio_init.field has the LOAD_CODE bit set after an AUDIO_INIT
  request, the application must load the DSP code specified by the driver in
  audio_init.loadpath into a buffer, and then issue an AUDIO_LOAD request.  The
  audio_load.buffer field must point to the start of the buffer where the code
  has been loaded, and the field audio_load.size must be set to the number of
  bytes of loaded code (which is the size of the file).  The audio_load.flags
  field allows loading the file in multiple chunks.  To do this, the first
  chunk is written with the LOAD_START flag set, and the last chunk with the
  LOAD_END flag set.  All intermediate chunks have both flags cleared.  To load
  the file in a single chunk, both flags are set.  The first buffer written
  must be at least 128 bytes long.


  struct audio_load
  {
    char far      *buffer;        /* pointer to buffer containing DSP code    */
    unsigned long size;           /* size of DSP code in bytes                */
    unsigned long flags;          /* indicate start and end of operation      */
  };
  /* audio_load.flags definitions                                             */
  #define  LOAD_START 1           /* indicates that this is the 1st block     */
  #define  LOAD_END   2           /* indicates that this is the last block    */


  Figure  2-11. audio_load structure




  2.6.6  AUDIO_WAIT IOCTL

  The AUDIO_WAIT request can be used to suspend program operation until all
  previously written data has been played by the device.  The actual playing of
  audio data by the audio device can occur after the WRITE call has returned to
  the caller.  If the caller does not want to continue program execution until
  all data has been actually played by the device, it can issue the AUDIO_WAIT
  request.  Also, some audio devices play audio data in discrete blocks.  Data
  is not played unless at least a full blocks worth of data is available.  If
  less than a blocks worth of data remains to be played, AUDIO_WAIT can be
  called which will cause the audio device driver to pad the data with silence
  thus allowing it to be played.  (The amount of data in the buffers can be
  determined via the AUDIO_BUFFER request.  See 2.6.4, "AUDIO_BUFFER IOCTL" on
  page 2-19 for more information).


  AUDIO_WAIT does nothing if there have been no prior WRITE system calls or
  AUDIO_HPI ioctl.  In this case it returns immediately to the caller.

  There are no parameters for the AUDIO_WAIT IOCTL request.


                                        Chapter 2.  Technical Description  2-20


  2.6.7  AUDIO_HPI

  The AUDIO_HPI function provides several high performance interface functions.
  This call can also be used to increase the device drivers internal input &
  output buffer sizes.  This is needed in order to do the higher bandwidth
  audio modes.  Note that any buffers provided must be an even number of bytes
  in length.


  NOTE:  By default, the internal buffer sizes are usually 512 bytes.

  The application may provide the device driver with one or more blocks of its
  own memory to be used for buffering transmit and/or receive data by passing a
  pointer to an iobuf structure in fields newxbuf and newrbuf respectively.
  This capability also allows an application to add or remove its data directly
  to the input and output queues.  Up to 16 buffers may be provided for each
  transmit and receive.  Care must be taken when updating the buffer and
  pointers in iobuf to ensure that the audio device driver interrupt handler
  doesn't simultaneously access them.  This is done by setting the IOBUF_LOCK
  bit in iobuf.runflags when manipulating iobuf fields.

  Set iobuf.newxbuf and iobuf.newrbuf to NULL to cause the default internal
  buffers to be used.


  An address is returned in audio_hpi.ep which may be used to directly invoke
  audio device driver functions.  NULL is returned if this function isn't
  available in the current environment.


  The application may pass a callback routine address (DOS) or system semaphore
  handle (OS/2) in audio_hpi.cb.

  NOTE:  The DOS callback routine must be an interrupt routine (i.e. return
         with an IRET, not a RET instruction).  Care must also be taken not to
         re-enter DOS.  For example, the interrupt could occur in the middle of
         executing a DOS call.  Any call to DOS made in the callback routine
         would result in DOS being entered a second time, and probably crash
         the system.

  If not NULL, then this address will be called (DOS), or semaphore cleared
  (OS/2) based on the state of the CBDATA, CBBLOCK, CBIOBUF, and CBERROR flags
  in iobuf.runflags:

      CBDATA for each data byte sent to or received from the device.  Note that
      some devices transfer data to and from the host only in blocks, in which
      case this bit has the same effect as CBBLOCK.

      CBBLOCK for each complete block of data sent to or received from the
      device.


                                        Chapter 2.  Technical Description  2-21


      CBIOBUF for each time the entire IOBUF contents are sent to or received
      from the device.

      CBERROR for each time a device error is detected by the device.

      CBUNDERRUN for each time an underrun/overrun is detected by the device.

  This will continue until either the device is stopped or closed, or else this
  call is made again with audio_hpi.cb set to NULL.  The device interrupt rate
  generally corresponds with the position resolution returned in the
  audio_init.position_resolution field.


    struct audio_hpi
    {
      void (far * ep)();            /* pointer to direct call entry point       */
      void (far * cb)();            /* pointer to callback routine              */
      struct iobuf far *newxbuf;    /* pointer to new xmit buffer to use        */
      struct iobuf far *newrbuf;    /* pointer to new receive buffer to use     */
      unsigned short flags;         /*                                          */
    };


  Figure  2-12. audio_hpi structure


                                        Chapter 2.  Technical Description  2-22

  struct iobuf
  {
    unsigned long size;           /* total size in bytes of the data buffer(s)*/
    char far *head;               /* queue head pointer (data added here)     */
    char far *tail;               /* queue tail pointer (data removed here)   */
    unsigned int head_segnum;     /* Index # of buf[] that *head points into  */
    unsigned int tail_segnum;     /* Index # of buf[] that *tail points into  */
    unsigned long count;          /* total # of data bytes currently queued   */
    unsigned long position;       /* position counter                         */
    long     delay;               /* # pos units before the next i/o          */
    unsigned short runflags;      /* start/stop/pause bits                    */
    char far *pIobufPhys;         /* Reserved.  Application must not modify.  */
    long lock_handle;             /* Reserved.  Application must not modify.  */
    unsigned short num_buffers;   /* Number of buffers passed by app (1 - 16) */
    struct addrs {                /* array of ptrs describing buffers         */
       unsigned long length;      /* Size of this buffer (must be even!)      */
       char far *Virt;            /* User's virtual address                   */
       char far *Phys;            /* Reserved.  Application must not modify.  */
       long lock_handle;          /* Reserved.  Application must not modify.  */
    } buf[1];                     /* 1 to 16                                  */
  };
  /* iobuf.runflags equates  */
  #define  STARTED        1
  #define  PAUSED         2
  #define  WAS_RUNNING    4      /* Reserved                                  */
  #define  IOB_OVERRUN    0x20   /* Overrun has occurred.                     */
  #define  IOB_UNDERRUN   0x40   /* Underrun has occurred.                    */
  #define  CHAIN_BUFFERS  128    /* reserved.  Must be 0                      */
  #define  CBDATA         0x0100 /* callback every data event                 */
  #define  CBBLOCK        0x0200 /* callback every full data block            */
  #define  CBIOBUF        0x0400 /* callback every full iobuf                 */
  #define  CBERROR        0x0800 /* callback on i/o or device error           */
  #define  CBUNDERRUN     0x1000 /* callback if underrun/overrun occurs       */
  #define  PADIT          0x2000 /* Pad any partial blocks with silence       */
  #define  IOBUF_LOCK     0x8000 /* Set when updating IOBUF fields to prevent */
                                 /*  collision with device driver.            */


  Figure  2-13. iobuf structure



                                        Chapter 2.  Technical Description  2-23


      void  (far *iobuf.ep)(short funcid, void far *data, short len);

    /* Definitions for funcid */
    #define EP_READ      2
    #define EP_WRITE     3
    #define EP_INIT      4
    #define EP_STATUS    5
    #define EP_CONTROL   6
    #define EP_BUFFER    7
    #define EP_LOAD      8
    #define EP_WAIT      9
    #define EP_HPI      10
    #define EP_UPDATE   11

      Upon return AX will contain an error code, or 0 if successful


  Figure  2-14. High Performance Direct Call interface




  2.6.8  AUDIO_UPDATE

  This function has two purposes:

  1.  Condense the array of buffers.

      This is done by removing all the buffers that have been processed from
      the array of buffers in the IOBUF structure.


  2.  Add a buffer to the list. The address and length of the buffer will be
      passed down to the device driver in the audio_update structure (see
      structure description below).

    struct audio_update {
       char iobuf_type;             /* transmit/receive iobuf           */
       char far *buffer_address;    /* address of buffer to be added    */
       unsigned long buffer_length; /* length of buffer to be added     */
       unsigned short rc;           /* return code                      */
       void far *reserved;          /* future use                       */
    }

    /* audio_update.iobuf_type values */
    XMIT_IOBUF     0
    REC_IOBUF      1

    /* audio_update.rc values         */
    MAX_NUM_BUFFERS_REACHED    9
    UPDATE_GENERAL_FAILURE    10
    INVALID_BUFFER_LENGTH     11



                                        Chapter 2.  Technical Description  2-24


  In order to use this IOCTL, the application must use the high performance
  interface.  When the AUDIO_HPI call is made to the device driver, an IOBUF
  structure with the maximum number of buffers that will ever be present must
  be passed down. The iobuf->num_buffers should have the maximum number of
  buffers in it. Note that there is a limit of 16 buffers that can be present.

  The buffers passed down in the buffer array of the iobuf structure do not
  need to contain addresses to buffers. Any or all of the buffers may point to
  NULL addresses and have lengths of zero. The device driver will look through
  the list of the buffers and count the number of non-NULL buffers and set the
  iobuf->num_buffers to this number.  All internal variables will be initial-
  ized to allow access to that number of buffers, and another AUDIO_HPI call
  will need to be made if this number changes.

  When the AUIO_UPDATE call is made, it will first 'remove' all buffers in the
  current iobuf buffer array that have been processed.  It will recalculate the
  iobuf->num_buffers and the iobuf->size (the total of all the buffer lengths).
  Note that the buffer size must be an even number of bytes and must be less
  than 64K in length.

  If the iobuf being updated is for transmit, it is assumed that the buffer
  passed down is full of data to be played.  The iobuf->head pointer will be
  updated to point to the beginning of the buffer following the buffer just
  added to the chain. The iobuf->count will also be updated by the device
  driver to include this buffer of data.

  Note that if the AUDIO_UPDATE.BUFFER_ADDRESS is NULL, then this IOCTL will
  simply free up processed buffers and return.  By freeing up a buffer the
  device driver will UnLock it if it is locked and set the length to zero.


  The AUDIO_UPDATE.RC on exit will contain an error code if one of the DevHlp
  calls failed, or if the maximum number of buffers have already been queued
  (see valid rc values listed above).



  2.6.9  AUDIO_DIAG8_READ IOCTL

  This function is used to read a byte directly from an audio device.  It is
  intended to facilitate diagnostic operations.  It will return in field
  diag_regs8.data the byte read from the audio device port identified by
  diag_regs8.offset.


    struct diag_regs8 {
      unsigned char offset;
      unsigned char data;
    };


  Figure  2-15. diag_regs8 structure


                                        Chapter 2.  Technical Description  2-25


  2.6.10  AUDIO_DIAG8_WRITE IOCTL

  This function is used to write a byte directly to an audio device.  It is
  intended to facilitate diagnostic operations.  It will write the byte passed
  in field diag_regs8.data to the audio device port identified by
  diag_regs8.offset.


  Refer to Figure 2-15 on page 2-25 for a description of the diag_regs8 struc-
  ture.



  2.6.11  AUDIO_DIAG16_READ IOCTL

  This function is used to read a word directly from an audio device.  It is
  intended to facilitate diagnostic operations.  It will return in field
  diag_regs16.data the word read from the audio device port identified by
  diag_regs16.offset.


    struct diag_regs16 {
      unsigned char offset;
      unsigned short data;
    };


  Figure  2-16. diag_regs16 structure




  2.6.12  AUDIO_DIAG16_WRITE IOCTL

  This function is used to write a word directly to an audio device.  It is
  intended to facilitate diagnostic operations.  It will write the word passed
  in field diag_regs16.data to the audio device port identified by
  diag_regs16.offset.


  Refer to Figure 2-16 for a description of the diag_regs16 structure.


                                        Chapter 2.  Technical Description  2-26


  2.7  IOCTL EXAMPLES

  Examples of using IOCTL's to communicate with an Audio Device Driver are
  given in Figure 2-18 on page 2-28 for C programs running under OS/2, and
  Figure 2-19 on page 2-29 for MASM programs running under DOS.  Figure 2-17 on
  page 2-27 is a pseudocode listing showing how an application would record or
  playback audio data.


  +---------------------------------------------------------------------------+
  |                                                                           |
  |    Open audio device driver.                                              |
  |    If error opening driver:                                               |
  |        then abort with error message.                                     |
  |    Issue AUDIO_INIT IOCTL to set type of audio data to play/record        |
  |    If BESTFIT_PROVIDED flag set:                                          |
  |        check audio parameters returned by AUDIO_INIT IOCTL                |
  |        if returned parameters not acceptable:                             |
  |            then abort with message.                                       |
  |    If LOAD_CODE flag set:                                                 |
  |        load file name returned in loadpath and issue AUDIO_LOAD IOCTL.    |
  |                                                                           |
  |    Issue AUDIO_CONTROL CHANGE to initialize connections and control values|
  |                                                                           |
  |    If Recording:                                                          |
  |        Open new file to write audio data to                               |
  |        Issue AUDIO_CONTROL START IOCTL                                    |
  |        Do until stop key pressed:                                         |
  |            Issue AUDIO_BUFFER IOCTL to determine how much data available  |
  |              to read                                                      |
  |            Issue Read to get data                                         |
  |            Write data to file                                             |
  |            Do user interface or other stuff                               |
  |            End Do                                                         |
  |        Issue AUDIO_CONTROL STOP IOCTL (optional)                          |
  |                                                                           |
  |    Else if Playback:                                                      |
  |        Open file containing data to playback                              |
  |        Issue AUDIO_BUFFER IOCTL to determine size of buffers.             |
  |        Read data from file and write data to fill Audio DD buffer         |
  |        Issue AUDIO_CONTROL START IOCTL                                    |
  |        Do until end of file or stop key pressed:                          |
  |            Issue AUDIO_BUFFER IOCTL to determine free space in Audio DD   |
  |              buffer                                                       |
  |            Read data from file                                            |
  |            Write data to Audio DD to fill Audio DD buffer                 |
  |            Do user interface or other stuff                               |
  |            End Do                                                         |
  |        Issue AUDIO_CONTROL STOP IOCTL (optional)                          |
  |    Close data file                                                        |
  |    Close Audio DD                                                         |
  |                                                                           |
  |                                                                           |
  +---------------------------------------------------------------------------+
  Figure  2-17. Pseudocode example.  This example shows the general steps to
                interface with an audio device driver.


                                        Chapter 2.  Technical Description  2-27


  +---------------------------------------------------------------------------+
  |                                                                           |
  |   #define   INCL_DOSDEVICES                                               |
  |   #include  <os2.h>                                                       |
  |                                                                           |
  |   #include  <io.h>                                                        |
  |   #include  <audiodd.h>        /* Defines for flags, etc.               */|
  |                                                                           |
  |   init_adpcmv(Handle)                  /* Init to record ADPCM voice    */|
  |   HFILE Handle;                        /* Handle returned from DosOpen()*/|
  |   {                                                                       |
  |      struct audio_init buffer;         /* I/O Buffer (def'd in audiodd.h*/|
  |      USHORT rc;                                                           |
  |                                                                           |
  |      buffer.srate = 11025;             /* Set rate = Voice mode         */|
  |      buffer.bits_per_sample = 16;      /* 16 bits per sample            */|
  |      buffer.bsize = 576;               /* Size of Voice mode data block */|
  |      buffer.mode = ADPCM;              /* ADPCM mode                    */|
  |      buffer.channels = 1;              /* Mono                          */|
  |      buffer.flags = FIXED;             /* Fixed block size data         */|
  |      buffer.operation = RECORD;        /* Setup to do record operation  */|
  |      buffer.version_level = 0x01020000; /* Set our version level        */|
  |                                                                           |
  |      rc = DosDevIOCtl(&buffer, NULL, 0x40+AUDIO_INIT, 0x80, Handle);      |
  |                                                                           |
  |      if(rc) return(rc);                                                   |
  |   }                                                                       |
  |                                                                           |
  |                                                                           |
  +---------------------------------------------------------------------------+
  Figure  2-18. OS/2 AUDIO_INIT IOCTL example.  Under OS/2, IOCTL calls are
                made using the DosDevIOCTL function.


                                        Chapter 2.  Technical Description  2-28


  +---------------------------------------------------------------------------+
  |                                                                           |
  |       INCLUDE AUDIODD.INC         ; Audio DD equates                      |
  |                                                                           |
  |   ; Read the queue status using AUDIO_BUFFER IOCTL                        |
  |                                                                           |
  |   Handle  DW  ?                   ; Handle to open device (MIDIn$)        |
  |                                                                           |
  |   Buffer  equ this word           ; I/O Buffer                            |
  |   FLAGS           DD  0           ; Error condition flags                 |
  |   READ_BUF_SIZE   DD  0           ; # of bytes currently in receive queue |
  |   WRITE_BUF_SIZE  DD  0           ; # of bytes currently in xmit queue    |
  |   READ_BUF_TIME   DD  0           ; Amount of data in rec queue in msec's |
  |   WRITE_BUF_TIME  DD  0           ; Amount of data in xmit queue in msecs |
  |   READ_BUF_MAX    DD  0           ; Maximum number of bytes ever in read q|
  |   WRITE_BUF_MAX   DD  0           ; Maximum number of bytes ever in write |
  |   POSITION        DD  0           ; time count since beginning of operatio|
  |   POSITION_TYPE   DD  0           ; specifies the type of position units  |
  |   READ_BUF_CAP    DD  0           ; Capacity of receive q (-1 if variable)|
  |   WRITE_BUF_CAP   DD  0           ; Capacity of write q (-1 if variable)  |
  |   REQUEST_BUF_CAP DD  0           ; max number of requests that can be q'd|
  |                                                                           |
  |                                                                           |
  |   Query_Q_Status:                                                         |
  |       MOV AH,44H                  ; Function call - IOCTL                 |
  |       MOV AL,0CH                  ; Indicate generic IOCTL request        |
  |       MOV BX,Handle               ; Audio device handle (from prev OPEN)  |
  |       MOV CH,80H                  ; Generic IOCTL Category                |
  |       MOV CL,40H+AUDIO_BUFFER     ; Generic IOCTL Function ID             |
  |       MOV DX,Offset Buffer        ; DS:DX points to buffer                |
  |       INT 21H                     ; Issue request to DOS                  |
  |       JC  Error                   ; Error code in AX if C set             |
  |       ...                                                                 |
  |                                                                           |
  |                                                                           |
  +---------------------------------------------------------------------------+
  Figure  2-19. DOS IOCTL example.  Under DOS, IOCTL calls are made using INT
                21[H] function 44[H].



                                        Chapter 2.  Technical Description  2-29


  CHAPTER 3.  MUSICAL INSTRUMENT DIGITAL INTERFACE (MIDI)

  This section describes the additional features offered by Audio Device
  Drivers for IBM Personal Computers while operating in MIDI mode.



  3.1  INTRODUCTION

  MIDI, the Musical Instrument Digital Interface, is a communication protocol
  tailored for the transmission of real-time musical performance data and is
  widely accepted by the music industry.  MIDI represents a musicians actions,
  not the sound produced by a musical instrument.  MIDI defines the bits and
  bytes that describe musical events.  Some examples are:

      The pressing and releasing of a key (beginning and end of a note)

      Pitch-bend (for example, the portamento effect produced by a trombone)

      Volume pedal movements

      etc.

  Although initially conceived to connect music keyboards and electronic sound
  devices together, it is now commonly used to connect these same devices to a
  computer.


  MIDI events can be written to a computer file for later playback.  MIDI
  defines a common format for such a file, called a Standard MIDI File.

  The recent addition of the General MIDI Mode to the MIDI specification will
  allow MIDI files to be portable across different manufacturer's synthesizers.



  3.2  MIDI EVENT TIMING

  One of the trickier aspects of most MIDI applications is timing.  Precise
  timing is required for turning notes on at just the right instance, as well
  as determining how long to leave the note on.  Timing probably accounts for
  the majority of hardware dependencies and differences between applications
  and system environments.

  In the Audio Device Drivers for IBM Personal Computers, MIDI timing support
  is provided via a time counter variable, and optionally by System Real Time
  (F8[H]) Timing Clock messages imbedded within the MIDI data.  System Exclu-
  sive messages are available to control generation of timing data.


                   Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-1




  By default, audio device drivers will generate no timing information.



  3.2.1  MIDI OUTPUT SYNCHRONIZATION

  MIDI Output Synchronization is used to simplify MIDI playback functions.
  Blocks of MIDI data may be written to a device driver with timing data
  imbedded within it.  Normal MIDI events will be processed immediately.  When
  a timing event is encountered (such as an F8[H] System Real Time Timing
  Clock), the device driver will wait until the next Timing Clock that is
  internally generated before processing any subsequent data.  Thus, the record
  and playback of MIDI data can be performed almost entirely by the audio
  device driver.  This function can be enabled or disabled via the Timing Gen-
  eration Control system exclusive message (See "Timing Generation Control" on
  page 3-4).



  3.2.2  MIDI SYSTEM REAL TIME MESSAGE

  MIDI System Real Time messages provide a clocking mechanism based on tempo.
  24 Timing Clocks per quarter note are generated by the device driver, and
  placed into the MIDI IN (Read) queue.  At a tempo of 120 bpm in 4/4 time, the
  device driver will generate 48 timing clocks per second (refer to
  Figure 3-1).

  +---------------------------------------------------------------------------+
  |                                                                           |
  |    Tempo of 120 beats per minute = 2 beats per second                     |
  |    4/4 time = 1 beat per quarter note                                     |
  |    2 beats per second * 24 clocks per quarter note = 48 clocks per second |
  |                                                                           |
  +---------------------------------------------------------------------------+
  Figure  3-1. Calculating the frequency of MIDI timing clocks.  Timing clocks
               are generated based on tempo and clocks per quarter note.

  For applications requiring more or less accuracy, the device driver can be
  instructed via a system exclusive message (see "Timing Generation Control" on
  page 3-4) to produce from 1/16 to 1536 Timing Clocks per quarter note
  (resulting in from 1/8 to 3072 timing clocks per second as opposed to 48 in
  the example above).  To prevent the input queue from becoming full, multiple
  consecutive Real Time messages can be converted into a single System Exclu-
  sive message.  This message includes a count of the number of Real Time mes-
  sages received between any other type of message.  For example, a sample
  librarian may take up to a minute or more to upload a sample to a sampling
  keyboard.  During this time, thousands of Real Time Messages could be
  received, which could cause the receive buffer to become full.  This could
  cause an acknowledgement message from the sampling keyboard to be lost.  This
  function is controlled via the Timing Generation Control system exclusive
  message (See "Timing Generation Control" on page 3-4).


                   Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-2



  3.3  MIDI SYSTEM EXCLUSIVE MESSAGES

  Nearly every function provided by an Audio device driver while in MIDI mode
  can be controlled by the application using System Exclusive messages.



  3.3.1  GENERAL FORMAT OF IBM SYSTEM EXCLUSIVE MESSAGES

       Timing Compression (long):   F0  00 00 3A  01  lsb  msb  F7
       Sound Generator Commands:    F0  00 00 3A  02  unit  cmd  chan ...  F7
       Device Driver Commands:      F0  00 00 3A  03  cmd  ...  F7
       Device Driver Query:         F0  00 00 3A  04  qid  F7
       Device Driver Response:      F0  00 00 3A  05  qid  data F7
       Timbre Parameter:            F0  00 00 3A  06  cmd  hh mm ll ... F7
       Timing Compression (short):  F0  00 00 3A  07-7F  F7


  3.3.2  TIMING COMPRESSION MESSAGES


  3.3.3  TIMING COMPRESSION

  These messages are used to compress sequential Timing Clocks (F8[H]) into a
  single System Exclusive message.  Up to 16,383 'F8[H]' Timing Clocks can be
  compressed into a single 6 or 8 byte message.  This message can be written to
  a device driver to cause a delay between output events if Output Synchro-
  nizing is enabled (see "Timing Generation Control" on page 3-4).

       F0  00 00 3A  01  ll  mm  F7  (Long version)
       F0  00 00 3A  nn  F7          (Short version)

       ll = number of System Real Time Timing Clocks LSB
       mm = number of System Real Time Timing Clocks MSB
       nn = number of System Real Time Timing Clocks (nn = 7 through 127)

       The short version may be used to represent durations of from 7 to 127
       clocks.  More than that may be represented using the long version.
       In the long version, the number of timing clocks that have occurred
       is calculated by combining the low 7 bits of mm with the low 7 bits
       of ll to produce a single 16 bit value:

           0mmm mmmm + 0lll llll = 00mm mmmm mlll llll



  3.3.4  DEVICE SPECIFIC SYSTEM EXCLUSIVE MESSAGES


                   Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-3


  3.3.5  DEVICE SPECIFIC

  These messages are device specific.  Although not a part of the Audio Device
  Drivers architecture, they are included here for lack of a better place (for
  the time being).  The 6th MIDI byte identifies the specific IBM device being
  addressed as listed:

  1.  M-ACPA (IBM Audio Capture & Playback Adapter)


  M-ACPA Front Panel Controls


  Program Change Enable


       F0  00 00 3A  02  01  01  ee  00  F7

       ee = Program Changes enable (0 = disabled, 1 = enabled; default)


  This message instructs the M-ACPA Synthesizer to either honor or ignore MIDI
  Program Change messages (Cn[H]).  By default, program changes are honored.
  This message does not affect voice change system exclusives, which are always
  honored.



  3.3.6  DEVICE DRIVER CONTROL SYSTEM EXCLUSIVE MESSAGES


  Timing Generation Control

  This message tells the device driver what timing information to generate.  By
  default, device drivers utilize real time messages at a rate of 24 per
  quarter note (beat) and 120 beats per minute internally for performing output
  synchronization, but will not queue timing clocks to either MIDI-Out or
  MIDI-In (read data).




                   Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-4


       F0  00 00 3A  03  01  tt  pp  00  F7

       tt = System Real Time control flags (default 08H)
            0x1x xxxx  Output Timing Clocks to MIDI-Out
            0x0x xxxx  Do not output Timing Clocks to MIDI-Out (default)
            0xx1 xxxx  Merge Timing Clocks with MIDI-In
            0xx0 xxxx  Do not pass Timing Clocks to MIDI-In (default)
            0xxx 1xxx  Synchronize Output to Timing Clocks (default)
            0xxx 0xxx  Disable Output Synchronization
            0xxx x1xx  Perform timing data compression
            0xxx x0xx  Disable timing data compression (default)
            0xxx xxRR  Reserved bits - always 0

       pp = System Real Time 24 CPQN Rate prescaler
            00dd dddd  Multiply by dddddd+1 (1 to 64) for 24 to 1536 ppq
            01dd dddd  Divide by dddddd+1 * 3 (3 to 192) for 8 to 1/8 ppq



  Tempo Control


       F0  00 00 3A  03  02  tl  tm  dd  F7

       tl = Tempo lsb
       tm = Tempo msb
       dd = duration


  This message sets the tempo for System Real Time Timing Clock generation.
  Tempo is expressed as 1/10 beats per minute.  The duration specifies how long
  it takes to gradually go from the current tempo to the specified tempo.
  Duration is specified in 1/10 seconds.  For example, to set the tempo to 120
  beats per minute, with duration set to 0 to make the new tempo effective
  immediately, the Tempo Control message would be:

        120 bpm = 1200 1/10 increments
                  1200 decimal = 00000100 10110000 binary
                  7 bit msb (tm) = 000100 1        = hex 9
                  7 bit lsb (tl) =         0110000 = hex 30

              F0  00 00 3A 03 02 30 09 00 F7


  Generic Sound Selection


       F0  00 00 3A  03  03  ii  tt  ss  F7

       ii = Instrument number
       tt = Sound type (0 = Musical instrument, 1 = sound effects)
       ss = Sound ID




                   Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-5




  This message selects the generic sound for an instrument.  There are 128
  generic musical instrument sounds, and 128 effects type sounds.  In cases
  where a requested sound isn't available on a device, the nearest available
  sound is used.


  Note that this message is left over from before General MIDI Mode.  It is
  recommended that General MIDI Mode be used instead of this message.



  Volume Control


       F0  00 00 3A  03  07  vv  dl  dm  F7

       vv = Volume (0-7F)
       dl = Duration lsb
       dm = Duration msb


  This message sets the volume level for the Audio device driver.  Volume is
  specified as a relative value from 0-7F.  The duration specifies how long it
  takes to gradually go from the current level to the target level.  Duration
  is specified in 1/10 seconds.  For example, to set the volume to maximum
  (7F), with duration set to 0 to make the new volume effective immediately,
  the Volume Control message would be:


              F0  00 00 3A 03 07 7F 00 00 F7

  This message will cause subsequent MIDI volume control change messages to be
  generated, and any subsequent volume control change messages encountered to
  be scaled proportionately.  Actual volume is the product of Volume and Master
  Volume.



  Balance Control


       F0  00 00 3A  03  08  bl  dl  dm  F7

       bb = Balance level (0 = full left, 40 = middle, 7F = full right)
       dl = Duration lsb
       dm = Duration msb


  This message sets the balance level for the Audio device driver.  Balance is
  specified as a relative value from 0-7F, where 0 is full left, 40 is middle,
  7F is full right.  The duration specifies how long it takes to gradually go
  from the current level to the target level.  Duration is specified in 1/10


                   Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-6



  seconds.  For example, to set the balance to full right (7F), with duration
  set to 10 to make the new balance move gradually to the right over a 1 second
  period, the Balance Control message would be:


              F0  00 00 3A 03 08 7F 0A 00 F7


  Master Volume Control


       F0  00 00 3A  03  09  vl  vm  00  F7

       vl = Master Volume lsb
       vm = Master Volume msb


  This message sets the master volume level for the Audio device driver.
  Master volume is intended to allow immediate control of overall volume,
  without interfering with the current volume setting as set by the Volume
  Control, described in "Volume Control" on page 3-6.  Volume is specified as a
  relative value from 0-3FFF.  For example, to set the volume to maximum (3FFF)
  the Master Volume Control message would be:


              F0  00 00 3A 03 09 7F 7F 00 F7

  This message will cause a MIDI volume control change message to be generated,
  and any subsequent volume control change messages encountered to be scaled
  proportionately.  Actual volume is the product of Volume and Master Volume.



  3.3.7  DEVICE DRIVER QUERY SYSTEM EXCLUSIVE MESSAGES


  Query Device Capability message


       F0 00 00 3A  04  01  F7


  This message is issued to a device driver by an application to request the
  basic capability of a device driver.  The device driver will respond to this
  message by returning a 'Query Response message' (see "Device Capability
  Response message" on page 3-8).



  Query Output Queue Size message


       F0 00 00 3A  04  02  F7



                   Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-7




  This message is issued to a device driver by an application to request the
  size of the output queue.  The device driver will respond to this message by
  returning a 'Queue Size Response message' (see "Queue Size Response
  message").



  Query Device ID message


       F0 00 00 3A  04  04  F7


  This message is issued to a device driver by an application to request the
  identity of the device driver.  The device driver will respond to this
  message by returning a 'Device ID Response message' (see "Device ID Response
  message" on page 3-9).  which will identify the device.



  3.3.8  DEVICE DRIVER RESPONSE SYSTEM EXCLUSIVE MESSAGES


  Device Capability Response message


       F0 00 00 3A  05  01  ii mm 00 F7

       ii = number of sound generators (instruments)

       mm = MIDI capability flags
          01xx xxxx MIDI Input is supported
          0x1x xxxx MIDI Output is supported
          0xx1 xxxx System Real Time Timing Clocks are supported


  This message is sent by a device driver in response to a 'Query Device Capa-
  bility message' (see "Query Device Capability message" on page 3-7).  It will
  indicate the basic MIDI capability of the device driver.



  Queue Size Response message


                   Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-8


       F0 00 00 3A  05  02  ll mm 00 F7

       ll = lower 7 bits of queue size
       mm = upper 7 bits of queue size
       (Queue Size in bytes = 00mm mmmm mlll llll)

       For example, if the device drivers output queue is 512 bytes in
       length, then the returned data would be:

         F0 00 00 3A  05  02  00  04  00  F7


  This message is sent by a device driver in response to a 'Query Output Queue
  Size message' (see "Query Output Queue Size message" on page 3-7).  It will
  indicate the total output queue size in bytes.



  Device ID Response message


       F0 00 00 3A  05  04  b1 b2 b3 F7

       b1 = 1st byte of device ID
       b2 = 2nd byte of device ID
       b3 = 3rd byte of device ID


  This message is sent by a device driver in response to a 'Query Device ID
  message' (see "Query Device ID message" on page 3-8).  It will identify the
  device.  This is provided to allow applications to perform device unique
  operations (such as issuing device specific System Exclusive messages).
  Refer to Appendix F, "Supported Audio Device Drivers" on page F-1 for a list
  of devices and their identifiers.



  3.3.9  TIMBRE PARAMETER MESSAGES

  Timbre parameter messages are provided to allow interrogating and changing
  the parameters that control the timbre of a given voice.  Parameters are
  addressed using three 7 bit bytes (21 bits), allowing approximately 2 million
  parameters to be addressed.  In most cases, these parameters will be divided
  into such units as banks, voices, etc.  Parameter values are passed in 2 7
  bit bytes, allowing up to 14 bits per parameter.



  Query Timbre Parameter message



                   Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-9




       F0 00 00 3A  06  01  hh  mm  ll  F7

       hh = high 7 bits parameter #
       mm = middle 7 bits parameter #
       ll = low 7 bits parameter #


  This message is issued to a device driver by an application to request the
  current setting of a timbre parameter.  The device driver will respond to
  this message by returning a 'Timbre Parameter response message' (see "Timbre
  Parameter response message").



  Timbre Parameter response message


       F0 00 00 3A  06  02  hh mm ll dl dm F7

       hh = high 7 bits parameter #
       mm = middle 7 bits parameter #
       ll = low 7 bits parameter #
       dl = parameter data lsb (0-127)
       dm = parameter data msb


  This message is sent by a device driver in response to a 'Query Timbre Param-
  eter message' (see "Query Timbre Parameter message" on page 3-9).  It allows
  determining the current value of a timbre parameter.



  Set Timbre Parameter message


       F0 00 00 3A  06  03  hh mm ll dl dm F7

       hh = high 7 bits parameter #
       mm = middle 7 bits parameter #
       ll = low 7 bits parameter #
       dl = parameter data lsb (0-127)
       dm = parameter data msb


  This message is used to set or change a timbre parameter.



  Request Timbre Block message


                  Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-10


       F0 00 00 3A  06  04  hh  mm  00  F7

       hh = high 7 bits block #
       mm = middle 7 bits block #


  This message is issued to a device driver by an application to request a
  block of timbre data.  The device driver will respond to this message by
  returning a 'Timbre Block message' (see "Timbre Block message").



  Timbre Block message


       F0 00 00 3A  06  05  hh  mm  ll  < len >  F7

       hh = high 7 bits block #
       mm = middle 7 bits block #
       ll = length of 7 bit data
       < len > = variable length (7 bit) data block


  This message is issued by a device driver in response to a 'Request Timber
  Block' message (see "Request Timbre Block message" on page 3-10).  It allows
  transferring blocks of timbre data from the device driver to an application.



  Write Timbre Block message


       F0 00 00 3A  06  06  hh  mm  ll  < len >  F7

       hh = high 7 bits block #
       mm = middle 7 bits block #
       ll = length of 7 bit data
       < len > = variable length (7 bit) data block


  This message is issued to a device driver by an application to write a block
  of timbre data.



  3.4  GENERIC MIDI SOUNDS

  A set of generic sounds is defined to allow a degree of portability between
  different MIDI hardware sound generation devices (i.e. IMF and M-ACPA).
  These sounds can be selected via the Generic Sound System Exclusive message.
  There are 128 musical instrument sounds, and 128 sound effects defined.
  Refer to Appendix E, "Generic Sounds" on page E-1 for a list of the sounds
  and their respective sound identification numbers.


                  Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-11



  Note that this list of sounds pre-dates General MIDI Mode, and as such should
  be treated as being superseded by it.




                  Chapter 3.  Musical Instrument Digital Interface (MIDI)  3-12



  APPENDIX A.  COMPATIBILITY BETWEEN AUDIO DEVICE DRIVER VERSIONS


  As Audio Device Drivers evolve, it is expected that there will be changes
  made to the interface and data structures used.  In order to provide back-
  wards compatibility between drivers, the application can specify to the
  device driver at AUDIO_INIT time the version level of the Audio Device Driver
  that it was written to use.  This information is passed via the
  audio_init.version_level field.  The Audio Device Driver will use this infor-
  mation to ensure that it is compatible, and in some cases modify its behavior
  to conform with the applications level.



  A.1  CHANGES MADE BETWEEN DIFFERENT VERSION LEVELS


  A.1.1  VERSION .5

  This version level predates the existence of the audio_init.version_level
  field.  It is identified by audio_init.operation values of 1, 2, or 3.  All
  subsequent versions have the high order bit set in audio_init.operation.



  A.1.2  VERSION 1

  audio_init.version_level = 0x01000000.

  o   audio_init.operation high order bit always set.  #defines changed for
      PLAY, RECORD, and PLAY_AND_RECORD.
  o   audio_init.version_level field added to end of structure.
  o   audio_change.input_gain field added to end of structure.
  o   audio_change.mode_info field added after input_gain.
  o   midi_info structure added.


  A.1.3  VERSION 1 BUILD 3

  audio_init.version_level = 0x01000003.

  o   DEFAULT_INPUT and DEFAULT_OUTPUT added


  A.1.4  VERSION 1 BUILD 4

  audio_init.version_level = 0x01000004.



           Appendix A.  Compatibility between Audio Device Driver versions  A-1




  A.1.5  VERSION 1 BUILD 5

  audio_init.version_level = 0x01000005.



  A.1.6  VERSION 1 BUILD 6

  audio_init.version_level = 0x01000006.

  o   MIDI position is now returned in milliseconds instead of MIDI_CLOCKS


  A.1.7  VERSION 1 BUILD 7

  audio_init.version_level = 0x01000007.



  A.1.8  VERSION 1 BUILD 8

  audio_init.version_level = 0x01000008.

  o   Device drivers now check to see if the application is up level, and
      return an error for AUDIO_INIT call if it is.
  o   AUDIO_WAIT will not clear the IOB_UNDERRUN bit in the IOBUF->runflags
      when it first gets called in case any previous underruns occurred and
      have not been cleared. This insures that when IOB_UNDERRUN occurs it will
      be because the data transfer has been completed.


           Appendix A.  Compatibility between Audio Device Driver versions  A-2


  APPENDIX B.  IBM MIDI SYSTEM EXCLUSIVES SUMMARY


       Timing Compression:
         Multiple F8 (long) . . . . . . . . F0 00 00 3A 01 ll mm F7
         Multiple F8 (short)  . . . . . . . F0 00 00 3A nn F7

       Timing Control . . . . . . . . . . . F0 00 00 3A 03 01 tt pp mm F7
       Tempo Control. . . . . . . . . . . . F0 00 00 3A 03 02 ll mm dd F7
       Generic Sound Select . . . . . . . . F0 00 00 3A 03 03 ii tt ss F7
       Channel number & number of notes . . F0 00 00 3A 03 06 ii nn mm F7
       Volume Control . . . . . . . . . . . F0 00 00 3A 03 07 vl vm dd F7
       Balance Control  . . . . . . . . . . F0 00 00 3A 03 08 bl bm dd F7
       Master Volume Control  . . . . . . . F0 00 00 3A 03 09 vl vm 00 F7

       Device Query
         Query Basic Capabilities . . . . . F0 00 00 3A 04 01 F7
         Output Queue Size  . . . . . . . . F0 00 00 3A 04 02 F7
         Device ID  . . . . . . . . . . . . F0 00 00 3A 04 04 F7

       Device Driver Query Response
         Basic Capabilities response  . . . F0 00 00 3A 05 01 ii mm ff F7
         Output Queue Size  . . . . . . . . F0 00 00 3A 05 02 ll mm 00 F7
         Device ID  . . . . . . . . . . . . F0 00 00 3A 05 04 b1 b2 b3 F7

       Query Timbre parameter . . . . . . . F0 00 00 3A 06 01 hh mm ll F7
       Timbre parameter response  . . . . . F0 00 00 3A 06 02 hh mm ll dl dm F7
       Set Timbre parameter . . . . . . . . F0 00 00 3A 06 03 hh mm ll dl dm F7
       Request Timbre block . . . . . . . . F0 00 00 3A 06 04 hh mm 00 F7
       Timbre Block . . . . . . . . . . . . F0 00 00 3A 06 05 hh mm ll <len> F7
       Write Timbre Block . . . . . . . . . F0 00 00 3A 06 06 hh mm ll <len> F7



                           Appendix B.  IBM MIDI System Exclusives summary  B-1


  APPENDIX C.  MIDI MESSAGE SUMMARY


  The following is a summary of the MIDI message formats.  Note that the 2nd
  and 3rd bytes (if present) always have a zero in their high order bit posi-
  tion.


       x  = MIDI channel number (0-F[H])
       cc = Control #
       dd = 7 bit data
       kk = Key Number (0-127, 60 = Middle C)
       vv = Velocity value (0-127)
       ll = LSB data (low 7 bits)
       mm = MSB data (high 7 bits)
       pp = Pressure value (0-127)

      -- byte --
       1   2   3  Function          Description
      --  --  --  -------------     --------------------------------------
      8x  kk  vv  Note Off          Turn off a note
      9x  kk  vv  Note on           Turn on a note (vv = 0 turns note off)
      Ax  kk  pp  Key Pressure      After Touch data for a key
      Bx  cc  dd  Control Change    Set controller value (ie. mod wheel)
      Cx  dd  --  Program Change    Change program (or sound) to dd
      Dx  pp  --  Channel Pressure  After Touch for the channel
      Ex  ll  mm  Pitch Bend        Specify Pitch Wheel change
      F0  *   *   System Exclusive  Send device-dependent or global control data
      F1  nd  --  MTC quarter frame n=message type, d=value
      F2  ll  mm  Song Position     Set song position pointers
      F3  nn      Select Song       Select song nn
      F4  --  --  n/a               undefined
      F5  --  --  n/a               undefined
      F6  --  --  Tune Request      Request Analog synths to tune osc's
      F7  --  --  EOX               End of System Exclusive
      F8  --  --  Timing Clock      Clock sent at 24 (or 384) per quarter note
      F9  --  --  n/a               undefined
      FA  --  --  Start             Reset song to beginning, and start play
      FB  --  --  Continue          Begin play at current location
      FC  --  --  Stop              Stop play
      FD  --  --  n/a
      FE  --  --  Active Sensing
      FF  --  --  System Reset      Reset to Power On condition

  A detailed specification can be ordered from:

              International MIDI Association
                     5316 W. 57th st.
                  Los Angeles, CA 90056

                   &telephone. (213)649-6434


                                         Appendix C.  MIDI message summary  C-1



  APPENDIX D.  GENERAL MIDI VOICES


  General MIDI voices are selected using MIDI program change messages.

  +---------------------------------------------------------------------------+
  | Table  D-1. General MIDI sound grouping (all channels except 10)          |
  +------------------+--------------------------------------------------------+
  | PROG #           | INSTRUMENT GROUP                                       |
  +------------------+--------------------------------------------------------+
  | 1-8              | Piano                                                  |
  +------------------+--------------------------------------------------------+
  | 9-16             | Chromatic Percussion                                   |
  +------------------+--------------------------------------------------------+
  | 17-24            | Organ                                                  |
  +------------------+--------------------------------------------------------+
  | 25-32            | Guitar                                                 |
  +------------------+--------------------------------------------------------+
  | 33-40            | Bass                                                   |
  +------------------+--------------------------------------------------------+
  | 41-48            | Strings                                                |
  +------------------+--------------------------------------------------------+
  | 49-56            | Ensemble                                               |
  +------------------+--------------------------------------------------------+
  | 57-64            | Brass                                                  |
  +------------------+--------------------------------------------------------+
  | 65-72            | Reed                                                   |
  +------------------+--------------------------------------------------------+
  | 73-80            | Pipe                                                   |
  +------------------+--------------------------------------------------------+
  | 81-88            | Synth Lead                                             |
  +------------------+--------------------------------------------------------+
  | 89-96            | Synth Pad                                              |
  +------------------+--------------------------------------------------------+
  | 97-104           | Synth Effects                                          |
  +------------------+--------------------------------------------------------+
  | 105-112          | Ethnic                                                 |
  +------------------+--------------------------------------------------------+
  | 113-120          | Percussive                                             |
  +------------------+--------------------------------------------------------+
  | 121-128          | Sound Effects                                          |
  +------------------+--------------------------------------------------------+



                                          Appendix D.  General MIDI voices  D-1


  +---------------------------------------------------------------------------+
  | Table  D-2. General MIDI Instrument Sounds listing                        |
  +------------------+------------------+------------------+------------------+
  |Prg# Instrument   |Prg# Instrument   |Prg# Instrument   |Prg# Instrument   |
  +------------------+------------------+------------------+------------------+
  |  1. Acoustic Gran| 33. Acoustic Bass| 65. Soprano Sax  | 97. FX 1 rain    |
  |  2. Bright Acoust| 34. Elec Bass    | 66. Alto Sax     | 98. FX 2 sndtrk  |
  |  3. Electric Grnd| 35. Elec Bass    | 67. Tenor Sax    | 99. FX 3 crystal |
  |  4. Honky-tonk   | 36. Fretless Bass| 68. Baritone Sax | 100. FX 4 atmosp |
  |  5. Electric Pian| 37. Slap Bass 1  | 69. Oboe         | 101. FX 5 bright |
  |  6. Electric Pian| 38. Slap Bass 2  | 70. English Horn | 102. FX 6 goblin |
  |  7. Harpsichord  | 39. Synth Bass 1 | 71. Bassoon      | 103. FX 7 echoes |
  |  8. Clavi        | 40. Synth Bass 2 | 72. Clarinet     | 104. FX 8 sci-fi |
  |  9. Celesta      | 41. Violin       | 73. Piccolo      | 105. Sitar       |
  | 10. Glockenspiel | 42. Viola        | 74. Flute        | 106. Banjo       |
  | 11. Music Box    | 43. Cello        | 75. Recorder     | 107. Shamisen    |
  | 12. Vibraphone   | 44. Contrabass   | 76. Pan Flute    | 108. Koto        |
  | 13. Marimba      | 45. Tremolo Strng| 77. Blown Bottle | 109. Kalimba     |
  | 14. Xylophone    | 46. Pizz Strings | 78. Shakuhachi   | 110. Bag pipe    |
  | 15. Tubular Bells| 47. Orch Harp    | 79. Whistle      | 111. Fiddle      |
  | 16. Dulcimer     | 48. Timpani      | 80. Ocarina      | 112. Shanai      |
  | 17. Drawbar Organ| 49. String Ensmbl| 81. Lead 1 square| 113. Tinkle Bell |
  | 18. Perc Organ   | 50. String Ensmbl| 82. Lead 2 sawtth| 114. Agogo       |
  | 19. Rock Organ   | 51. SynthStrings | 83. Lead 3 callio| 115. Steel Drums |
  | 20. Church Organ | 52. SynthStrings | 84. Lead 4 chiff | 116. Wood block  |
  | 21. Reed Organ   | 53. Choir Aahs   | 85. Lead 5 chara | 117. Taiko Drum  |
  | 22. Accordion    | 54. Voice Oohs   | 86. Lead 6 voice | 118. Melodic Tom |
  | 23. Harmonica    | 55. Synth Voice  | 87. Lead 7 fifth | 119. Synth Drum  |
  | 24. Tango Accrdn | 56. Orchestra Hit| 88. Lead 8 bass  | 120. Rev Cymbal  |
  | 25. Acoustic Gtr | 57. Trumpet      | 89. Pad 1 new age| 121. Gtr Fret Ns |
  | 26. Acoustic Gtr | 58. Trombone     | 90. Pad 2 warm   | 122. Breath Noise|
  | 27. Electric Gtr | 59. Tuba         | 91. Pad 3 polysyn| 123. Seashore    |
  | 28. Electric Gtr | 60. Muted Trumpet| 92. Pad 4 choir  | 124. Bird Tweet  |
  | 29. Electric Gtr | 61. French Horn  | 93. Pad 5 bowed  | 125. Tele Ring   |
  | 30. Overdrvn Gtr | 62. Brass Section| 94. Pad 6 metalli| 126. Helicopter  |
  | 31. Distorted Gtr| 63. SynthBrass 1 | 95. Pad 7 halo   | 127. Applause    |
  | 32. Gtr harmonics| 64. SynthBrass 2 | 96. Pad 8 sweep  | 128. Gunshot     |
  +------------------+------------------+------------------+------------------+



                                          Appendix D.  General MIDI voices  D-2


  +---------------------------------------------------------------------------+
  | Table  D-3. General MIDI Percussion Note Mapping (channel 10)             |
  +------------------------+-------------------------+------------------------+
  | KEY  SOUND             | KEY  SOUND              | KEY  SOUND             |
  +------------------------+-------------------------+------------------------+
  |  35  Acoustic Bass Drum|  51  Ride Cymbal 1      |  67  High Agogo        |
  |  36  Bass Drum 1       |  52  Chinese Cymbal     |  68  Low Agogo         |
  |  37  Side Stick        |  53  Ride Bell          |  69  Cabasa            |
  |  38  Acoustic Snare    |  54  Tambourine         |  70  Maracas           |
  |  39  Hand Clap         |  55  Splash Cymbal      |  71  Short Whistle     |
  |  40  Electric Snare    |  56  Cow bell           |  72  Long Whistle      |
  |  41  Low Floor Tom     |  57  Crash Cymbal 2     |  73  Short Guiro       |
  |  42  Closed Hi Hat     |  58  Vibraslap          |  74  Long Guiro        |
  |  43  High Floor Tom    |  59  Ride Cymbal 2      |  75  Claves            |
  |  44  Pedal Hi-Hat      |  60  Hi Bongo           |  76  Hi Wood Block     |
  |  45  Low Tom           |  61  Low Bongo          |  77  Low Wood Block    |
  |  46  Open Hi-Hat       |  62  Mute Hi Conga      |  78  Mute Cuica        |
  |  47  Low-MidTom        |  63  Open Hi Conga      |  79  Open Cuica        |
  |  48  Hi Mid Tom        |  64  Low Conga          |  80  Mute Triangle     |
  |  49  Crash Cymbal 1    |  65  High Timbale       |  81  Open Triangle     |
  |  50  High Tom          |  66  Low Timbale        |                        |
  +------------------------+-------------------------+------------------------+


                                          Appendix D.  General MIDI voices  D-3


  APPENDIX E.  GENERIC SOUNDS


  Generic Sounds have been replaced with the new General MIDI mappings.
  (see "Generic Sound Selection" on page 3-5).


                                               Appendix E.  Generic Sounds  E-1


  APPENDIX F.  SUPPORTED AUDIO DEVICE DRIVERS


  The following tables list a number of available or potential Audio Device
  Drivers.  The "Device Driver Name and parameters" column lists the file name
  and parameters that are specified in the CONFIG.SYS file.  The 'n' parameter
  specifies the audio device number.  For example, specifying '1' will result
  in the device name being "AUDIO1$", whereas specifying '2' will result in the
  device name being "AUDIO2$".  The 'intlvl' parameter is used to specify the
  IRQ number used by the device.  The 'ioaddr' parameter is used to specify the
  port I/O address used by the device.  The 's' parameter is used to specify
  the size, in Kbytes, of the DMA buffer to be used by the device driver (1 -
  32).  The "Device ID" column lists the ID that is returned by the AUDIO_INIT
  IOCTL call (described in 2.6.1, "AUDIO_INIT IOCTL" on page 2-5), and the MIDI
  Device ID Sys-Ex (refer to "Device ID Response message" on page 3-9).


  F.1  DOS AUDIO DEVICE DRIVERS

  +---------------------------------------------------------------------------+
  | Table  F-1. DOS Audio Device Drivers (currently available, planned, or    |
  |             candidates).                                                  |
  +------------------+------------------+------------------+------------------+
  | DEVICE NAME      | DEVICE DRIVER    | DEVICE ID        | AVAILABLE OR     |
  |                  | NAME AND PARAME- |                  | PLANNED?         |
  |                  | TERS             |                  |                  |
  +------------------+------------------+------------------+------------------+
  | IBM Music        | IMFDD.SYS n      | 'IMF'            | Available        |
  | Feature          | intlvl           |                  |                  |
  +------------------+------------------+------------------+------------------+
  | IBM M-ACPA       | ACPADD.SYS n     | 'ACP'            | Available        |
  +------------------+------------------+------------------+------------------+
  | IBM PS/1         | PS1DD.SYS        | 'PS1'            | Available        |
  +------------------+------------------+------------------+------------------+
  | Sound Blaster    | SNDBDD.SYS n     | 'SB '            | Available        |
  |                  | intlvl ioaddr s  |                  |                  |
  +------------------+------------------+------------------+------------------+
  | Roland MPU-401   | MPUDD.SYS n      | 'MPU'            | Available        |
  | and compatibles  | intlvl           |                  |                  |
  +------------------+------------------+------------------+------------------+

  Source code for the MPUDD device driver is available from the author to
  assist in creating device drivers to support additional devices.  Other
  developers wishing to provide additional drivers to support their hardware
  should contact the author to obtain a unique Device ID.


  F.2  OS/2 AUDIO DEVICE DRIVERS


                               Appendix F.  Supported Audio Device Drivers  F-1


  +---------------------------------------------------------------------------+
  | Table  F-2. OS/2 Audio Device Drivers currently available, or candidates. |
  +------------------+------------------+------------------+------------------+
  | DEVICE NAME      | DEVICE DRIVER    | DEVICE ID        | AVAILABLE OR     |
  |                  | NAME AND PARAME- |                  | PLANNED?         |
  |                  | TERS             |                  |                  |
  +------------------+------------------+------------------+------------------+
  | IBM Music        | IMFDD2.SYS n     | 'IMF'            | Available        |
  | Feature          | intlvl           |                  |                  |
  +------------------+------------------+------------------+------------------+
  | IBM Audio        | ACPADD2.SYS n    | 'ACP'            | Available        |
  | Capture and      |                  |                  |                  |
  | Playback Adapter |                  |                  |                  |
  | for the PS/2     |                  |                  |                  |
  +------------------+------------------+------------------+------------------+
  | Sound Blaster    | SNDBDD2.SYS n    | 'SB '            | Available        |
  |                  | intlvl ioaddr s  |                  |                  |
  +------------------+------------------+------------------+------------------+
  | Roland MPU-401,  | MPUDD2.SYS n     | 'MPU'            | planned          |
  | Voyetra OP4000/1 | intlvl           |                  |                  |
  +------------------+------------------+------------------+------------------+

  Source code for the MPUDD2 device driver is available from the author to
  assist in creating device drivers to support additional devices.  Other
  developers wishing to provide additional drivers to support their hardware
  should contact the author to obtain a unique Device ID.



                               Appendix F.  Supported Audio Device Drivers  F-2


  APPENDIX G.  DEVICE SPECIFIC INFORMATION & CAPABILITIES





  G.1  ACPA SPECIFIC INFORMATION

  The following table lists the AUDIO_INIT parameters for the operating modes
  currently supported by the IBM M-Audio Capture & Playback Adaptor.



                 Appendix G.  Device specific information G-1 capabilities  G-1


  +---------------------------------------------------------------------------+
  | Table  G-1 (Page 1 of 2). ACPA AUDIO_INIT Parameters for currently sup-   |
  |                           ported modes                                    |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | DESCRIPTI|NMODE            | BITS| SAMPLE    | #   | BLOC| FLAGS          |
  |          |                 | PER | RATE      | CHAN|SSIZE|                |
  |          |                 | SAMP|E          |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | MIDI     | MIDI            | -   | -         | -   | -   | -              |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | AVC      | ADPCM           | 16  | 11025     | 1   | 576 | Fixed          |
  | Voice    |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | AVC      | ADPCM           | 16  | 22050     | 1   | 1128| Fixed          |
  | Music    |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | AVC      | ADPCM           | 16  | 22050     | 2   | 2256| Fixed          |
  | Stereo   |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | AVC High | ADPCM           | 16  | 44100     | 1   | 1128| Fixed          |
  | Quality  |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | PCM             | 8   | 8000,     | 1   | 560 | 0              |
  | PCM      |                 |     | 11025,    |     |     |                |
  |          |                 |     | 22050,    |     |     |                |
  |          |                 |     | 44100     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | PCM             | 8   | 8000,     | 2   | 560 | 0              |
  | PCM      |                 |     | 11025,    |     |     |                |
  | stereo   |                 |     | 22050,    |     |     |                |
  |          |                 |     | 44100     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 16 bit   | PCM             | 16  | 8000,     | 1   | 560 | TWOS_COMPLEMENT|
  | PCM mono |                 |     | 11025,    |     |     |                |
  |          |                 |     | 22050,    |     |     |                |
  |          |                 |     | 44100     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 16 bit   | PCM             | 16  | 8000,     | 2   | 560 | TWOS_COMPLEMENT|
  | PCM      |                 |     | 11025,    |     |     |                |
  | stereo   |                 |     | 22050,    |     |     |                |
  |          |                 |     | 44100     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | MU_LAW          | 8   | 8000,     | 1   | 560 | 0              |
  | mu-law   |                 |     | 11025,    |     |     |                |
  | mono     |                 |     | 22050,    |     |     |                |
  |          |                 |     | 44100     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | MU_LAW          | 8   | 8000,     | 2   | 560 | 0              |
  | mu-law   |                 |     | 11025,    |     |     |                |
  | stereo   |                 |     | 22050,    |     |     |                |
  |          |                 |     | 44100     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+

                 Appendix G.  Device specific information G-2 capabilities  G-2


  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | A_LAW           | 8   | 8000,     | 1   | 560 | 0              |
  | A-law    |                 |     | 11025,    |     |     |                |
  | mono     |                 |     | 22050,    |     |     |                |
  |          |                 |     | 44100     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | A_LAW           | 8   | 8000,     | 2   | 560 | 0              |
  | A-law    |                 |     | 11025,    |     |     |                |
  | stereo   |                 |     | 22050,    |     |     |                |
  |          |                 |     | 44100     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Claim    | CLAIM_HDWR      | -   | -         | -   | -   | -              |
  | Hardware |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Source   | SOURCE_MIX      | -   | -         | -   | -   | -              |
  | Mix      |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Speech   | SPV2BCPCM       | 16  | 14700     | -   | 426 | 0              |
  | Viewer/2 |                 |     |           |     | tx  |                |
  | BCPCM    |                 |     |           |     | /   |                |
  |          |                 |     |           |     | 426 |                |
  |          |                 |     |           |     | rx  |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Speech   | SPV2PCM         | 16  | 14700     | -   | 964 | 0              |
  | Viewer/2 |                 |     |           |     | tx  |                |
  | PCM      |                 |     |           |     | / 2 |                |
  |          |                 |     |           |     | rx  |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Speech   | SPV2NONE        | -   | -         | -   | 256 | -              |
  | Viewer/2 |                 |     |           |     | tx  |                |
  | Computa- |                 |     |           |     | /   |                |
  | tions    |                 |     |           |     | 138 |                |
  |          |                 |     |           |     | rx  |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | ADPCM XA | ADPCMXA         | 16  | 18900,    | 1   | 1304| 0              |
  | mono     |                 |     | 37800     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | ADPCM XA | ADPCMXA         | 16  | 18900,    | 2   | 1304| 0              |
  | stereo   |                 |     | 37800     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+


                 Appendix G.  Device specific information G-3 capabilities  G-3


  +---------------------------------------------------------------------------+
  | Table  G-2. M-ACPA misc. audio capabilities                               |
  +--------------------------------+----------+-------------------------------+
  | CAPABILITY                     | YES/NO   | COMMENTS                      |
  +--------------------------------+----------+-------------------------------+
  | Volume                         | Yes      |                               |
  +--------------------------------+----------+-------------------------------+
  | Volume Delay                   | Yes      |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance                        | Yes      |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance Delay                  | Yes      |                               |
  +--------------------------------+----------+-------------------------------+
  | Treble                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Bass                           | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Pitch                          | No       | Not with current DSP code     |
  +--------------------------------+----------+-------------------------------+
  | Input gain                     | No       | Not with current DSP code     |
  +--------------------------------+----------+-------------------------------+
  | Input                          | Yes      |                               |
  +--------------------------------+----------+-------------------------------+
  | Output                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Monitor                        | Yes      | Depends on mode selected      |
  +--------------------------------+----------+-------------------------------+

                 Appendix G.  Device specific information G-4 capabilities  G-4


  +---------------------------------------------------------------------------+
  | Table  G-3. M-ACPA I/O Connections                                        |
  +--------------------------------+----------+-------------------------------+
  | DEVICE NAME                    | NUMBER   | COMMENTS                      |
  |                                | SUP-     |                               |
  |                                | PORTED   |                               |
  +--------------------------------+----------+-------------------------------+
  | Line Inputs                    | 1 Stereo |                               |
  +--------------------------------+----------+-------------------------------+
  | Microphone Input               | 1 Mono   |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line Input               | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset Input                  | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth Input                    | 1        | When SYNTH mode selected      |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone Line input       | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Handset input          | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-In port                   | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Loop-Back input                | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Default Input                  |          | Line Input                    |
  +--------------------------------+----------+-------------------------------+
  | Line output                    | 1 Stereo |                               |
  +--------------------------------+----------+-------------------------------+
  | Speaker output                 | 1        | Always selected               |
  +--------------------------------+----------+-------------------------------+
  | Headphones output              | 1        | Same as speaker output        |
  +--------------------------------+----------+-------------------------------+
  | Phone Line output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset output                 | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth output                   | 8 note   | General MIDI                  |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone line output      | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital handset output         | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-Out port                  | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Default output                 |          | Line output                   |
  +--------------------------------+----------+-------------------------------+


                 Appendix G.  Device specific information G-5 capabilities  G-5


    struct track_info
    {
      unsigned short master_volume;  /* the master volume setting        */
      unsigned short dither_percent; /* 0-100 percent of a bit to dither */
      unsigned short reserved[3];  /* reserved for future use            */
    };


  Figure  G-1. M-ACPA track_info structure (pointed to by
               audio_change.dev_info)



    struct spv2_mode_info_struct
    {
      unsigned short pitch;               /* pitch setting               */
      unsigned short num_LPC_coeff;       /* number of LPC coefficients  */
      unsigned short rate_of_LPC;         /* LPC rate                    */
      unsigned short hamming_width;       /* hamming width               */
      unsigned short ret_signal;          /* return signal               */
      unsigned short slow_down;           /* slow down factor            */
    };


  Figure  G-2. Pointed to by audio_change.mode_info in SPV2 modes..  Speech
               Viewer/2 mode specific information


  G.2  PS1 SPECIFIC INFORMATION

  The following table lists the AUDIO_INIT parameters for the operating modes
  currently supported by the IBM PS1 Audio Adapter.

  +---------------------------------------------------------------------------+
  | Table  G-4. PS1 AUDIO_INIT Parameters for currently supported modes       |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | DESCRIPTI|NMODE            | BITS| SAMPLE    | #   | BLOC| FLAGS          |
  |          |                 | PER | RATE      | CHAN|SSIZE|                |
  |          |                 | SAMP|E          |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | MIDI     | MIDI            | -   | -         | -   | -   | -              |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | PCM             | 8   | 8000,     | 1   | 1   | 0              |
  | PCM      |                 |     | 11025     |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Claim    | CLAIM_HDWR      | -   | -         | -   | -   | -              |
  | Hardware |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+

                 Appendix G.  Device specific information G-6 capabilities  G-6


  +---------------------------------------------------------------------------+
  | Table  G-5. PS/1 misc. audio capabilities                                 |
  +--------------------------------+----------+-------------------------------+
  | CAPABILITY                     | YES/NO   | COMMENTS                      |
  +--------------------------------+----------+-------------------------------+
  | Volume                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Volume Delay                   | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance                        | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance Delay                  | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Treble                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Bass                           | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Pitch                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input gain                     | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Output                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Monitor                        | No       |                               |
  +--------------------------------+----------+-------------------------------+

                 Appendix G.  Device specific information G-7 capabilities  G-7


  +---------------------------------------------------------------------------+
  | Table  G-6. PS/1 I/O Connections                                          |
  +--------------------------------+----------+-------------------------------+
  | DEVICE NAME                    | NUMBER   | COMMENTS                      |
  |                                | SUP-     |                               |
  |                                | PORTED   |                               |
  +--------------------------------+----------+-------------------------------+
  | Line Inputs                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Microphone Input               | 1 Mono   |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line Input               | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset Input                  | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth Input                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone Line input       | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Handset input          | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-In port                   | 1        |                               |
  +--------------------------------+----------+-------------------------------+
  | Loop-Back input                | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Default Input                  |          | Mic Input                     |
  +--------------------------------+----------+-------------------------------+
  | Line output                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Speaker output                 | 1        | Internal                      |
  +--------------------------------+----------+-------------------------------+
  | Headphones output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset output                 | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth output                   | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone line output      | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital handset output         | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-Out port                  | 1        | 2nd connector is Out or Thru  |
  +--------------------------------+----------+-------------------------------+
  | Default output                 |          | Speaker output                |
  +--------------------------------+----------+-------------------------------+


  G.3  SOUND BLASTER DD SPECIFIC INFORMATION

  The following table lists the AUDIO_INIT parameters for the operating modes
  currently supported by the Sound Blaster AUDIODD Device Driver (SNDB).



                 Appendix G.  Device specific information G-8 capabilities  G-8

  +---------------------------------------------------------------------------+
  | Table  G-7. SNDB AUDIO_INIT Parameters for currently supported modes      |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Desc     | Mode            | Bits| SAMPLE    | #   | Blk | FLAGS          |
  |          |                 | per | RATE      | Ch's| Size|                |
  |          |                 | Smpl|           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | MIDI     | MIDI            | -   | -         | -   | -   | -              |
  | (not     |                 |     |           |     |     |                |
  | sup-     |                 |     |           |     |     |                |
  | ported   |                 |     |           |     |     |                |
  | yet)     |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | PCM             | 8   | variable: | 1   | var | 0e:            |
  | PCM      |                 |     | 3907 to   |     | base|                |
  |          |                 |     | 12000     |     | on  |                |
  |          |                 |     | record,   |     | room|                |
  |          |                 |     | 3907 to   |     | and |                |
  |          |                 |     | 23000     |     | DMA |                |
  |          |                 |     | play      |     | bfr |                |
  |          |                 |     |           |     | size|                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Claim    | CLAIM_HDWR      | -   | -         | -   | -   | -              |
  | Hardware |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+

  +---------------------------------------------------------------------------+
  | Table  G-8. SoundBlaster misc. audio capabilities                         |
  +--------------------------------+----------+-------------------------------+
  | CAPABILITY                     | YES/NO   | COMMENTS                      |
  +--------------------------------+----------+-------------------------------+
  | Volume                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Volume Delay                   | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance                        | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance Delay                  | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Treble                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Bass                           | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Pitch                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input gain                     | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Output                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Monitor                        | No       |                               |
  +--------------------------------+----------+-------------------------------+


                 Appendix G.  Device specific information G-9 capabilities  G-9

  +---------------------------------------------------------------------------+
  | Table  G-9. SoundBlaster I/O Connections                                  |
  +--------------------------------+----------+-------------------------------+
  | DEVICE NAME                    | NUMBER   | COMMENTS                      |
  |                                | SUP-     |                               |
  |                                | PORTED   |                               |
  +--------------------------------+----------+-------------------------------+
  | Line Inputs                    | 1 mono   |                               |
  +--------------------------------+----------+-------------------------------+
  | Microphone Input               | 1 Mono   |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line Input               | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset Input                  | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth Input                    | -        | Not with current driver       |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone Line input       | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Handset input          | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-In port                   | -        | Not with current driver       |
  +--------------------------------+----------+-------------------------------+
  | Loop-Back input                | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Default Input                  |          | Mic Input                     |
  +--------------------------------+----------+-------------------------------+
  | Line output                    | 1 mono   |                               |
  +--------------------------------+----------+-------------------------------+
  | Speaker output                 | 1        |                               |
  +--------------------------------+----------+-------------------------------+
  | Headphones output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset output                 | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth output                   | -        | Not with current driver       |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone line output      | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital handset output         | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-Out port                  | -        | Not with current driver       |
  +--------------------------------+----------+-------------------------------+
  | Default output                 |          | Line output                   |
  +--------------------------------+----------+-------------------------------+


  G.4  DIGISPEECH SPECIFIC INFORMATION

  The following table lists the AUDIO_INIT parameters for the operating modes
  currently supported by the DigiSpeech Audio Device Driver.


               Appendix G.  Device specific information G-10 capabilities  G-10

  +---------------------------------------------------------------------------+
  | Table  G-10. DigiSpeech AUDIO_INIT Parameters for currently supported     |
  |              modes                                                        |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | DESCRIPTI|NMODE            | BITS| SAMPLE    | #   | BLOC| FLAGS          |
  |          |                 | PER | RATE      | CHNS| SIZE|                |
  |          |                 | SAMP|E          |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | PCM             | 8   | 8000      | 1   | 1   | FOREGROUND     |
  | PCM      |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | MU_LAW          | 8   | 8000      | 1   | 1   | FOREGROUND     |
  | Mu-Law   |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | 8 bit    | A_LAW           | 8   | 8000      | 1   | 1   | FOREGROUND     |
  | A-Law    |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | CVSD     | CVSD            | 8   | 0=1800,   | 1   | 1   | 0              |
  |          |                 |     | 1=2400,   |     |     |                |
  |          |                 |     | 2=3000,   |     |     |                |
  |          |                 |     | 3=3600,   |     |     |                |
  |          |                 |     | 4=4200,   |     |     |                |
  |          |                 |     | 5=4800    |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | DigiSpeec| DSMM            | -   | -         | 1   | 1   | 0              |
  | Movie    |                 |     |           |     |     |                |
  | Mode     |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | DigiSpeec| DSSM            | 8   | -         | 1   | 1   | 0              |
  | Standard |                 |     |           |     |     |                |
  | Mode     |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Claim    | CLAIM_HDWR      | -   | -         | -   | -   | -              |
  | Hardware |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+


               Appendix G.  Device specific information G-11 capabilities  G-11


  +---------------------------------------------------------------------------+
  | Table  G-11. DigiSpeech misc. audio capabilities                          |
  +--------------------------------+----------+-------------------------------+
  | CAPABILITY                     | YES/NO   | COMMENTS                      |
  +--------------------------------+----------+-------------------------------+
  | Volume                         | Yes      |                               |
  +--------------------------------+----------+-------------------------------+
  | Volume Delay                   | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance                        | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance Delay                  | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Treble                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Bass                           | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Pitch                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input gain                     | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Output                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Monitor                        | No       |                               |
  +--------------------------------+----------+-------------------------------+



               Appendix G.  Device specific information G-12 capabilities  G-12


  +---------------------------------------------------------------------------+
  | Table  G-12. DigiSpeech I/O Connections                                   |
  +--------------------------------+----------+-------------------------------+
  | DEVICE NAME                    | NUMBER   | COMMENTS                      |
  |                                | SUP-     |                               |
  |                                | PORTED   |                               |
  +--------------------------------+----------+-------------------------------+
  | Line Inputs                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Microphone Input               | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line Input               | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset Input                  | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth Input                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone Line input       | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Handset input          | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-In port                   | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Loop-Back input                | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Default Input                  | none     |                               |
  +--------------------------------+----------+-------------------------------+
  | Line output                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Speaker output                 | 1        |                               |
  +--------------------------------+----------+-------------------------------+
  | Headphones output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset output                 | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth output                   | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone line output      | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital handset output         | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-Out port                  | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Default output                 |          | Speaker output                |
  +--------------------------------+----------+-------------------------------+


  G.5  MPU SPECIFIC INFORMATION

  The following table lists the AUDIO_INIT parameters for the operating modes
  currently supported by the MPUDD & MPUDD2 Audio Device Driver.


               Appendix G.  Device specific information G-13 capabilities  G-13


  +---------------------------------------------------------------------------+
  | Table  G-13. MPU AUDIO_INIT Parameters for currently supported modes      |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | DESCRIPTI|NMODE            | BITS| SAMPLE    | #   | BLOC| FLAGS          |
  |          |                 | PER | RATE      | CHNS| SIZE|                |
  |          |                 | SAMP|E          |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | MIDI     | MIDI            | -   | -         | -   | -   | -              |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Claim    | CLAIM_HDWR      | -   | -         | -   | -   | -              |
  | Hardware |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+

  +---------------------------------------------------------------------------+
  | Table  G-14. MPU misc. audio capabilities                                 |
  +--------------------------------+----------+-------------------------------+
  | CAPABILITY                     | YES/NO   | COMMENTS                      |
  +--------------------------------+----------+-------------------------------+
  | Volume                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Volume Delay                   | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance                        | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance Delay                  | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Treble                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Bass                           | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Pitch                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input gain                     | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Output                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Monitor                        | No       |                               |
  +--------------------------------+----------+-------------------------------+


               Appendix G.  Device specific information G-14 capabilities  G-14



  +---------------------------------------------------------------------------+
  | Table  G-15. MPU I/O Connections                                          |
  +--------------------------------+----------+-------------------------------+
  | DEVICE NAME                    | NUMBER   | COMMENTS                      |
  |                                | SUP-     |                               |
  |                                | PORTED   |                               |
  +--------------------------------+----------+-------------------------------+
  | Line Inputs                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Microphone Input               | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line Input               | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset Input                  | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth Input                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone Line input       | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Handset input          | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-In port                   | 1        |                               |
  +--------------------------------+----------+-------------------------------+
  | Loop-Back input                | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Default Input                  |          | MIDI-In port                  |
  +--------------------------------+----------+-------------------------------+
  | Line output                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Speaker output                 | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Headphones output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset output                 | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth output                   | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone line output      | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital handset output         | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-Out port                  | 1        | 2nd MIDI-Out or Thru          |
  +--------------------------------+----------+-------------------------------+
  | Default output                 |          | MIDI-Out port                 |
  +--------------------------------+----------+-------------------------------+


  G.6  IBM MUSIC FEATURE SPECIFIC INFORMATION

  The following table lists the AUDIO_INIT parameters for the operating modes
  currently supported by the IBM Music Feature Audio Device Drivers.



               Appendix G.  Device specific information G-15 capabilities  G-15


  +---------------------------------------------------------------------------+
  | Table  G-16. IMF AUDIO_INIT Parameters for currently supported modes      |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | DESCRIPTI|NMODE            | BITS| SAMPLE    | #   | BLOC| FLAGS          |
  |          |                 | PER | RATE      | CHNS| SIZE|                |
  |          |                 | SAMP|E          |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | MIDI     | MIDI            | -   | -         | -   | -   | -              |
  +----------+-----------------+-----+-----------+-----+-----+----------------+
  | Claim    | CLAIM_HDWR      | -   | -         | -   | -   | -              |
  | Hardware |                 |     |           |     |     |                |
  +----------+-----------------+-----+-----------+-----+-----+----------------+

  +---------------------------------------------------------------------------+
  | Table  G-17. IBM Music Feature misc. audio capabilities                   |
  +--------------------------------+----------+-------------------------------+
  | CAPABILITY                     | YES/NO   | COMMENTS                      |
  +--------------------------------+----------+-------------------------------+
  | Volume                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Volume Delay                   | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance                        | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Balance Delay                  | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Treble                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Bass                           | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Pitch                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input gain                     | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Input                          | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Output                         | No       |                               |
  +--------------------------------+----------+-------------------------------+
  | Monitor                        | No       |                               |
  +--------------------------------+----------+-------------------------------+


               Appendix G.  Device specific information G-16 capabilities  G-16




  +---------------------------------------------------------------------------+
  | Table  G-18. IBM Music Feature I/O Connections                            |
  +--------------------------------+----------+-------------------------------+
  | DEVICE NAME                    | NUMBER   | COMMENTS                      |
  |                                | SUP-     |                               |
  |                                | PORTED   |                               |
  +--------------------------------+----------+-------------------------------+
  | Line Inputs                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Microphone Input               | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line Input               | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset Input                  | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth Input                    | 1        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone Line input       | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital Handset input          | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-In port                   | 1        |                               |
  +--------------------------------+----------+-------------------------------+
  | Loop-Back input                | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Default Input                  |          | MIDI-In port                  |
  +--------------------------------+----------+-------------------------------+
  | Line output                    | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Speaker output                 | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Headphones output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Phone Line output              | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Handset output                 | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Synth output                   | 1        | 8 note polyphony              |
  +--------------------------------+----------+-------------------------------+
  | Digital Phone line output      | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | Digital handset output         | -        |                               |
  +--------------------------------+----------+-------------------------------+
  | MIDI-Out port                  | 1        |                               |
  +--------------------------------+----------+-------------------------------+
  | Default output                 |          | MIDI-Out port                 |
  +--------------------------------+----------+-------------------------------+


               Appendix G.  Device specific information G-17 capabilities  G-17



  APPENDIX H.   MPM/2 DEVICE DRIVER COMMANDS (IDC)


  The DDCmds are an interface used by a stream handler to communicate with a
  physical device driver. This interface uses the IDC (InterDevice communi-
  cation) mechanism provided by the OS/2 ATTACHDD DevHelp api. The stream
  handler must attach to the device driver using the ATTACHDD DevHelp to
  receive the DDCmd entry point address of the device driver. This must be done
  prior to issuing any DDCmds. Some device drivers may also require that a
  DosOpen() call be used to open the device driver before it can be used
  through the ATTACHDD entry point.

  The DDCmds are provided through a single entry point, DDCmdEntryPoint, which
  accepts a parameter structure on input.

         typedef RC (FAR *PSHDFN)        (PVOID pParmIn);
         typedef RC (FAR *PDDCMDFN)      (PVOID pParmIn);

  For the PDD interface, all pointers are 16:16 far pointers. This will allow
  the current 16 bit device driver model to be used for ring 0 Stream Handlers.
  The following list contains the function numbers for all DDCmds. It should be
  used in the ulFunction field of the Parameter structure passed on the call to
  indicate which function is being requested by the Stream Handler.

      0L    DDCMD_SETUP
      1L    DDCMD_READ
      2L    DDCMD_WRITE
      3L    DDCMD_STATUS
      4L    DDCMD_CONTROL
      5L    DDCMD_REG_STREAM
      6L    DDCMD_DEREG_STREAM


  H.1.1  DDCMD DEFINITIONS



                          Appendix H.   MPM/2 Device Driver Commands (IDC)  H-1


  H.2
  DDCMD_SETUP

  #define INCL_SPI

  +---------------------------------------------------------------------------+
  |                                                                           |
  | SHDENTRYPOINT  (PVOID PPARMIN)                                            |
  |                                                                           |
  +---------------------------------------------------------------------------+

  Perform device specific stream instance setup.


  H.2.1  PARAMETERS

  PPARMIN PVOID Input
      Pointer to input parameter block.

      Input structure:


             struct ParmIn {
                ULONG     ulFunction;           // Input - DDCMD command function
                HSTREAM   hstream;              // Input - Stream handle
                PVOID     pSetupParm;           // Input - ptr to device setup info
                ULONG     ulSetupParmSize;      // Input - buffer size
                }



  H.2.2  RETURNS

  Error code indicating success or type of failure:

  NO_ERROR                Function performed.
  ERROR_INVALID_FUNCTION  Illegal function requested.
  ERROR_INVALID_STREAM    Invalid stream handle.
  ERROR_INVALID_REQUEST   Invalid setup request.
  FAILURE                 Device driver specific error occurred - rc contains
                          error code.


  H.2.3  REMARKS

  This function will indicate to the device driver that a specific stream
  instance become the active stream instance. The pSetupParms field is used for
  device specific information.


  H.2.4  RELATED FUNCTIONS


                          Appendix H.   MPM/2 Device Driver Commands (IDC)  H-2


  H.3
  DDCMD_READ

  #define INCL_SPI

  +---------------------------------------------------------------------------+
  |                                                                           |
  | SHDENTRYPOINT  (PVOID PPARMIN)                                            |
  |                                                                           |
  +---------------------------------------------------------------------------+

  Perform a read from the device into a buffer.


  H.3.1  PARAMETERS

  PPARMIN PVOID Input/Output
      Pointer to input parameter block.

      Input structure:


             struct ParmIn {
                ULONG     ulFunction;           // Input - DDCMD command function
                HSTREAM   hstream;              // Input - Stream handle
                PVOID     pBuffer;              // Output - ptr read buffer
                ULONG     ulBufferSize;         // Input - buffer size
                }



  H.3.2  RETURNS

  Error code indicating success or type of failure:

  NO_ERROR                Function performed.
  ERROR_INVALID_FUNCTION  Illegal function requested.
  ERROR_INVALID_STREAM    Invalid stream handle.
  ERROR_INVALID_BLOCK     Invalid address passed in parameter block.
  ERROR_STREAM_NOT_ACTIVE Illegal request for an inactive stream.
  FAILURE                 Device driver specific error occurred - rc contains
                          error code.


  H.3.3  REMARKS

  Typically this function is used by a stream handler to give an "empty" buffer
  to the physical device driver. An example would be the case of audio
  recording, where the physical device driver fills the buffer it gets from the
  stream handler.  The pBuffer parameter is a pointer to the buffer to be
  filled in  by the physical device driver. Also, note that this pointer is
  either a physical 0:32 pointer, 16:16 far pointer or a global linear pointer.
  This is defined when the stream registers a stream with the device driver
  (DDCMD_REG_STREAM).


                          Appendix H.   MPM/2 Device Driver Commands (IDC)  H-3



  H.3.4  RELATED FUNCTIONS



                          Appendix H.   MPM/2 Device Driver Commands (IDC)  H-4




  H.4
  DDCMD_WRITE

  #define INCL_SPI

  +---------------------------------------------------------------------------+
  |                                                                           |
  | SHDENTRYPOINT  (PVOID PPARMIN)                                            |
  |                                                                           |
  +---------------------------------------------------------------------------+

  Perform a write from a buffer to the device.


  H.4.1  PARAMETERS

  PPARMIN PVOID Input
      Pointer to input parameter block.

      Input structure:


             struct ParmIn {
                ULONG     ulFunction;           // Input - DDCMD command function
                HSTREAM   hstream;              // Input - Stream handle
                PVOID     pBuffer;              // Input - ptr read buffer
                ULONG     ulBufferSize;         // Input - buffer size
                }



  H.4.2  RETURNS

  Error code indicating success or type of failure:

  NO_ERROR                Function performed.
  ERROR_INVALID_FUNCTION  Illegal function requested
  ERROR_INVALID_STREAM    Invalid stream handle
  ERROR_INVALID_BLOCK     Invalid address passed in parameter block.
  ERROR_STREAM_NOT_ACTIVE Illegal request for an inactive stream.
  FAILURE                 Device driver specific error occurred - rc contains
                          error code.


  H.4.3  REMARKS

  Typically this function is used by a stream handler to give a "full" buffer
  to the physical device driver. An example would be the case of audio play-
  back, where the stream handler passes a buffer with data to the physical
  device driver.

  The pBuffer parameter is a pointer to the data buffer.  Also, note that this
  pointer is either a physical 0:32 pointer, 16:16 far pointer or a global



                          Appendix H.   MPM/2 Device Driver Commands (IDC)  H-5



  linear pointer. This is defined when the stream registers a stream with the
  device driver (DDCMD_REG_STREAM).


  H.4.4  RELATED FUNCTIONS


                          Appendix H.   MPM/2 Device Driver Commands (IDC)  H-6



  H.5
  DDCMD_STATUS

  #define INCL_SPI

  +---------------------------------------------------------------------------+
  |                                                                           |
  | SHDENTRYPOINT  (PVOID PPARMIN)                                            |
  |                                                                           |
  +---------------------------------------------------------------------------+

  Request status from the device.


  H.5.1  PARAMETERS

  PPARMIN PVOID Input/Output
      Pointer to input parameter block.

      Input structure:


             struct ParmIn {
                ULONG     ulFunction;           // Input - DDCMD command function
                HSTREAM   hstream;              // Input - Stream handle
                PVOID     pStatus;              // Output - ptr Status buffer
                ULONG     ulStatusSize;         // Input/Output - buffer size
                }



  H.5.2  RETURNS

  Error code indicating success or type of failure:

  NO_ERROR                Function performed.
  ERROR_INVALID_FUNCTION  Illegal function requested
  ERROR_INVALID_STREAM    Invalid stream handle
  FAILURE                 Device driver specific error occurred - rc contains
                          error code.


  H.5.3  REMARKS

  The function is used to query the status of the physical device driver. This
  function may not be supported by all physical device drivers.


  H.5.4  RELATED FUNCTIONS



                          Appendix H.   MPM/2 Device Driver Commands (IDC)  H-7


  H.6
  DDCMD_CONTROL

  #define INCL_SPI

  +---------------------------------------------------------------------------+
  |                                                                           |
  | SHDENTRYPOINT  (PVOID PPARMIN)                                            |
  |                                                                           |
  +---------------------------------------------------------------------------+

  Perform a device specific command.


  H.6.1  PARAMETERS

  PPARMIN PVOID Input
      Pointer to input parameter block.

      Input structure:


             struct ParmIn {
                ULONG     ulFunction;           // Input - DDCMD command function
                HSTREAM   hstream;              // Input - Stream handle
                ULONG     ulCmd;                // Input - device control command
                PVOID     pParmIn;              // Input - ptr to parameters
                ULONG     ulParmInSize;         // Input - parameter block size
                }

             // ulCmd defines
             #define DDCMD_START       1
             #define DDCMD_STOP        2
             #define DDCMD_PAUSE       3
             #define DDCMD_RESUME      4



  H.6.2  RETURNS

  Error code indicating success or type of failure:

  NO_ERROR                Function performed.
  ERROR_INVALID_FUNCTION  Illegal function requested
  ERROR_INVALID_STREAM    Invalid stream handle
  ERROR_INVALID_SEQUENCE  Invalid device control command.
  ERROR_STREAM_NOT_ACTIVE Illegal request for an inactive stream.
  ERROR_INSUFF_BUFFER     Not enough buffer sent to device driver.
  FAILURE                 Device driver specific error occurred - rc contains
                          error code.



                          Appendix H.   MPM/2 Device Driver Commands (IDC)  H-8


  H.6.3  REMARKS

  This interface is similar to the DosDevIOCtl OS/2 call to device drivers. It
  is a generic interface that may or may not be used by any specific device
  driver. This function is also used to control the physical device driver.


  H.6.4  RELATED FUNCTIONS


                          Appendix H.   MPM/2 Device Driver Commands (IDC)  H-9


  H.7
  DDCMD_REG_STREAM

  #define INCL_SPI

  +---------------------------------------------------------------------------+
  |                                                                           |
  | SHDENTRYPOINT  (PVOID PPARMIN)                                            |
  |                                                                           |
  +---------------------------------------------------------------------------+

  Register a stream instance with a device driver.


  H.7.1  PARAMETERS

  PPARMIN PVOID Input
      Pointer to input parameter block.

      Input structure:


             struct ParmIn {
                ULONG     ulFunction;           // Input - DDCMD command function
                HSTREAM   hstream;              // Input - Stream handle
                ULONG     ulSysFileNum;         // Input - Device Handle so pdd can map
                                                //  device instance to hstream
                PSHDFN    pSHDEntryPoint;       // Input - Stream handler entry point
                ULONG     ulStreamOperation;    // Input - Record or play
                SPCBKEY   spcbkey;              // Input - stream data type key
                ULONG     ulBufSize;            // Output(optional) - transfer buffer size
                ULONG     ulNumBufs;            // Output(optional) - # buffers to transfer
                ULONG     ulAddressType;        // Output(required) - address ptr type
                ULONG     ulBytesPerUnit;       // Output(required) - Pdd timing
                MMTIME    mmtimePerUnit;        // Output(required) - Pdd timing
                }

             // ulStreamOperation  defines:
             #define STREAM_OPERATION_MASK   0xC000
             #define STREAM_OPERATION_CONSUME  0x8000
             #define STREAM_OPERATION_PRODUCE  0xC000

             // ulAddressType  defines:  (ptr type pdd expects)
             #define ADDRESS_TYPE_VIRTUAL    0L
             #define ADDRESS_TYPE_PHYSICAL   1L              //default
             #define ADDRESS_TYPE_LINEAR     2L



  H.7.2  RETURNS

  Error code indicating success or type of failure:

  NO_ERROR                Function performed.


                         Appendix H.   MPM/2 Device Driver Commands (IDC)  H-10

  ERROR_INVALID_FUNCTION  Illegal function requested
  ERROR_INVALID_STREAM    Invalid stream handle
  ERROR_HNDLR_REGISTERED  Stream had already been registered.
  ERROR_INVALID_REQUEST   Invalid request.
  ERROR_INVALID_SPCBKEY   Invalid spcbkey.
  FAILURE                 Device driver specific error occurred - rc contains
                          error code.


  H.7.3  REMARKS

  This allows the stream handler to register its entry point with the device
  driver. This must be done once for each stream instance.  It sets up the com-
  munication link between the stream handler and the physical device driver.


  H.7.4  RELATED FUNCTIONS


                         Appendix H.   MPM/2 Device Driver Commands (IDC)  H-11


  H.8
  DDCMD_DEREG_STREAM

  #define INCL_SPI

  +---------------------------------------------------------------------------+
  |                                                                           |
  | SHDENTRYPOINT  (PVOID PPARMIN)                                            |
  |                                                                           |
  +---------------------------------------------------------------------------+

  De-register a stream instance with a device driver.


  H.8.1  PARAMETERS

  PPARMIN PVOID Input
      Pointer to input parameter block.

      Input structure:


             struct ParmIn {
                ULONG     ulFunction;           // Input - DDCMD command function
                HSTREAM   hstream;              // Input - Stream Handle
                }



  H.8.2  RETURNS

  Error code indicating success or type of failure:

  NO_ERROR                Function performed.
  ERROR_INVALID_FUNCTION  Illegal function requested
  ERROR_INVALID_STREAM    Invalid stream handle
  FAILURE                 Device driver specific error occurred - rc contains
                          error code.


  H.8.3  REMARKS

  This function removes the communication link between the physical device
  driver and the stream handler for a particular stream instance.


  H.8.4  RELATED FUNCTIONS


                         Appendix H.   MPM/2 Device Driver Commands (IDC)  H-12


  H.9   STREAM HANDLER DEVICE HELPER FUNCTIONS

  The SHDs are provided through a single entry point, SHDmdEntryPoint, which
  accepts a parameter structure on input.  For the PDD interface, all pointers
  are 16:16 far pointers. This will allow the current 16 bit device driver
  model to be used for ring 0 Stream Handlers.  There is one SHD function. The
  function number should be used in the ulFunction field of the Parameter
  structure passed on the call to indicate which function is being requested by
  the Stream Handler.

      0L    SHD_REPORT_INT


  H.9.1  SHD DEFINITIONS


                         Appendix H.   MPM/2 Device Driver Commands (IDC)  H-13


  H.10
  SHD_REPORT_INT

  #define INCL_SPI

  +---------------------------------------------------------------------------+
  |                                                                           |
  | SHDENTRYPOINT  (PVOID PPARMIN)                                            |
  |                                                                           |
  +---------------------------------------------------------------------------+

  Report an interrupt occurred on the device.


  H.10.1  PARAMETERS

  PPARMIN PVOID Input
      Pointer to input parameter block.

      Input structure:


             struct ParamIn {
                ULONG     ulFunction;           // Input - SHD command function
                HSTREAM   hstream;              // Input - Stream handle
                PVOID     pBuffer;              // Input - Ptr to last used buffer
                ULONG     ulFlag;               // Input - Reason for interrupt
                ULONG     ulStatus;             // Input - Error return code or
                ULONG   ulStreamTime;           // Input - Stream time in milliseconds
                }                               //     # bytes read/written.

             // ulFlag defines:
             #define SHD_ERROR              0x80L
             #define SHD_READ_COMPLETE      1L
             #define SHD_WRITE_COMPLETE     2L



  H.10.2  RETURNS

  Error code indicating success or type of failure:

  NO_ERROR                Function performed.
  ERROR_INVALID_FUNCTION  Illegal function requested
  ERROR_INVALID_STREAM    Invalid stream handle
  ERROR_DEVICE_UNDERRUN   There was a device data underrun.
  ERROR_DEVICE_OVERRUN    There was a device data overrun.
  FAILURE                 Stream handler specific error occurred - rc contains
                          error code.



                         Appendix H.   MPM/2 Device Driver Commands (IDC)  H-14


  H.10.3  REMARKS

  This function is a mechanism for the physical device driver to perform the
  following:  Report real-time cue point events or status. To indicate that a
  buffer has been consumed or that a new buffer is needed for consumption.


  H.10.4  RELATED FUNCTIONS


                         Appendix H.   MPM/2 Device Driver Commands (IDC)  H-15



                         Appendix H.   MPM/2 Device Driver Commands (IDC)  H-16


  APPENDIX I.  NOTES ON DESIGNING A NEW AUDIO DEVICE DRIVER

  The Audio Device Drivers have been implemented using a single set of source
  code modules.  These modules are divided into 2 groups:

  1.  Device independent routines

  2.  Device specific routines

  When building a new audio device driver, a new device specific module is
  built, and linked in with the existing device independent modules.  This pro-
  vides several benefits over building each driver from scratch:

  1.  Simplifies design & development

  2.  Eases creation of device drivers for multiple environments.

  3.  Greatly enhances compatibility with all other drivers, since a good
      portion of the code will in fact be the same.

  4.  Simplifies future changes, which may only require a single change to a
      device independent module, instead of every device driver.

  If you are planning on writing an Audio Device Driver, please contact the
  author before proceeding any further in order to obtain the current source
  code modules, and to register a new device ID number (if needed).  Refer to
  the Audio Device Drivers for IBM Personal Computers Device Dependent Specifi-
  cation Version 1.0 document for detailed information about creating a new
  Audio Device Driver.



                 Appendix I.  Notes on designing a new Audio Device Driver  I-1


  GLOSSARY


  ACPA.  Audio Capture and Playback         programmable Digital Signal
  Adapter.  See "M-ACPA".                   Processor, and stereo CD quality D/A
                                            and A/D converters.
  AIX.  IBM's "Advanced Interactive
  Executive" Operating System.              IMF.  IBM Music Feature.

  API.  Application Program Interface.      MIDI.  Musical Instrument Digital
                                            Interface.
  BPM.  Beats per minute
                                            MMA.  MIDI Manufacturers Associ-
  CPQN.  Clocks per quarter note            ation.  These are the developers of
                                            the MIDI Specification.  They work
  DEVICE DRIVER.  A section of code         in conjunction with the JMSC.
  selectively linked into an operating
  system during IPL, and used to            MPU-IMC.  The microchannel version
  interface with installed devices.         of Roland's MPU-401.

  DOS.  Disk Operating System.              MPU-401.  Rolands industry standard
                                            MIDI interface adapter.
  IBM.  International Business
  Machines, Inc.                            MTC.  MIDI Time Code.

  ID.  Identification.                      MULTITIMBRAL..  The ability of a
                                            synthesizer to generate multiple
  IMA.  International MIDI Associ-          sounds at the same time, each with
  ation.  Distributor of the MIDI           different timbres.
  Specification.  Their address is
  5316 West 57th Street, Los Angeles,       MUSICAPI FORUM.  A publicly
  California 90056.  Their phone            appendable (forum) file on the IBM
  number is (213)649-MIDI.                  VM network tools disk IBMPC.  This
                                            disk is for IBM internal use only,
  IOCTL.  Input/Output Control.  A          and is not accessible outside of
  mechanism implemented by a device         IBM.
  driver for sending or receiving
  special control data to or from a         OS/2.  Operating System /2.
  device.
                                            PAN.  The Performing Arts Network is
  IPL.  Initial Program Load.  Refers       a Videotex information service dedi-
  to the loading of the operating           cated to the performing arts.  A lot
  system code after applying power to       of good music related dialog goes on
  the computer (or subsequently, in         here.  For more information about
  which case it is referred to as a         PAN, contact THE PAN NETWORK, P.O.
  "re-boot").                               box 162, Skippack, PA. 19474 U.S.A.
                                            (215)584-0300.  Tell Perry that Ron
  JMSC.  Japan MIDI Standards Council.      sent ya.

  M-ACPA.  Multimedia - Audio Capture       PATCH.  Used to describe the config-
  and Playback Adapter. It contains a       uration or programming of a

                                                                  Glossary  X-1


  synthesizer to produce a particular       standardize the software and user
  timbre.  This term dates back to          interfaces used in its products.
  when modular synthesizers used
  "patch cords" to interconnect sound       SMPTE.  Society of Motion Picture
  modules.                                  and Television Engineers.  Used in
                                            this document to refer to ANSI
  PC.  Personal Computer.  Used in          V98.12M-1981 time and control code
  this document to refer collectively       for video and audio tape.
  to the IBM Personal System/1 or the
  IBM Personal System/2.                    SOUND BLASTER.  An audio card by
                                            Creative Labs.  It contains an
  POLYPHONY.  The number of notes that      Ad-Lib compatible synthesizer and an
  can be generated by a synthesizer at      8-bit D/A converter.
  the same time.
                                            TIMBRE.  (pronounced 'tamber'), is
  PPQN.  Pulses Per Quarter Note            the name used to describe the
  (equivalent to CPQN)                      aspects that make a sound unique.

  PS/2.  IBM Personal System/2              VOICE.  The ability of a synthesizer
                                            to generate a sound.
  SAA.  IBM System Application Archi-
  tecture.  This is an architecture         WINDOWS.  Microsoft's Multi-tasking
  that IBM is developing in order to        Operating System


                                                                  Glossary  X-2


  INDEX


     +---+                                  Installing an Audio Device
     | A |                                   Driver  2-1
     +---+                                  IOCTL functions  2-4
                                               AUDIO_BUFFER  2-19
  ACPA                                         AUDIO_CONTROL  2-12
     AUDIO_INIT Parameters  G-1                   AUDIO_CHANGE  2-14
  audio_init                                      AUDIO_PAUSE  2-18
     BESTFIT_PROVIDED flag  2-5                   AUDIO_RESUME  2-18
     bits_per_sample field  2-6                   AUDIO_START  2-17
     bsize field  2-6                             AUDIO_STOP  2-18
     channels field  2-6                       AUDIO_DIAG16_READ  2-26
     description  2-5                          AUDIO_DIAG16_WRITE  2-26
     flags field  2-6                          AUDIO_DIAG8_READ  2-25
     LOAD_CODE flag  2-7                       AUDIO_DIAG8_WRITE  2-26
     mode field  2-6                           AUDIO_HPI  2-21
     position_resolution  2-7                  AUDIO_INIT  2-5
     srate field  2-6                          AUDIO_LOAD  2-20
     use in minimal device driver  2-3         AUDIO_STATUS  2-11
     version_level  2-7                        AUDIO_UPDATE  2-24
                                               AUDIO_WAIT  2-20

     +---+
     | D |                                     +---+
     +---+                                     | M |
                                               +---+
  DDCMD_CONTROL  H-8
  DDCMD_DEREG_STREAM  H-12                  MIDI  3-1
  DDCMD_READ  H-3                              DOS Device Drivers  F-1
  DDCMD_REG_STREAM  H-10                       Event Timing  3-1
  DDCMD_SETUP  H-2                                Default timing generation  3-1
  DDCMD_STATUS  H-7                            General MIDI Mode  3-1
  DDCMD_WRITE  H-5                             General MIDI Voices  D-1
  DigiSpeech                                   Generic Sound types  E-1
     AUDIO_INIT Parameters  G-10               Generic Sounds  3-11
                                               IBM System Exclusive
                                                Messages  3-3
     +---+                                     IBM System Exclusives
     | I |                                        Balance Control  3-6
     +---+                                        Device Capability Response
                                                   message  3-8
  IMF                                             Device Driver Control  3-4
     AUDIO_INIT Parameters  G-15                  Device ID Response
  Installation                                     message  3-9
                                                  Generic Sound Selection  3-5
                                                  M-ACPA Front Panel
                                                   Controls  3-4


                                                                     Index  X-3


  MIDI (continued)                             +---+
     IBM System Exclusives (continued)         | S |
        M-ACPA Program Change                  +---+
         Enable  3-4
        Master Volume Control  3-7          Scenarios
        Query /Device ID message  3-8       Serializing access to audio
        Query Device Capability              hardware  2-3
         message  3-7                       SHD_REPORT_INT  H-14
        Query Output Queue Size             Sound Blaster DD
         message  3-7                          AUDIO_INIT Parameters  G-8
        Query Timbre Parameter              Specialized Audio Device
         message  3-10                       Drivers  2-3
        Queue Size Response
         message  3-9
        Request Timbre Block                   +---+
         message  3-11                         | V |
        Set Timbre Parameter                   +---+
         message  3-10
        Summary  B-1                        Version level  2-7
        Tempo Control  3-5
        Timbre Block message  3-11
        Timbre Parameter response              +---+
         message  3-10                         | W |
        Timing Control  3-4                    +---+
        Volume Control  3-6
        Write Timbre Block                  Writing a new audio device
         message  3-11                       driver  I-1
     messages summary  C-1
     OS/2 Device Drivers  F-2
     Output Synchronization  3-2
     Standard MIDI files  3-1
     System Exclusive Messages  3-3
     System Real Time messages  3-2
  Minimum Audio Device Drivers  2-3
  MPU
     AUDIO_INIT Parameters  G-13
  Multitasking of audio
   applications  2-3


     +---+
     | P |
     +---+

  PS1
     AUDIO_INIT Parameters  G-6


                                                                     Index  X-4
