Presentation Manager Display Driver Services

The virtual device driver provides the following DOSRequestVDD services for the PM display driver.

The Set Display Requirements request is issued by a PM display driver whenever PM switches to or from full-screen operation (including the first time it initializes the display, during system initialization):
```
     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_SETDRQ (11)              */
        ULONG cbInput,  /* Sizeof(VVDRQ)                      */
        PVOID pInput,   /* Pointer to VVDRQ structure         */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Parameters are invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)
```
where VVDRQ is a structure defining the region to be copied and how it is to be copied:
```
     /*
     ** Structure for VVDSYSREQ_SETDRQ
     */

     typedef struct vvdrq_s
     {
        PBYTE  pPhysVRAM;   /* Physical address of VRAM       */
        ULONG  nbReserved;  /* Number of reserved bytes       */
        ULONG  offLatchByte;/* Offset of available latch
                            /* storage                        */
        PBYTE  pfbDRQFlags; /* Pointer to flags (see DRQ_*    */
                            /* constants)                     */
        PBYTE  pfCtrlOwned; /* Addr. of display.dll's         */
                            /* fCtrlOwned flag                */
        PBYTE  pfCtrlNotify;/* Addr. of display.dll's         */
                            /* fCtrlNotify flag               */
        ULONG  nShadowRegs; /* Number of registers to shadow  */
        PVVREG pShadowData; /* Address of first entry in      */
                            /* shadow list                    */
     }  VVDRQ;

     #define DRQ_DIRTYREGS 0x01 /* Video controller registers */
                                /* modified                   */
```
and in which the PVVREG pointer points to one or more structures (as indicated by nShadowRegs) containing:
```
     /*
     ** Shadow entry for VVDSYSREQ_SETDRQ
     */

     typedef struct vvreg_s
     {
        USHORT port;    /* Port number                         */
        CHAR   indx;    /* Register index # (-1 if index reg)  */
        BYTE   value;   /* Last value written to register      */
                        /* by virtual video device driver      */
     } VVREG;
```
pPhysVRAM
indicates the starting physical address for VGA VRAM that the display driver will use (for example, A0000h).
nbReserved
is the number of bytes of display memory reserved exclusively for the PM display driver. It includes all the visible on-screen memory required, which must start at offset 0 from pPhysVRAM, as well as any off-screen memory needed for mouse pointer manipulation, latch storage, and so forth, immediately following. 64KB minus nbReserved yields the amount of off-screen memory to be managed by the virtual video device driver.
offLatchByte
is the offset (relative to pPhysVRAM) of a byte of video memory that the virtual video device driver can use at any (non-interrupt) time to temporarily save or restore VGA latches to and from system memory.
pfbDRQFlags
is a 16:16 pointer (Global Descriptor Table (GDT) alias selector:offset) to a byte of resident data containing inter-device driver communication bits. Currently, only one bit (bit 0) is defined, and it is set whenever the virtual video device driver has modified VGA Sequencer or Graphics Data Controller (GDC) registers. The PM display driver uses the bit to determine whether or not it must reinitialize any Sequencer or GDC registers it uses prior to the next PM drawing operation, after it has claimed ownership of the VGA controller.
pfCtrlOwned
is another 16:16 pointer-to-byte flag that is 0 if the controller is currently unowned, or 1 if owned. When either party sets the flag, the test and set must be done atomically (for example, XCHG and CMP) to avoid race conditions. If the PM display driver cannot set the flag, it must issue the REQCTRL function to force the virtual video device driver to clear the flag immediately. Similarly, if the virtual video device driver cannot set the flag, it must set the CtrlNotify byte flag (the 16:16 address of which is in pfCtrlNotify) and wait for the PM display driver to finish the current drawing operation and issue the FREECTRL function.
pShadowData
is a 16:16 pointer to an array of entries specifying a VGA port (for example, 3C0H, 3CEH), a register index or -1 for the index itself, and a shadow byte in which any changes to that register or index must be stored. The virtual video device driver must update the shadow bytes in parallel with the actual OUT instructions, uninterrupted, so that interrupt-time PM pointer operations are not affected. The PM display driver also updates the shadow bytes, but it has no obligation to do so.

The Request Off-screen Memory request is issued by a PM display driver when it wants to use some of the non-reserved off-screen memory.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_REQMEM (12)              */
        ULONG cbInput,  /* 1 implies WAIT, 0 implies NOWAIT   */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* # of bytes of off-screen memory    */
                        /* needed                             */
        PVOID pOutput   /* Address of DWORD to receive offset */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)
        ERROR_NOT_ENOUGH_MEMORY    (Off-screen memory
                                    allocation failed.)

On successful return, pOutput points to an offset (relative to pPhysVRAM) of one or more contiguous pages of off-screen VGA memory.

ﾚﾄﾄﾄ IMPLEMENTATION NOTE ﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄｿ
ｳ                                                          ｳ
ｳ   The WAIT-NOWAIT parameter is not honored.  If suf-     ｳ
ｳ   ficient memory is not immediately available, an error  ｳ
ｳ   is returned (that is, behavior is always NOWAIT).      ｳ
ｳ   Current display driver technology uses only NOWAIT.    ｳ
ｳ                                                          ｳ
ﾀﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾄﾙ

In the current virtual video device driver implementation, the request always fails if any DOS sessions currently exist. This way, if any background or windowed DOS sessions switch to a planar graphics mode, they will not be starved for VGA memory due to indeterminate memory consumption by PM (for example, Task Manager popped up, pull-down menu active, and so forth).

The Free Off-screen Memory request is issued by a PM display driver to free memory allocated by the above request. It should do so in a timely manner, particularly if the memory was allocated by way of a WAIT request.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_FREEMEM (13)             */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* # of bytes of off-screen memory    */
                        /*   freeing                          */
        PVOID pOutput   /* Address of DWORD containing offset */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not
                                    be locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

The Request VGA Controller request is issued by a PM display driver to force the virtual video device driver to immediately release ownership of the VGA controller. Ownership is indicated by the fCtrlOwned byte flag (see the VVDRQ data structure description in the section titled Presentation Manager Display Driver Services).

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_REQCTRL (14)             */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION (iFunc is invalid.)

The Free VGA Controller request is issued by a PM display driver to notify the virtual video device driver that the VGA controller is now available. This request is not issued every time the display driver completes an operation, but rather when the virtual video device driver has requested notification by setting the fCtrlNotify byte flag (see the VVDRQ data structure description in the section titled Presentation Manager Display Driver Services).

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_FREECTRL (15)            */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)

The Query VRAM Status request is issued by the PM Session Manager during screen-switches back to PM. It indicates whether or not any intermediate full-screen switches to DOS sessions might possibly have invalidated PM's last video image. If no invalidation occurred, then certain expensive PM application repaints are avoided.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_QUERYVRAMSTATUS (16)     */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_DATA         (Video memory has been invalidated.)

Success indicates that PM's memory image is intact; failure means that the image may or may not be intact.

[Back: DOS Session Window Manager Services]
[Next: Other Virtual Video Device Driver Services]