## Physical Device Driver Reference

[prev][next][parent][TOC]

### Physical Device Driver Components

The components of a physical device driver are illustrated in the following figure.

    /----------------------------\    /---------------------------\

    |          Task Time         |    |      Other PDD            |

    |                            |    |                          |

    |    /--------+----------+---/    \-----------+----------\    |

    |    |        |          |                    |          |    |

    |    |  /-----+----------+--------------------+-------\  |    |

    | K  |  |     |          |                    |       |  |    |

    | E  |  | /------\  /------\            /------\   |  |    |

    | R  |  | | Strat |  |Context|            |  IDC  |   |  \----/

    | N  |  | \-------/  \-------/   OS/2     \-------/   |

    | E  |  |                        PDD                  | Any Context

    | L  |  |                                             |

    |    |  | /-------\  /-------\            /-------\   |  /----\

    |    |  | | Timer |  |  Int  |            |  VDD  |   |  |    |

    |    |  | \------/  \------/            \------/   |  |    |

    |    |  |     |          |                    |       |  |    |

    |    |  \-----+----------+--------------------+-------/  |    |

    |    |        |          |                    |          |    |

    |    \--------+----------+---\    /-----------+----------/    |

    |                            |    |                          |

    |       Interrupt Time       |    |      Matched VDD          |

    \----------------------------/    \---------------------------/

    (1)  Strategy Entry Point  (required)

    (2)  Task-time Context  (optional)

    (3)  Timer Services Entry Point  (optional)

    (4)  Hardware Interrupt Entry Point  (mandatory)

    (5)  PDD-PDD IDC Entry Point  (optional)

    (6)  PDD-VDD IDC Entry Point  (optional)

Deciding what components to include in a physical device driver depends on two things, the complexity of the task and how the application performs I/O to its device. A physical device driver must have a strategy routine and can have a hardware interrupt routine, a timer handler, a context hook handler, an IDC handler or a VDD communications handler:

Strategy Routine (Required)

The strategy routine is called at task-time to handle I/O requests through a request packet interface with the OS/2 kernel as a result of an application I/O request. Application I/O requests can come from OS/2 applications active in protect mode or from DOS applications active in a DOS session.

The strategy routine follows the 16-bit far call/return model. When it completes processing, it issues a far return to the kernel. By convention, OS/2 preserves any registers used by the strategy routine.

The request packet interface to device drivers is described in Physical Device Driver Strategy Commands.

Context Hook Handler (Optional)

This routine is called by the OS/2 kernel at task time as a result of issuing the DevHelp_ArmContextHook call by the physical device driver. The handler runs in the first available task context after being armed.

Note: A thread running in the OS/2 kernel or a physical device driver cannot be pre-empted so the context hook, though called at kernel level, will wait until an application level thread would be dispatched before running.

The context hook handler follows the 16-bit far call/return model. When it has completed processing it issues a far return to the kernel. The handler must save and restore any registers it uses.

Timer Handler (Optional)

The timer handler is called as a result of a periodic clock tick and executes at interrupt time. This handler can be used to manage timeouts or polling of a non-interrupt driven device.

The timer handler follows the far call/return model. When it has completed processing, it issues a 16-bit far return to OS/2. The handler must save and restore any registers it uses.

Hardware Interrupt Handler (Optional)

The hardware interrupt handler is called as a result of a hardware interrupt and executes at interrupt time. The interrupt handler follows the 16-bit far call/return model. When it completes processing, it issues a far return to the OS/2 operating system. The handler must clear or set the Carry Flag (CF) to indicate whether it owns the hardware interrupt. If the device owns the interrupt, the carry flag is cleared (CLC). If the device does not own the interrupt, the interrupt handler must set the carry flag (STC) before returning. By convention, OS/2 2.1 (or later) preserves any registers used by the hardware interrupt handler.

Inter-Device-Driver Communications Handler (optional)

A physical device driver can call and pass data to another physical device driver by using the inter-device-driver communication (IDC) mechanism that is provided by the OS/2 operating system. To communicate with each other, device drivers must maintain addressability, while being sensitive to interrupt-time performance.

A physical device driver uses its device driver header to indicate that another device driver can communicate with it. See the section Physical Device Driver Header for a detailed description of the physical device driver header.

-The physical device driver must set bit 14 in the attribute field to indicate that it can participate in inter-device-driver communication.

-The physical device driver must set up the offset to its entry point for other device drivers, which is identified as the IDC Entry Point.

Another device driver can communicate with this driver by calling its IDC Entry Point. The other device driver obtains the address of this entry point (and other information it needs to be able to call this driver) by calling the AttachDD device helper routine. This DevHlp service returns the address of the IDC Entry Point of the specified named device driver. See Device Helper (DevHlp) Services for more information.

The type and form of communication are defined by the physical device driver that provides the IDC Entry Point. Registers can be used to indicate the type of communication (for example, initialize a buffer, write data to a buffer) as well as the form of communication (for example, data structures). To communicate with a physical device driver, therefore, another device driver must use the published interface to the IDC Entry Point.

By default, all IDC services provided by a device driver are assumed to be valid at kernel-context mode. Services that are valid at other calling contexts must be explicitly defined by the driver providing the IDC service .

Virtual Device Driver Communications Handler (optional)

A physical device and a virtual device driver can call and pass data to each other using a virtual-to-physical device driver communication mechanism. The physical device driver must register the communications handler entry point using the DevHelp_RegisterPDD call at initialization time. The virtual device driver will then gain the handler's address by using the VDHOpenPDD call.

To communicate with each other, the virtual and physical device drivers must maintain addressability while being sensitive to interrupt time performance.

The type and form of communication are defined by the physical/virtual device driver pair. A register-based or stack-based calling convention is acceptable but the initial call into the physical device driver is stack based and requires a 32-bit far return. See the DevHelp_RegisterPDD definition for more information.