GRADD Model Components

This chapter describes the individual components of the Graphics ADapter Device (GRADD) driver model used for developing device drivers.

The GRADD model is composed of several components that coordinate the communication among each graphic subsystem and the available graphics hardware. The components include the following:
 * Video Manager (VMAN):The VMAN component binds the GRADD model components together. VMAN synchronizes the communication between translation layers and a GRADD and also manages the graphics pointer.
 * When an operating system service requests a graphics operation, the associated translation layer sends one of the defined Video Manager Interface (VMI) commands to VMAN. On receiving a VMI command, VMAN either handles the request or sends it down to the appropriate GRADD. For more information about VMAN, refer to.


 * Translation Layers:A translation layer exists for each graphics engine in OS/2 Warp. The translation layer converts the function calls made by the graphics engine to the VMI protocol required by VMAN. For more information about transition layers, refer to.
 * SOFTDRAW:SOFTDRAW is the default for any simulated graphics functions for nonaccelerated graphics operations.
 * Acting as a graphics library, SOFTDRAW exports the base drawing functions (SDBitBlt and SDLine) used by VMAN to simulate graphics operations. SOFTDRAW provides a generic graphics library. Given a pointer to a linear address (a VRAM bit map or system-memory bit map), SOFTDRAW can draw the bits directly into the bit map.


 * Graphics Adapter Device Driver:The GRADDs represent the available video hardware. They execute the requested operation or returns it for simulation. When a GRADD receives a GHI function call from VMAN that is not mandatory, the GRADD has the option of performing the requested operation or returning the request to VMAN with a return code of RC_SIMULATE. The RC_SIMULATE return code informs VMAN that the operation needs to be simulated in software. For more information about GRADDs, refer to.

The following figure graphically illustrates the components of the GRADD model.



Video Manager (VMAN)
This section describes how the Video Manager (VMAN) component fits into the GRADD model.

When VMAN is initialized, a series of components are loaded and initialized. These components include SOFTDRAW and the GRADDs required for the available graphics adapters (each graphics adapter may require more than one GRADD).

The GRADD model supports multiple GRADDs. If a developer wants to extend the GRADD model or to filter out operations, a filter GRADD can be placed between VMAN and the primary GRADD running the hardware. This form of linking GRADDs is called chaining and provides a way of modifying a GRADD's behavior without rewriting and recompiling the GRADD. "Adding Extensions" in discusses the specifics involved when extending the GRADD architecture.

Video Manager Interface (VMI)
The VMAN component relies on a special protocol, called the Video Manager Interface (VMI), to receive requests from the translation layers. VMI consists of a small set of operations, each identified by a unique function number. Separate function numbers are required for each operation because VMAN exports only one entry point for the translation layers to communicate with VMAN. This exported function is called. VMIEntry expects four parameters from each function call it receives from a translation layer.

Because the VMIEntry function receives many different types of requests from the translation layers, the gid provides an ID number that identifies the GRADD to receive the operation and the ulFunction provides a function number that identifies the requested operation. The last two parameters ( pIn, pOut) pointer to input and output data structures that are unique to each VMI function.

Most of the requests VMAN receives from a translation layer are passed directly to the appropriate GRADD. Each GRADD has its own exported function, called, which is the same function type as VMIEntry (see for more information about GHI protocol).

Pointer Management in the Video Manager
VMAN is responsible for pointer management. When a pointer movement occurs, VMAN is notified by the function. VMAN calls down the GRADD chain for the pointer update. The GRADD can either update the pointer or return to VMAN for simulation. If RC_SIMULATE is returned, VMAN uses the regular bitblit command to simulate the pointer movement.

VMAN tracks information about the current state of the pointer. All drawing VMI commands that affect the display surface must include the areas of the screen being updated by the primitive. VMAN uses this information to determine whether or not the pointer should be hidden before it passes a drawing request down the GRADD chain. On return from the drawing command, VMAN will restore the pointer if it was previously hidden.

Video Helper Functions
VMAN exports a number of helper services that GRADDs may use for common required functions. By using video helpers, a GRADD can avoid operating system specific calls. These helper functions are described below.

The helper returns a 32-bit pointer to a piece of memory. The caller of this function supplies the byte count required.

The helper frees memory that has been allocated via the VHAllocMem helper.

The helper makes code or data segments available for ring 0 interrupt-time processing.

The helper converts physical address ranges to linear virtual address ranges for processes using VMI.

The helper aliases process memory to a global ring 0 context.

The helper converts the physical address of VRAM to linear virtual aperture for both process and global ring 0 context.

Translation Layers
Translation layers use the structure to gain access to the hardware capabilities and available modes. The function returns the CHAININFO structure.

When the function receives an operation from a translation layer, VMAN checks the function number and either handles the operation or forwards it to the appropriate GRADD. VMAN will handle the operation if the GRADD returns an RC_SIMULATE. The GRADD Model diagram shows how the VMAN component handles communication among the various components and the paths that commands can take during processing.

Translation Layer between OS/2 Graphics Engine and VMAN
The translation layer for the OS/2 Graphics Engine (GRE) is called GRE2VMAN. For a system that uses OS/2 as the dominant operating system service, GRE2VMAN is the first translation layer and the first component of the GRADD model to be loaded. When GRE2VMAN is loaded, it calls VMAN's VMIEntry function with a. When VMAN receives a VMI_CMD_INIT for the first time, it loads the other GRADD model components.

Virtual VMI Device Driver (VVMI)
Video Manager (VMAN) creates a thread which is used to process all VMAN requests from the VDM. This thread is blocked by VVMI until a request is made, at which time the thread is unblocked and the request is serviced by VMAN.

Future Translation Layers
In the future, other graphics subsystems can be adapted to work in the IBM Operating System/2 operating system. To accomplish this, a translation layer must be provided (shown as 'n2VMAN' in the GRADD Model diagram). This translation layer must map the graphics primitives of the graphics subsystem to the appropriate VMI_CMD_ functions.

Translation Layer for Extensions
The GRADD Model can be extended using the VMI extension protocol. Using this protocol, a translation layer directs extension functions to a GRADD through the function. In order to accomplish this, a translation layer must be provided (shown as 'EXT2VMAN' in the GRADD Model diagram).

See for more information.

Graphics Adapter Device Driver (GRADD)
This section describes how the Graphics Adapter Device Driver components interface with VMAN.

Graphics Hardware Interface (GHI)
The entry point and functions supported by a GRADD are referred to as the Graphics Hardware Interface (GHI). The differences between the VMAN protocol (VMI) and the protocol for the GRADDs GHI include the following: Each GRADD has an exported function, called, which is the same function type as  in VMAN.
 * The GHI is a subset of the VMI.
 * The ulFunction parameter value changes to the appropriate GHI_CMD_ function name.

HWEntry receives all of the operations from VMAN.

In the GRADD model, the GRADDs are the only components that have direct access to the video hardware. GRADD code uses the accelerated features of a graphics adapter. By returning RC_SIMULATE for a graphics operation, the GRADD gives the SOFTDRAW component permission to draw directly to the video memory of the hardware. The serialization of video memory is handled by the Video Manager through the function.

Each GRADD must process the following GHI_CMD_ functions:
 * 
 * 
 * 
 * 
 * 
 * * This function is mandatory only when a 256-color mode has been chosen.

The following GHI functions can return RC_SIMULATE and let VMAN handle the operations:
 * 
 * 
 * 
 * 
 * 
 * 
 * 

The GHI function numbers are assigned in such a way that they can be used as a zero-based index into a function jump table.

Systems Management (RAS)
Because performance is critical in a video graphics subsystem, all systems management and RAS hooks should be placed in a filter GRADD. This protects the majority of users, who do not need this support, from performance degradations caused by the addition of trace points and hooks.