Virtual Device Driver Reference for OS/2: Difference between revisions
No edit summary |
|||
| (9 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
'' | {{IBM-Reprint}} | ||
{{VDDRef}} | |||
==EDM/2 preamble== | |||
This is the ''Virtual Device Driver Reference for OS/2'' as last published by IBM in 1995. It is republished here with explicit permission from the company (Copyright Permission #21953) and you should keep in mind that it is an intellectual property of International Business Machines Corp. that cannot be changed or reused without their permission and is not governed by the [[Attribution-Share Alike 3.0]] licence like the rest of the EDM/2 Wiki. | |||
The content of the documentation is unchanged apart from the following: | |||
* The original document was an INF file split into thousands of different small sections, these have been consolidated into chapters, and restructured to fit [[HTML]] formatting, mimicking the original [[GML]] format as much as possible. | |||
The | * Sales, technical help, download and contact information has been removed. The VDDR/2 and the related SDK's are no longer for sale, nor is support available from IBM. Some of the INF viewer related help has been removed as well as it is superfluous after the format change and might be misleading, and the Glossary and Notices section was merged with other DDK/SDK glossary sections as they are all identical. | ||
* Miniscule changes have been made to the text, spelling errors, formatting errors and possible copy and paste errors have been fixed and/or noted. | |||
Outside of formatting changes, adding Wikilinks and graphic improvements, the document shall be left as it is. It should be noted that the some of the driver models and data formats described in the documentation are have been replaced or extended by both IBM and third parties, but that does not mean that this document should be changed, but it is acceptable that a link is created to an internal or external article that explains the newer models and formats. | |||
==About This Book== | |||
The ''OS/2 Virtual Device Driver Reference'' defines what a virtual device driver is, how it operates, and when to use one. In addition, a description of the types of virtual device drivers, their interfaces, and the available kernel services is provided. System and application programmers can use the information found in this book to write their own virtual device drivers and subsystems. | |||
Knowledge of a programming language (such as C or assembler) that is used for writing OS/2 applications is necessary, and the programmer must be familiar with the workings of the OS/2 operating system. | |||
==How This Book is Organized == | ===How This Book is Organized=== | ||
This book consists of three parts: | This book consists of three parts: | ||
| Line 24: | Line 30: | ||
''Appendixes'' | ''Appendixes'' | ||
;[[#OS/2 Version Compatibility Considerations|OS/2 Version Compatibility Considerations]]:This table describes information added to or changed since the availability of OS/2 Warp, Version 3 in terms of version compatibility. | ;[[#OS/2 Version Compatibility Considerations|OS/2 Version Compatibility Considerations]]:This table describes information added to or changed since the availability of OS/2 Warp, Version 3 in terms of version compatibility. | ||
;[[Assembler Language Syntax]] :This appendix contains assembler language versions of the kernel functions covered in Chapter 6. | ;[[Assembler Language Syntax]]:This appendix contains assembler language versions of the kernel functions covered in Chapter 6. | ||
;[[IBM SDK/DDK Notices|Notices]] :This appendix contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies. | ;[[IBM SDK/DDK Notices|Notices]]:This appendix contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies. | ||
A [[IBM SDK/DDK Glossary|glossary]] and an index are included at the back of this book. | A [[IBM SDK/DDK Glossary|glossary]] and an index are included at the back of this book. | ||
==Introduction== | |||
Virtual device drivers are used by the OS/2* operating system to act as virtual devices for DOS applications executing in a DOS session. These device drivers provide ''virtual hardware'' support for DOS and DOS applications. | |||
== | |||
Virtual device drivers are used by the OS/2* operating system to act as virtual devices for DOS applications executing in a DOS session. These device drivers provide ''virtual hardware''support for DOS and DOS applications. | |||
The virtual device drivers shipped with OS/2 will virtualize most of the standard devices, including: | The virtual device drivers shipped with OS/2 will virtualize most of the standard devices, including: | ||
*Asynchronous Communication (RS-232C) | |||
*Asynchronous Communication (RS-232C) | *DMA (Direct Memory Access) | ||
*Fixed Disk and Diskette | |||
*Keyboard | |||
*Mouse | |||
*Parallel Port Printer | |||
*PIC (Programmable Interrupt Controller) | |||
*Timer | |||
*Video | |||
This book provides an overview of the virtual device driver mechanism and the available kernel services. | This book provides an overview of the virtual device driver mechanism and the available kernel services. | ||
==Types of OS/2 Device Drivers == | ==Types of OS/2 Device Drivers == | ||
Three types of device drivers are used in the OS/2 operating system: | Three types of device drivers are used in the OS/2 operating system: | ||
*Virtual device drivers | |||
*Physical device drivers | |||
*Presentation drivers | |||
===Virtual Device Drivers=== | |||
=== Virtual Device Drivers === | |||
The virtual device driver is an installable module, responsible for virtualizing a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers, operating at Ring 0, the most privileged level of the operating system. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware. | The virtual device driver is an installable module, responsible for virtualizing a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers, operating at Ring 0, the most privileged level of the operating system. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware. | ||
===Physical Device Drivers=== | |||
Standard I/O devices are supported by base physical device drivers that are part of the OS/2 operating system. Additional or replacement physical device drivers can be loaded to extend the control provided by the base device drivers, or to support nonstandard I/O devices. Typical examples of these loadable device drivers are ANSI.SYS and ANSI.DLL, which are loaded by "DEVICE=" statements in the CONFIG.SYS file, and provide additional functions on the interfaces to the screen and keyboard. Physical device drivers are initialized at Ring 3 and operate at Ring 0. | |||
=== Physical Device Drivers === | |||
Standard I/O devices are supported by base physical device drivers that are part of the OS/2 operating system. Additional or replacement physical device drivers can be loaded to extend the control provided by the base device drivers, or to support nonstandard I/O devices. Typical examples of these loadable device drivers are ANSI.SYS and ANSI.DLL, which are loaded by | |||
Further information on physical device drivers, physical device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Physical Device Driver Reference''. | Further information on physical device drivers, physical device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Physical Device Driver Reference''. | ||
=== Presentation Drivers === | === Presentation Drivers === | ||
The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API (Application Programming Interface) call interface, which uses the program stack to communicate with , or pass parameters to, the presentation drivers. These drivers are special-purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or privilege level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware. | The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API (Application Programming Interface) call interface, which uses the program stack to communicate with , or pass parameters to, the presentation drivers. These drivers are special-purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or privilege level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware. | ||
Presentation drivers are dynamic link library modules that are supplied as files and are identified by the extension | Presentation drivers are dynamic link library modules that are supplied as files and are identified by the extension ".DRV". When the Presentation Manager is initialized, the display presentation driver is automatically loaded and enabled. Other presentation drivers (for example, the hardcopy presentation drivers) are loaded and enabled when an application calls the ''DevOpenDC'' function to open the device. | ||
Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack. | Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack. | ||
Include (.INC and .h) files are shipped with the ''Developer's Toolkit for OS /2''to provide support for building presentation drivers that are written in either C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions. | Include (.INC and .h) files are shipped with the ''Developer's Toolkit for OS /2'' to provide support for building presentation drivers that are written in either C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions. | ||
Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Presentation Device Driver Reference''. | Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Presentation Device Driver Reference''. | ||
==When to Use a Virtual Device Driver == | ==When to Use a Virtual Device Driver == | ||
The device virtualization provided by OS/2 can be extended by creating a virtual device driver (VDD) and the corresponding physical device driver (PDD). A user-supplied virtual device driver virtualizes the hardware interfaces of an option adapter or device, usually to migrate an existing DOS application into the OS/2 DOS environment. | |||
The device virtualization provided by OS/2 can be extended by creating a virtual device driver (VDD) and the corresponding physical device driver ( PDD). A user-supplied virtual device driver virtualizes the hardware interfaces of an option adapter or device, usually to migrate an existing DOS application into the OS/2 DOS environment. | |||
Note that a virtual device driver is needed only in a limited number of cases. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely. OS/2 maps interrupts, I/O ports, and I/O memory directly to any DOS device driver or DOS application which attempts to access these resources. As long as a resource is not already claimed by another session or by the OS/2 kernel, it is directly accessible to the DOS program. | Note that a virtual device driver is needed only in a limited number of cases. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely. OS/2 maps interrupts, I/O ports, and I/O memory directly to any DOS device driver or DOS application which attempts to access these resources. As long as a resource is not already claimed by another session or by the OS/2 kernel, it is directly accessible to the DOS program. | ||
| Line 199: | Line 86: | ||
In the absence of a sharing requirement, a virtual device driver might be necessary if the device has strict interrupt service latency requirements. A virtual device driver/physical device driver pair improves the interrupt service latency for an option adapter or device. | In the absence of a sharing requirement, a virtual device driver might be necessary if the device has strict interrupt service latency requirements. A virtual device driver/physical device driver pair improves the interrupt service latency for an option adapter or device. | ||
==OS/2 Version Compatibility Considerations== | |||
=OS/2 Version Compatibility Considerations = | |||
The following table lists information that has been added to or changed in this documentation since the availability of OS/2 Warp, Version 3. When writing a device driver, you will want to take into consideration these particular changes, which may affect the downward compatibility of these items. | The following table lists information that has been added to or changed in this documentation since the availability of OS/2 Warp, Version 3. When writing a device driver, you will want to take into consideration these particular changes, which may affect the downward compatibility of these items. | ||
{|class="wikitable" | |||
{| class="wikitable" | |||
!Item Added or Changed ||Date Item Added or Changed||Compatibility of Addition or Change | !Item Added or Changed ||Date Item Added or Changed||Compatibility of Addition or Change | ||
|- | |- | ||
| Line 210: | Line 94: | ||
|} | |} | ||
[[Category:Driver | [[Category:Device Driver Reference]] | ||
Latest revision as of 04:44, 29 September 2022
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
| Virtual Device Driver Reference for OS/2 |
|---|
| Part 1. Overview
Part 2. Virtual Device Drivers Part 3. Reference Material Appendixes |
EDM/2 preamble
This is the Virtual Device Driver Reference for OS/2 as last published by IBM in 1995. It is republished here with explicit permission from the company (Copyright Permission #21953) and you should keep in mind that it is an intellectual property of International Business Machines Corp. that cannot be changed or reused without their permission and is not governed by the Attribution-Share Alike 3.0 licence like the rest of the EDM/2 Wiki.
The content of the documentation is unchanged apart from the following:
- The original document was an INF file split into thousands of different small sections, these have been consolidated into chapters, and restructured to fit HTML formatting, mimicking the original GML format as much as possible.
- Sales, technical help, download and contact information has been removed. The VDDR/2 and the related SDK's are no longer for sale, nor is support available from IBM. Some of the INF viewer related help has been removed as well as it is superfluous after the format change and might be misleading, and the Glossary and Notices section was merged with other DDK/SDK glossary sections as they are all identical.
- Miniscule changes have been made to the text, spelling errors, formatting errors and possible copy and paste errors have been fixed and/or noted.
Outside of formatting changes, adding Wikilinks and graphic improvements, the document shall be left as it is. It should be noted that the some of the driver models and data formats described in the documentation are have been replaced or extended by both IBM and third parties, but that does not mean that this document should be changed, but it is acceptable that a link is created to an internal or external article that explains the newer models and formats.
About This Book
The OS/2 Virtual Device Driver Reference defines what a virtual device driver is, how it operates, and when to use one. In addition, a description of the types of virtual device drivers, their interfaces, and the available kernel services is provided. System and application programmers can use the information found in this book to write their own virtual device drivers and subsystems.
Knowledge of a programming language (such as C or assembler) that is used for writing OS/2 applications is necessary, and the programmer must be familiar with the workings of the OS/2 operating system.
How This Book is Organized
This book consists of three parts:
Part 1. Overview
- Introduction
- This chapter contains a general description of the three types of OS/2 device drivers, and an overview of the virtual device driver mechanism and kernel services.
- Virtual Device Driver Architecture and Operations
- This chapter contains a description of virtual device driver architecture, operations, and communication between device drivers.
Part 2. Virtual Device Drivers
- Base Virtual Device Drivers
- This chapter contains a description of each base virtual device driver shipped with OS/2.
- Installable Virtual Device Drivers
- This chapter contains a description of each installable virtual virtual device driver shipped with OS/2.
- Virtual Mouse Device Driver
- This chapter describes the virtual mouse device driver (VMOUSE), which is responsible for all mouse support in multiple DOS sessions.
Part 3. Reference Material
- C Language Virtual DevHlp Services
- This chapter contains full C language descriptions of the kernel functions available to virtual device drivers.
Appendixes
- OS/2 Version Compatibility Considerations
- This table describes information added to or changed since the availability of OS/2 Warp, Version 3 in terms of version compatibility.
- Assembler Language Syntax
- This appendix contains assembler language versions of the kernel functions covered in Chapter 6.
- Notices
- This appendix contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies.
A glossary and an index are included at the back of this book.
Introduction
Virtual device drivers are used by the OS/2* operating system to act as virtual devices for DOS applications executing in a DOS session. These device drivers provide virtual hardware support for DOS and DOS applications.
The virtual device drivers shipped with OS/2 will virtualize most of the standard devices, including:
- Asynchronous Communication (RS-232C)
- DMA (Direct Memory Access)
- Fixed Disk and Diskette
- Keyboard
- Mouse
- Parallel Port Printer
- PIC (Programmable Interrupt Controller)
- Timer
- Video
This book provides an overview of the virtual device driver mechanism and the available kernel services.
Types of OS/2 Device Drivers
Three types of device drivers are used in the OS/2 operating system:
- Virtual device drivers
- Physical device drivers
- Presentation drivers
Virtual Device Drivers
The virtual device driver is an installable module, responsible for virtualizing a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers, operating at Ring 0, the most privileged level of the operating system. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware.
Physical Device Drivers
Standard I/O devices are supported by base physical device drivers that are part of the OS/2 operating system. Additional or replacement physical device drivers can be loaded to extend the control provided by the base device drivers, or to support nonstandard I/O devices. Typical examples of these loadable device drivers are ANSI.SYS and ANSI.DLL, which are loaded by "DEVICE=" statements in the CONFIG.SYS file, and provide additional functions on the interfaces to the screen and keyboard. Physical device drivers are initialized at Ring 3 and operate at Ring 0.
Further information on physical device drivers, physical device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Physical Device Driver Reference.
Presentation Drivers
The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API (Application Programming Interface) call interface, which uses the program stack to communicate with , or pass parameters to, the presentation drivers. These drivers are special-purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or privilege level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware.
Presentation drivers are dynamic link library modules that are supplied as files and are identified by the extension ".DRV". When the Presentation Manager is initialized, the display presentation driver is automatically loaded and enabled. Other presentation drivers (for example, the hardcopy presentation drivers) are loaded and enabled when an application calls the DevOpenDC function to open the device.
Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack.
Include (.INC and .h) files are shipped with the Developer's Toolkit for OS /2 to provide support for building presentation drivers that are written in either C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions.
Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Presentation Device Driver Reference.
When to Use a Virtual Device Driver
The device virtualization provided by OS/2 can be extended by creating a virtual device driver (VDD) and the corresponding physical device driver (PDD). A user-supplied virtual device driver virtualizes the hardware interfaces of an option adapter or device, usually to migrate an existing DOS application into the OS/2 DOS environment.
Note that a virtual device driver is needed only in a limited number of cases. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely. OS/2 maps interrupts, I/O ports, and I/O memory directly to any DOS device driver or DOS application which attempts to access these resources. As long as a resource is not already claimed by another session or by the OS/2 kernel, it is directly accessible to the DOS program.
Where access-sharing is required, it is generally not necessary to create a virtual device driver if the I/O is handle-based. DOS INT 21h I/O requests are routed by the OS/2 file system to the protect-mode physical device driver. If all I/O is handle-based, it is necessary only to create the physical device driver.
For block devices, it is recommended that OS/2 support be provided only by a physical device driver. Both DOS and OS/2 sessions will then access the device through file system interfaces defined by DOS and the OS/2 operating system.
In the absence of a sharing requirement, a virtual device driver might be necessary if the device has strict interrupt service latency requirements. A virtual device driver/physical device driver pair improves the interrupt service latency for an option adapter or device.
OS/2 Version Compatibility Considerations
The following table lists information that has been added to or changed in this documentation since the availability of OS/2 Warp, Version 3. When writing a device driver, you will want to take into consideration these particular changes, which may affect the downward compatibility of these items.
| Item Added or Changed | Date Item Added or Changed | Compatibility of Addition or Change |
|---|---|---|
| Advanced OS/2 Joystick Device Driver | November 1995 | OS/2 Warp, Version 3 and higher |