Device Driver Development Kit for 32 Bit Drivers

Device Driver Development Kit for 32 bit drivers Written by David Azarwicz <david@88watts.net> Available from http://88watts.net/software.html Drv32 is a development kit to make developing new device drivers very easy. This kit contains header files and a library that contains all of the system related interfaces and thunking modules necessary to build a 32 bit device driver on OS/2. The only thing you need to focus on is your unique code for your device. Then simply link to the library and you can start testing your code. Examples of working drivers are included in the kit. The AHCI driver, the USB drivers, and the Multimac drivers are based on this kit. The Drv32 kit can be used to build both DEVICE and BASEDEV drivers. This kit is not yet suitable for building IFS drivers. Package Contents ---------------- Kit Directory Drv32.lib - A library containing the setup and many functions needed for a 32 bit device driver. Dev32lib.h - The header file for the Drv32.lib library. Dev32Help.h - A modified dev help header file for 32 bit drivers. Dev32iorb.h - A header file for IO Request blocks for 32 bit drivers. Dev32ndis.h - A header file for NDIS support for 32 bit drivers. Dev32rmbase.h - A header file for RM support for 32 bit drivers Dev32rmcalls.h - A header file for RM support for 32 bit drivers. Dev32scsi.h - A header file for SCSI structures for 32 bit drivers. pci_regs.h - A header file with PCI register definitions. Required Directory Driver.c - A sample of the minimum required elements for building a device driver with the Drv32 kit. BaseDev.c - A sample of the minimum required elements for building a basedev device driver with the Drv32 kit. makefile - The makefile for building the sample drivers. Sample Directory PciAc5.c - The sample device driver ioctl.h - The header file for IOCtl communication between the driver and an application. test.c - A test application for testing the driver's IOCtl interface. makefile - The makefile for building the sample driver and test application. Copyright and License --------------------- Copyright (c) 2013-2022 David Azarewicz <david@88watts.net> All rights reserved. (c) Copyright IBM Corporation 1990,2000. All rights reserved. The Drv32 Kit is a derivative work of the IBM DDK. You must have a IBM DDK license to use this software. Drv32 is provided to you solely for the purpose of assisting you in developing your own OS/2 device drivers. You may use this software in your device drivers free of charge. Drv32 is provided AS-IS, WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESS, IMPLIED OR STATUTORY, not even any implied warranty of MERCHANTABILITY. YOUR USE THIS PRODUCT IS CONDITIONED UPON YOUR ACCEPTANCE OF THIS LICENSE AGREEMENT. INSTALLING AND/OR USING THE PRODUCT INDICATES YOUR ACCEPTANCE OF THESE TERMS AND CONDITIONS. IF YOU DO NOT AGREE TO THESE TERMS AND CONDITIONS PROMPTLY DELETE THIS PRODUCT. This Product consists of: (1) Drv32 Code, (2) Tools and Lib Code. *1. Grant of License for the Drv32 Code* You are granted a non-exclusive, non-assignable, non-transferable right to use the enclosed Drv32 Code for the sole purposes of designing, developing and testing derivative work(s) which are device drivers for the OS/2 program (the "OS/2 Device Driver"). In addition, you are granted a non-exclusive, non-assignable, non-transferable right to reproduce and distribute, in object code form only, the permitted derivative works described above. Under this license you may not: a. use, copy, modify, display or merge copies of the Drv32 Code except as provided in this agreement; b. distribute, sublicense, rent, lease, assign or transfer the Drv32 Code, except as provided in this agreement; or c. disclose, display, disseminate, market or distribute the Drv32 Code in any media, except for your own internal use by you or your full-time employees on a need to know basis on your premises. *2. Grant of License for Tools and Lib Code* You are granted a non-exclusive, non-assignable, non-transferable right to use the Tools and Lib Code, in object code form only, and only for your internal use and for the sole purposes of designing, developing and testing the OS/2 Device Driver. Under this license you may not: a. use or copy the Tools and Lib Code except as provided in this agreement; b. modify, display, or merge copies of Tools and Lib Code; c. reverse assemble or reverse compile the Tools and Lib Code; d. distribute, sublicense, rent, lease, assign or transfer the Tools and Lib Code; Requirements ------------ 1. The latest MiniDDK (preferred) or an updated DDK. If you get compile warnings or errors using the DDK, then your DDK is not up-to-date. The MiniDDK contains no source code, and has been rearranged so that all header files are in base/h or base32/h, all include files are in base/inc or base32/inc, and all libraries are in base/lib or base32/lib. The supplied makefiles assume the layout of the MiniDDK, so some changes may be required to your DDK, or to the makefiles of your project so that the appropriate files can be found. For the Drv32 Kit, check that you have the newest versions of the following files: base\h\strategy.h 5,998 bytes If you are developing a driver and you need a copy of the MiniDDK, please contact me by email at david@88watts.net. Include in your message the driver(s) you are working on and confirm that you already have a IBM DDK license. 2. OpenWatcom v1.9 or greater See http://www.openwatcom.org The resulting driver built with the Drv32 package will only run on Pentium class systems and above. 486 processors and below are not supported. Sample Drivers Included ----------------------- Sample The driver in the Sample directory is a real working driver that you can use as an example for building your own driver. Required The drivers in the Required directory shows examples of the bare minimum you need to build a working driver using Drv32. There is also plenty of documentation in the comments in Driver.c and BaseDev.c. Installing the Required Packages -------------------------------- Note: Example commands are only to indicate logical flow and meaning. They will need to be modified to apply to your particular system. 1. Unzip the package. If you are reading this, then you probably have already done that. 2. Copy the contents of the Kit directory to a directory of your choice. Example: md E:\Drv32Kit copy Kit\* e:\Drv32Kit 3. Set the DRV32KIT environment variable to point to the Drv32 Kit you just installed. Example: set DRV32KIT=e:\Drv32Kit You can put this statement in your CONFIG.SYS so it is always available. 4. If you are using your own DDK, skip this step. Install the MiniDDK. Create a directory for the MiniDDK and unzip the contents of the MiniDDK into that directory. Example: md E:\MiniDDK cd e:\MiniDDK 7za x MiniDDK-20131010.7z 3. Set the DDK environment variable to point to the MiniDDK you just installed, or to your DDK. Example: set DDK=e:\MiniDDK You can put this statement in your CONFIG.SYS so it is always available. 4. Make sure you have the WATCOM environment variable pointing to your OpenWatcom installation. Example: set WATCOM=e:\Watcom You can put this statement in your CONFIG.SYS so it is always available. Building the Sample Drivers --------------------------- Go to the directory of the driver you want to build and type wmake. Example: cd Sample wmake Example: cd Required wmake Documentation ------------- Documentation for this package is in the header files and the sample drivers. Warnings and Restrictions Regarding 32 Bit Device Drivers --------------------------------------------------------- 32 bit device drivers under OS/2 are extremely restricted as to the system resources they can access. The developer must have a thorough understanding of the different address spaces in the system. Building a 16 bit driver is always easier than building a 32 bit driver. This is a partial list of the issues that exist with 32 bit drivers: 1. The init routine runs at ring 0. This means that you cannot use any of the normal Dos* system services that are available to 16 bit drivers. 2. The interface to the system is still 16 bits, so you must be very careful that all pointers are properly converted each way. 3. You are restricted to a 64K data segment. The pointer conversion routines provided by DRV32 require this. Your 32 bit code segment is unlimited. You can, of course, allocate as much memory as you want. You can manually convert pointers between Far16 and Flat, or you can let the compiler do it for you. The DRV32 library has conversion functions that the compiler will call automatically to convert the pointers if they are defined correctly. See the comments in the Dev32lib.h header file for the FlatToFar16() and the Far16ToFlat() functions. Use of D32ThunkStackTo32() is required instead of KernThunkStackTo32() in order for FlatToFar16() to work properly for stack variables. Beware that if you do not have variables declared properly, you can get a double conversion or no conversion, either of which won't work. Drv32 Kit is still being developed ---------------------------------- Although this package is stable, it is still under development. Some features and modules needed to build more complex drivers may be missing. More features and modules are being added. The modules that exist have been tested and should work fine. If you have a problem or need a feature, please contact me at david@88watts.net. Be sure to put Drv32Kit in the subject line. Change History -------------- v20240802 strtol fixed to terminate on any invalid character v20240526 D32g_DbgBufWrap changed to D32g_DbgFlags v20220522 Changed handling of 64 bit BARs. v20220312 Changed file functions. Some IORB optimizations. v20210223 Added some IORB support functions. v20210117 Fixed SMP problem in heap manager. v20200731 Added DevMfence() and DevWbinvd() Added GenInit() v20200319 Changed some variable names. v20200218 Added RMGetCommandLine Added RMKeyToHandleList Changed some structure names in Dev32iorb.h v20190305 Changed compiler optimizations. v20190210 Added MultiCPU protection for debug output v20180906 Fixed error in DhTickCount() Added DevGetCS() v20180702 Added Timer_ResetTimer() v20180520 Added Event Semaphore Dev32Help functions Added GDTTOFAR16 macro Added reserved word to header to make size 20h Added StringPad() v.20180412 Added Dev32Help_Yield() Enhanced printf options. Added PSD check for Msi functions. v.20180106 Added kludge for Uniaud MSI v.20171229 Added missing RMDestroyDevice function. v.20170807 Fixed a problem with FlatToFar16 pointer conversion. v.20170731 Added several functions and enhancements mostly related to IDC calls and basedev drivers. v.20170704 Added Msi functions. Changed RmAddIrq() and Rm1AddIrq() to include flags. v.20170607 Fixed interrupt handlers. v.20161226 Zero code and data lengths if init returns error. fixed strncpy - always returns dst zero terminated. v.20161219 Fixed minor issue in CallFar16 v.20161208 Fixed some minor issues in the heap manager. Fixed an SMP defect in the ndis module. v.20161115 Enhanced debugging functions. Added Timer functions. Added some Dev32Help functions: RegisterDeviceClass, RegisterKrnlExit, CallFar16, InternalError Enhanced FlatToFar16 Reorganized library for smaller modules. v.20160313 Heap manager fixes and enahancements. Added a few functions. v.20150507 Fixed a register corruption issue in the RM calls Added BaseDev sample driver. Fixed an SMP issue. v.20150424 Heap manager fixes and improvements Added CastFar16ToULONG Added Dev32Help_TickCount FlatToFar16 fixes and improvements v.20140110 Misc fixes v.20131211 Fixed NDIS module Updates to heap manager Misc other changes v.20131030 Documentation updates v.20131014 Initial release