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 | | | | #include | | #include /* 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 F7 Write Timbre Block . . . . . . . . . F0 00 00 3A 06 06 hh mm ll 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