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
- Ensure the necessary compilers and assemblers are installed.
- 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.
- Change the directory to DDK\VIDEO\SRC\VIDEO\TESTTOOL\DTT.
- To build the retail version, invoke NMAKE with target RETOS2C on the resident makefile.
- 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
- 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.
- 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:
- Change the directory to DDK\VIDEO\SRC\VIDEO\VGA32\IBMVGA32.
- To build the retail version, invoke NMAKE with target RETOS2C on the resident makefile.
- To build the debug version, invoke NMAKE with target DBGOS2C on the resident makefile.
- To build IBMDEV32.DLL:
- Change the directory to DDK\VIDEO\SRC\VIDEO\VGA32\IBMDEV32.
- To build the retail version, invoke NMAKE with target RETOS2C on the resident makefile.
- To build the debug version, invoke NMAKE with target DBGOS2C on the resident makefile.
- Build Notes
- 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.
- 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
- 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. - 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. - 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:
- Change the directory to \DDK\BASE\SRC\DEV\USB.
- Invoke NMAKE on the resident makefile.
To build an individual USB device driver:
- Change the directory to \DDK\BASE\SRC\DEV\MOUSE\USB.
- Change to the directory of the desired USB device driver.
- 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
- 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. - 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. - Change the directory to \DDK\BASE\SRC\VDEV\MME\VJOY.
- Invoke NMAKE on the resident makefile.
- 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
- 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. - 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. - Change the directory to DDK\BASE\SRC\DEV\MME\JOY.
- Invoke NMAKE on the resident makefile.
- 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