QueryFunctions

Returns the function pointers for the specified function group.

Declaration

ibool NAPI GA_loaderFuncs::QueryFunctions(
    N_uint32 id,
    N_int32 safetyLevel,
    void _FAR_ *funcs)

Prototype In

snap/graphics.h

Parameters

id

Identifier for the function group to get pointers for

safetyLevel

Safety level requested

funcs

Pointer to function block to fill in

 

Return Value

True if the requested function group is available, false if not.

Description

This function is the main function that is used by the graphics application code to get a block of function pointers for a specified function group. The function groups are defined GA_funcGroupsType enumeration, and breaks up the functions in the device driver API into groups of logically similar functions. For instance to get the block of functions for the hardware cursor, you would call this function with the GA_GET_CURSORFUNCS identifier.

The safetyLevel parameter defines the safety level of those functions that are returned by the driver. The safety level essentially defines what runtime requirements those functions have, such as requiring kernel mode access to registers etc. There are currently three safety levels defined:

safetyLevel

Description

0

Level 0 is defined as 'unsafe', which means that the functions must be executed in kernel mode as they require access to I/O space registers. Essentially requesting level 0 function pointers will return pointers to all available functions in that function group.

1

Level 1 is defined as 'mostly safe', which means that the functions only access memory mapped registers and do not require any I/O space register access. These functions can thus be exectued in user space provided that all the memory mapped register regions are mapped into user space.

2

Level 2 is defined as 'safe', which means that the functions only access memory mapped registers via the 'safe' IOMemMaps[2] and IOMemMaps[3] regions (the first two will only be mapped into kernel space by the loader code). The idea here is that the driver separates 'safe' and 'unsafe' registers (defined below).

Note that with the above defined safety levels, it is possible for the display driver in the operating system to provide a compromise between maximum performance and maximum security as a user level setting. Maximum security would be achieved if the graphics functions where only ever called from kernel mode, but would incur the overhead of user mode to kernel mode switching for all graphics output. Better performance can be achieved if safety level 2 functions are executed in the user mode component of the display driver, but this requires specific hardware that is designed to separate 'safe' and 'unsafe' registers by at least 8Kb (so they can be indivudally mapped into user+kernel or just kernel space). Even higher performance can be achieved if all functions which only use memory mapped register access are executed in user space, which can be done with all modern PC graphics hardware. However this does expose the possibility of an errant application accidentally writing to the user space registers and causing the graphics hardware to lock.

Note:    Application code should not call this function directly, but instead call GA_queryFunctions.

Note:    To allow for future compatibility, all function blocks begin with a dwSize member. The caller is expected to fill in the dwSize member with the size of the function block being retrieved before calling QueryFunctions. If the driver exports more functions than the application knows about, only a subset of the functions are copied to the application. If the application expects more functions than the driver provides, the non-existant functions are set to NULL pointers by QueryFunctions, and the remainder copies from the driver.

Note:    The OS loader code will only map the IOMemMaps[2] and IOMemMaps[3] regions into user space, and will map all memory mapped I/O regions into kernel space. This allows unsafe registers (that would potentially cause the system to lock) to not be mapped into user space and potentially compromising system stability.

Note:    This mechanism also provides for a clean and simple upgrade path for future drivers, while ensuring maximum compatibility with existing specifications. New functions for a particular group can simply be added to the end of the function group to extend that group. Totally new function groups can be added by defining new identifiers for that function group, and older drivers will return a NULL if that funciton group is requested. Finally if a function group requires a complete redesign to achieve maximum peformance for next generation hardware, a new extended function group can be defined (and drivers can continue to export the older and slower function group for backwards compatibility).

Note:    Safety levels other than 0 are not implemented in SNAP 1.0

See Also

InitDriver, QueryFunctions, UnloadDriver

Copyright © 2002 SciTech Software, Inc. Visit our web site at http://www.scitechsoft.com