Miles Sound System SDK 7.2a

VDI_HDR

The structure VDI_HDR describes a DOS sound driver's Driver Header Table.

struct VDI_HDR
{
  U8 ID[8];
  U32 driver_version;
  IO_PARMS * common_IO_configurations;
  U16 num_IO_configurations;
  char * environment_string;
  IO_PARMS IO;
  U16 service_rate;
  U16 busy;
  U16 driver_number;
  U16 this_ISR;
  void * prev_ISR;
  U8 scratch[128];
  char dev_name[80];
};

In Members

ID[8]: is an eight-character string which identifies the MSS driver's type. In assembly language, for example, the ID string would be initialized with a statement of the form db 'AIL3xxx',26, where xxx is replaced by 'DIG' for .DIG digital sound drivers, and 'MDI' for .MDI XMIDI drivers.
driver_version: should be initialized to a hexadecimal value corresponding to the revision level of the DDK For instance, version 0.10 of the DDK would correspond to a driver_version value of 0000010H, while version 1.00 would be 00000100H. See the MSS_DIG.H file for the current DDK version number.
common_IO_configurations: points to an array of num_IO_configurations structures of type IO_PARMS (above). This is a list of commonly encountered user I/O port settings for the supported sound device(s). It offers a reasonably "safe" compromise for auto-detection of sound hardware -- one that lies between attempting detection at only one factory default setting and recklessly scanning dozens of I/O port combinations, as many other drivers have attempted to do in the past. num_IO_configurations may be initialized to 0 if appropriate.
num_IO_configurations: specifies how many I/O configurations are pointed to by the common_IO_configuration field.
environment_string: if not NULL, points to an ASCII environment variable name (such as 'BLASTER' for Creative Labs Sound Blaster drivers) which may be found on end-users' systems and used to identify the correct I/O parameters for the supported audio device. The programmer may be able to avoid the "risks" inherent in the auto-detection process by performing a getenv for this standard environment variable and, if the result is not NULL, calling Function 303H (Parse Environment String) to fill the VDI_HDR's IO_PARMS structure with the information derived from the variable.
IO: tells the driver what I/O parameters to use to communicate with the supported device. It must be initialized by either MSS or by calling Function 303H (Parse Environment String) prior to any calls to functions 304H - 402H.
service_rate: if greater than zero, the driver requires real-mode callback service at service_rate calls per second from MSS via Function 302H (Periodic Interrupt Service). Function 302H is typically employed only for .MDI drivers or .DIG drivers which support non-DMA-equipped audio adapters, such as PCMCIA or parallel-port devices. Most .DIG drivers will not need to use Function 302H for timing, as digital audio devices generally provide their own timing and interrupt capabilities.
busy: initialized to 0 by MSS before any driver functions are called. Its value will become non-zero during any INT 66H function call to the driver, or while any external interrupt service for audio devices is taking place. MSS will not attempt any type of interaction with a driver whose busy flag is nonzero.
driver_number: initialized by MSS to a unique driver number value. When an INT 66H call is received, the driver compares the caller's BX value with driver_number, responding to the call only if the two values are equal. Otherwise, the call is dispatched to the prev_ISR handler (below).
this_ISR: initialized by the driver at assembly time. Its value is the offset of the driver's INT 66H function dispatcher from the beginning of the driver image.
prev_ISR: initialized by MSS to the address of the INT 66H handler which was active prior to installation of this_ISR into the INT 66H chain. When an INT 66H call is received, the driver compares the caller's BX value with driver_number, responding to the call only if the two values are equal. Otherwise, the call is dispatched to the prev_ISR handler.
scratch[128]: provides a 128-byte array which may be used either as temporary workspace by any sound driver function or as a convenient real-mode memory buffer for communications between MSS and functions such as 303H (Parse Environment String).
dev_name[80]: is an 80-byte array which contains the ASCII name(s) of the driver's supported device(s). Characters past the end of the ASCII string should be initialized to 0.

Discussion

The driver header's ID, driver_version, and this_ISR fields are statically initialized at assembly time. common_IO_configurations, num_IO_configurations, environment_string, and service_rate must be initialized by Function 300H (Initialize Driver), and cannot be accessed by MSS until after this function is called. All other members, including busy, driver_number, and prev_ISR are initialized by MSS immediately upon loading and installing the driver, before any INT 66H calls to the driver can be made.

Group: MSS Device Development Kit for DOS Sound Drivers
Related Sections: DDK Digital Function: IRQ_acknowledge, DDK Digital Function: IRQ_validate, DDK Function: 302H Periodic Interrupt Service, DDK Function: 303H Parse Environment String, DDK Function: 304H Verify Device I/O Parameters, DDK Function: 305H Initialize Device, DOS Sound Driver Architecture
Related Basic Types: U16, U32, U8, char, char *, void *
Related Structures: IO_PARMS, VDI_HDR