Using Your DDK

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

DDK Roadmap

This section provides a directory structure overview of the DDK.

Device Driver Build Instructions contains build information and directory roadmaps for the OS/2 device drivers.

Certification Test Suites Structure contains information about a set of tools and test cases designed to assist you in testing OS/2 device drivers.

Miscellaneous/Other Tools Structure contains information about various kernel debuggers, released levels of OS/2 debug kernels, and other useful utilities.

Device Driver Build Instructions

DDK Components

Display Device Drivers and Test Tools

DBCS Device Drivers

Printer Device Drivers and Test Tools

CD-ROM Device Drivers

DASD Device Drivers

Device Driver Test Tool

Input/Output Device Drivers and Test Tools

Multimedia Device Drivers and Test Tools

Display Device Drivers and Test Tools

Display Device Drivers

32-Bit Display Test Tool

32-Bit PM (VGA, SVGA 256 and ISO Fonts)

32-Bit PMVIDEO (Merged XGA/8514/S3 Drivers)

S3GRADD Driver

Base Video Screen Device Drivers(Screen01 and Screen02)

BBS Display Installation

16-Bit SVGA Base Video Handler

Filter GRADD

Generic and OEM PMI Samples

GENGRADD Driver

SVGA Utility

DSPINSTL Action Routine Sample

VGA/8514 Base Video Handler

Virtual XGA Video Device Driver

Virtual Video Display Driver

Palette Display Test Tool

32-Bit Display Test Tool

Tool Description

The 32-Bit Display Test Tool is a Presentation Manager application that enables the user to select one or more tests and execute them. A script interface also is provided, which permits the DTT to run predefined test-case scripts automatically.

The 32-Bit Display Test Tool is also listed as executables, under Certification Test Suites. When you select this tool as a Certification Test Suite, the build instructions are not applicable.

Compilers/Assemblers Required

IBM VisualAge C++ V3.0

OS/2 Toolkit for OS/2 2.1 or later

Build Instructions

1. Ensure the necessary compilers and assemblers are installed.
2. Run the SETCMPLR.CMD REXX command file located in the DDK\TOOLS directory. This command initializes environment variables to be used during the build.

   e.g., SETCMPLR <MSCpath> <VACpath> <CSETpath> <DDKpath>

   Where

   <MSCpath> represents the Microsoft C 6.0 install directory

   <VACpath> represents the IBM Visual Age C++ install directory

   <CSETpath> represents the IBM C Set ++ install directory

   <DDKpath> represents the DDK install directory

   Note: A period (.) may be substituted for a compiler directory that is not used during the build.

3. Change the directory to DDK\VIDEO\SRC\VIDEO\TESTTOOL\DTT.
4. To build the retail version, invoke NMAKE with target RETOS2C on the resident makefile.
5. To build the debug version, invoke NMAKE with target DBGOS2C on the resident makefile.

Build Notes:The DDK provides the executables of DTT32, which are located in the DDK\TESTCERT\DISPLAY\FUNCTION\DTT32 directory. If you have modified and rebuilt this test tool, you need to update these executables by copying the files from the DDK\VIDEO\REL\OS2C\RETAIL\BASE\TEST\VIDEO directory.

Files Created by Successful Build

Retail Version:

Directory: \DDK\VIDEO\REL\OS2C\RETAIL\BASE\TEST\VIDEO

• DTT.EXE

Directory: \DDK\VIDEO\REL\OS2C\RETAIL\BASE\TEST\VIDEO

• GREARC.DLL
• GREATT2.DLL
• GREATTR.DLL
• GREBIT2.DLL
• GREBNDS.DLL
• GREBTMP.DLL
• GRECLIP.DLL
• GRECOLR.DLL
• GREDVCON.DLL
• GREESC.DLL
• GREGEN2.DLL
• GREGENFC.DLL
• GRELINE.DLL
• GREMARK.DLL
• GREMDEV.DLL
• GREQURY.DLL
• GRETXTST.DLL

Debug Version:

Directory: \DDK\VIDEO\REL\OS2C\DEBUG\BASE\TEST\VIDEO

• DTT.EXE
• GREARC.DLL
• GREATT2.DLL
• GREATTR.DLL
• GREBIT2.DLL
• GREBNDS.DLL
• GREBTMP.DLL
• GRECLIP.DLL
• GRECOLR.DLL
• GREDVCON.DLL
• GREESC.DLL
• GREGEN2.DLL
• GREGENFC.DLL
• GRELINE.DLL
• GREMARK.DLL
• GREMDEV.DLL
• GREQURY.DLL
• GRETXTS.DLL

32-Bit PM (VGA) Display Driver

Driver Description

The 32-Bit PM (VGA) Display Driver consists of two DLLs: IBMVGA32.DLL and IBMDEV32.DLL. IBMVGA32.DLL contains the device-independent functions of the driver; IBMDEV32.DLL contains all the device-specific functions of the driver. IBMDEV32.DLL needs to be modified in order to port the driver to other video cards. This display driver can be used to support SVGA displays by replacing IBMDEV32.DLL with the corresponding SVGA DLL.

Compilers/Assemblers Required

Microsoft MASM 6.0

Build Instructions

1. Set the environment variables so the correct tools are picked up during the build.

   e.g., SET PATH=<drive>:\DDK\TOOLS;<drive>:\DDK\VIDEO\TOOLS;%PATH%

   Where <drive> represents your DDK installed drive and DDK represents the DDK installed directory. On the CD-ROM, the TOOLS directory path is DDK\TOOLS.

2. Before the FIRST build is attempted, run (only once) the COPYASM6.CMD REXX command file in the DDK\TOOLS directory. This command copies the set of needed files from your copy of the Microsoft MASM 6.0 assembler to the proper directories under the DDK base directory.

   e.g., COPYASM6 <MASMdrive>:\'MASM60' <drive>:\DDK

   Where <MASMdrive> represents the Microsoft MASM 6.0 installed drive and 'MASM60' represents the Microsoft MASM 6.0 installed directory, <drive> represents your DDK installed drive and DDK represents the DDK installed directory.

   To build IBMVGA32.DLL:

3. Change the directory to DDK\VIDEO\SRC\VIDEO\VGA32\IBMVGA32.
4. To build the retail version, invoke NMAKE with target RETOS2C on the resident makefile.
5. To build the debug version, invoke NMAKE with target DBGOS2C on the resident makefile.

   To build IBMDEV32.DLL:

6. Change the directory to DDK\VIDEO\SRC\VIDEO\VGA32\IBMDEV32.
7. To build the retail version, invoke NMAKE with target RETOS2C on the resident makefile.
8. To build the debug version, invoke NMAKE with target DBGOS2C on the resident makefile.

Build Notes

1. IBMVGA32.DLL and IBMDEV32.DLL must be built as a pair. That is, for any changes you make to either one, you must build and use BOTH DLLs.
2. If the following error message is found during the compile:

fatal error: A1017: out of near memory

remove unnecessary settings from your environment variables and run NMAKE again.

Files Created by Successful Build

32-Bit VGA/SVGA Common

Retail Version:

Directory: \DDK\VIDEO\REL\OS2C\RETAIL\BASE\OS2\DLL

• IBMVGA32.DLL

Debug Version:

Directory: \DDK\VIDEO\REL\OS2C\DEBUG\BASE\OS2\DLL

• IBMVGA32.DLL

32-Bit VGA Display Driver

Retail Version:

Directory: \DDK\VIDEO\REL\OS2C\RETAIL\BASE\OS2\DLL

• IBMDEV32.DLL

Debug Version:

Directory: \DDK\VIDEO\REL\OS2C\DEBUG\BASE\OS2\DLL

• IBMDEV32.DLL

Input/Output Device Drivers and Test Tools

USB Device Driver Sample

Driver Description

The Universal Serial Bus (USB) device driver sample contains source code for USB device drivers and installation protocols. The code includes the base USB device driver stack and the following drivers:

• Keyboard
• Mouse
• Modem
• Digital audio

Compilers/Assemblers Required

• Microsoft MASM 5.1 (supplied with the DDK)
• Microsoft C 6.0

Build Instructions

1. Set the environment variables so the correct tools are picked up during the build.
   e.g., SET PATH=<drive>:\DDK\TOOLS;%PATH%
   Where <drive> represents your DDK installed drive and DDK represents the DDK installed directory. On the CD-ROM, the TOOLS directory path is \DDK\TOOLS.
2. Before the FIRST build is attempted, run (only once) the COPYC60.CMD REXX command file in the \DDK\TOOLS directory. This command copies the set of needed files from your copy of the Microsoft C 6.0 compiler to the proper directories under the DDK base directory.
   e.g., COPYC60 <MSCdrive>:\'MSC60' <drive>:\DDK
   Where <MSCdrive> represents the Microsoft C installed drive and "MSC60" represents the Microsoft C installed directory, <drive> represents your DDK installed drive and DDK represents the DDK installed directory.
3. To ensure the device driver gets created properly on a FAT file system, type SET LANG=US at an OS/2 command prompt before invoking NMAKE.

To build all the USB device drivers:

1. Change the directory to \DDK\BASE\SRC\DEV\USB.
2. Invoke NMAKE on the resident makefile.

To build an individual USB device driver:

1. Change the directory to \DDK\BASE\SRC\DEV\MOUSE\USB.
2. Change to the directory of the desired USB device driver.
3. Invoke NMAKE on the resident makefile.

Files Created by Successful Build

Directory: \DDK\BASE\SRC\DEV\USB\USBD

• USBD.SYS

Directory: \DDK\BASE\SRC\DEV\USB\UHCI

• USBUHCD.SYS
• USBUHCD2.SYS

Directory: \DDK\BASE\SRC\DEV\USB\HID

• USBHID.SYS

Directory: \DDK\BASE\SRC\DEV\USB\USBMOUSE

• USBMOUSE.SYS

Directory: \DDK\BASE\SRC\DEV\USB\USBKBD

• USBKBD.SYS

Directory: \DDK\BASE\SRC\DEV\USB\USBAUDIO

• USBAUDIO.SYS

Directory: \DDK\BASE\SRC\DEV\USB\USBCOM

• USBCOM.SYS

Multimedia Device Drivers and Test Tools

Joystick Virtual Device Driver and Applications

Driver Description

The IBM PC game port adapter provides a simple interface to joysticks and other similar analog devices. This component includes the OS/2 device driver source code for the PDD/VDD pair and OS/2 source code for the JOYTUNE and JOYTEST applications.

Compilers/assemblers Required

• Microsoft Assembler 5.0
• IBM C Set ++ V2.01

Build Instructions

1. Set the environment variables so the correct tools are picked up during the build.
   e.g., SET PATH=<drive>:\DDK\TOOLS;%PATH%
   Where <drive> represents your DDK installed drive and DDK represents the DDK installed directory. On the CD-ROM, the TOOLS directory path is DDK\ TOOLS.
2. Before the FIRST build is attempted, run (only once) the COPYCSET.CMD REXX command file in the DDK\TOOLS directory. This command copies the set of needed files from your copy of the IBM C Set ++ V2.01 compiler to the proper directories under the DDK base directory.
   e.g., COPYCSET <IBMCdrive>:\'IBMC' <drive>:\DDK
   Where <IBMCdrive> represents the IBM C Set ++ V2.01 installed drive and 'IBMC' represents the IBM C Set ++ V2.01 installed directory, <drive> represents your DDK installed drive and DDK represents the DDK installed directory.
3. Change the directory to \DDK\BASE\SRC\VDEV\MME\VJOY.
4. Invoke NMAKE on the resident makefile.
5. Invoke NMAKE DEBUG to build the debug version.

Files Created By Successful Build

Directory: \DDK\BASE\SRC\VDEV\MME\VJOY

Retail Version:

• GAMEVDD.SYS
• JOYTEST.EXE
• JOYTUNE.EXE

Debug Version:

• DGAMEVDD.SYS

Joystick Physical Device Driver

Driver Description

The IBM PC game port adapter provides a simple interface to joysticks and other similar analog devices. This component includes the OS/2 device driver source code for the PDD/VDD pair and OS/2 source code for the JOYTUNE and JOYTEST applications.

Compilers/assemblers Required

• Microsoft Assembler 5.0
• Microsoft C 6.0

Build Instructions

1. Set the environment variables so the correct tools are picked up during the build.
   e.g., SET PATH=<drive>:\DDK\TOOLS;%PATH%
   Where <drive> represents your DDK installed drive and DDK represents the DDK installed directory. On the CD-ROM, the TOOLS directory path is DDK\ TOOLS.
2. Before the FIRST build is attempted, run (only once) the COPYC60.CMD REXX command file in the DDK\TOOLS directory. This command copies the set of needed files from your copy of the Microsoft C 6.0 compiler to the proper directories under the DDK base directory.
   e.g., COPYC60 <MSCdrive>:\'C600' <drive>:\DDK
   Where <MSCdrive> represents the Microsoft C installed drive and 'C600' represents the Microsoft C installed directory, <drive> represents your DDK installed drive and DDK represents the DDK installed directory.
3. Change the directory to DDK\BASE\SRC\DEV\MME\JOY.
4. Invoke NMAKE on the resident makefile.
5. Invoke NMAKE DEBUG to build the debug version.

Files Created By Successful Build

Directory: \DDK\BASE\SRC\DEV\MME\JOY

Retail Version:

• GAMEDD.SYS

Debug Version:

• DGAMEDD.SYS

Certification Test Suites Structure

Certification Test Suites

Display Test Suite

Palette Display Test Tool

32-Bit Display Test Tool

Color Point

CompuShow 2000!

FRACTINT

Picture Man

PMVIEW

WINFRACT

Function Verification Test Cases

System Verification Test Cases

Printer Test Suite

32-Bit Printer Test Tool

Device Driver Test Tool and Suites

Test Certification Common Utilities

Keyboard

Mouse

Parallel Port

CDROM

DASD

PCMCIA

SCSI

Multimedia Test Suite

MMPM/2 AP2/P2STRING Test Tool and Suites

MMPM/2 Audio Device Driver Exerciser Tool(PMADDE)

Note

The following tools are not available with this DDK. They can be downloaded from CompuServe.

• CompuShow 2000!
• FRACTINT
• Picture Man
• PMVIEW
• WINFRACT

Miscellaneous/Other Tools Structure

Misc/Other Tools

ASDT32 Debugger

Debugo

OS/2 Debug Kernels

OS/2 Japanese Debug Kernels

Other Tools

IBM Documentation

The following documents are in the \DDK\DOCS directory on the CD-ROM. You can view these books using the OS/2 VIEW command or by double-clicking on the DDK References on CD-ROM folder. (Your CD must be in the drive.)

These online documents are the latest technical reference books for developing OS/2 device drivers.

A brief description appears when you double-click on the title:

• Display Device Driver Reference
• Graphics Adapter Device Driver (GRADD) Reference
• Information Presentation Facility Guide and Reference
• Input/Output Device Driver Reference
• MMPM/2 Device Driver Reference
• Pen for OS/2 Device Driver Reference
• Physical Device Driver Reference
• Presentation Device Driver Reference
• Printer Device Driver Reference
• Storage Device Driver Reference
• Virtual Device Driver Reference

Module Level Version Control

The architecture of OS/2 mandates that certain device drivers supplied by our customers use the same names as those supplied with the OS/2 product. When IBM supplied a ServicePak to support our product, there was no way to detect the actual supplier of the device driver being serviced. In some cases, our service utility was replacing a vendor-supplied device driver with an IBM developed driver. To fix this problem, IBM is implementing Module Level Version Control in steps.

Step 1

The service utility will look for the "IBM" string in the Description field located in the LINKER definition file (see below). The utility will look for the "IBM" string only in the device drivers that had the support implemented when OS/2 Warp, Version 3 shipped. Consequently, version control will work only on DDK drivers whose makefiles have versioning already implemented in them.

Step 2

The second step of this architecture is being implemented by IBM OS/2 development. Development is adding support through the Description field of the LINKER definition file (DEF file). The current implementation uses the "IBM" string located in the built binary (in our case, a device driver) to allow our service utility to detect whether the module being serviced is actually an IBM module or one supplied by another party. The support is not complete, but there are examples in some MAKEFILEs of how we implemented this strategy. A specification is also provided below.

How to Insert the Information into the Executable

1. Modify MAKEFILE to create the LINKER definition file dynamically. This is implemented by utilizing the internal function of NMAKE, which allows for automatic creation of files from within the MAKEFILE. In addition, the description field of the LINKER definition file should be changed to reflect the following information. The "description" information will be taken by the LINKER and put in the load module header as the first entry in the Non-Resident Names Table. The loader will not load it, so there is no memory or performance impact.

The following is an example of how this is implemented in the IBMFLPY1.ADD device driver MAKEFILE which is located in the SRC\DEV\DASD\IBM\IBMFLPY1 directory of the DDK.

!include $(H)\VERSION.MAK
   .
   .
   .
ibm1flpy.add:  $(OBJS) $(LIBS) makefile
        Rem Create DEF file <<$(DEF02)
LIBRARY IBM1FLPY

DESCRIPTION "$(FILEVER)  Adapter Driver for ISA Diskette Controllers"

PROTMODE

SEGMENTS
 DDHeader       CLASS 'DATA'
 LIBDATA        CLASS 'DATA'
 _DATA          CLASS 'DATA'
 CONST          CLASS 'CONST'
 _BSS           CLASS 'BSS'
 'Code'         CLASS 'CODE' IOPL
 LIBCODE        CLASS 'CODE' IOPL
 _TEXT          CLASS 'CODE' IOPL
 SwapCode       CLASS 'CODE' IOPL
<<keep

2. Add the inclusion of the VERSION.MAK file located in the H directory of the current release to the MAKEFILE.

The following is an example of one of the VERSION.MAK files located on the DDK.

#
#       VERSION.MAK
#
#       Current build level for File Versioning
#
#       This file should reside in the same place as COMMON.MAK
#

_VENDOR  = OEM
_VERSION = 8.155

FILEVER = @^#$(_VENDOR):$(_VERSION)^#@

Notes

1. There are currently three VERSION.MAK files located on the DDK. These files represent the different "build" levels or releases that the source code supports. This "build" number is an IBM internal numbering scheme used to identify the release that the module supports by use of the _VERSION macro.
2. The VERSION.MAK file has the string "OEM" placed in the _VENDOR macro when the DDK is created. This string can be replaced with anything other than the string "IBM", which is reserved.

The following is the format of the complete Description field:

The maximum length of the Description entry is 256 bytes. This field should be kept to a minimum to limit disk space impact. The Description field is broken up into the following parts:

• The leading string of an "at sign" followed by the "pound sign" (@#).
• Vendor name followed by a colon (:). This is implemented in the _VENDOR macro imbedded in the FILEVER macro "OEM" (without the quotes).
• A version number of the form [A.B.C.D.], where A,B,C,D are alphanumeric fields that always increase in value in the ASCII table and never decrease for newer versions of the module. The version number is used to indicate function and cumulative fix levels. C and D (with the associated periods) are optional. A is the major version number. B is the minor version number. C (if present) is a revision level and D is a minor revision level. For example, 7.709 (a build number) would be a valid version indicator.
• The trailing string of a "pound sign" followed by an "at sign" (#@)
• Comment field (optional). If present, the comment should be kept as short as possible to limit disk footprint impact.

WIN-OS2 Version 3.1 Device Driver Supplement Diskette

The following drivers are available from IBM for adding WINOS2 support. They are available on a free separate diskette. Please reference the WIN-OS2 Version 3.1 Device Driver Supplement Registration for ordering information.

Please reference the Microsoft Windows 3.1 DDK driver build instructions for the following:

• WIN-OS/2 Seamless VGA:
• WIN-OS/2 Comm:
• WIN-OS/2 Mouse:

Build instructions

Driver Description

This package contains the modified Windows 3.1 DDK source files for the seamless VGA display driver, COMM driver, and MOUSE driver.

Build Instructions

Please follow the instructions in the README file that is shipped with the IBM WIN-OS2 Version 3.1 Device Driver Supplement Diskette.

Files Created by Successful Build

Full Screen VGA Display Device Driver:

Directory: \DDK\WINOS231\DRIVERS\DISPLAY\4PLANE\VGA\RETAIL

• VGA.DRV

Seamless VGA Display Device Driver:

Retail Version:

Directory: \DDK\WINOS231\DRIVERS\DISPLAY\4PLANE\VGA\SRETAIL

• SWIN132.DRV
• SWINVGA.DRV

Debug Version:

Directory: \DDK\WINOS231\DRIVERS\DISPLAY\4PLANE\VGA\SDEBUG

• SWIN132.DRV
• SWINVGA.DRV

ASYNC Communications Port:

Directory: \DDK\WINOS231\DRIVERS\286\COMM

• COMM.DRV

Mouse Device Driver:

Directory: \DDK\WINOS231\DRIVERS\286\MOUSE

• MOUSE.DRV