pciVideoPtr *xf86GetPciVideoInfo(void);
	  

returns a pointer to a list of pointers to pciVideoRec entries, of which there is one for each detected PCI video card. The list is terminated with a NULL pointer. If no PCI video cards were detected, the return value is NULL.

    void ChipIdentify(int flags);
	  

This is expected to print a message indicating the driver name, a short summary of what it supports, and a list of the chipset names that it supports. It may use the xf86PrintChipsets() helper to do this.

    void xf86PrintChipsets(const char *drvname, const char *drvmsg,
                           SymTabPtr chips);
	  

This function provides an easy way for a driver's ChipIdentify function to format the identification message.

    Bool ChipProbe(DriverPtr drv, int flags);
	  

The purpose of this is to identify all instances of hardware supported by the driver. The flags value is currently either 0, PROBE_DEFAULT or PROBE_DETECT. PROBE_DETECT is used if "-configure" or "-probe" command line arguments are given and indicates to the Probe() function that it should not configure the bus entities and that no xorg.conf information is available.

The probe must find the active device sections that match the driver by calling xf86MatchDevice(). The number of matches found limits the maximum number of instances for this driver. If no matches are found, the function should return FALSE immediately.

Devices that cannot be identified by using device-independent methods should be probed at this stage (keeping in mind that access to all resources that can be disabled in a device-independent way are disabled during this phase). The probe must be a minimal probe. It should just determine if there is a card present that the driver can drive. It should use the least intrusive probe methods possible. It must not do anything that is not essential, like probing for other details such as the amount of memory installed, etc. It is recommended that the xf86MatchPciInstances() helper function be used for identifying matching PCI devices, and similarly the xf86MatchIsaInstances() for ISA (non-PCI) devices (see the RAC section). These helpers also checks and claims the appropriate entity. When not using the helper, that should be done with xf86CheckPciSlot() and xf86ClaimPciSlot() for PCI devices and xf86ClaimIsaSlot() for ISA devices (see the RAC section).

The probe must register all non-relocatable resources at this stage. If a resource conflict is found between exclusive resources the driver will fail immediately. This is usually best done with the xf86ConfigPciEntity() helper function for PCI and xf86ConfigIsaEntity() for ISA (see the RAC section). It is possible to register some entity specific functions with those helpers. When not using the helpers, the xf86AddEntityToScreen() xf86ClaimFixedResources() and xf86SetEntityFuncs() should be used instead (see the RAC section).

If a chipset is specified in an active device section which the driver considers relevant (ie it has no driver specified, or the driver specified matches the driver doing the probe), the Probe must return FALSE if the chipset doesn't match one supported by the driver.

If there are no active device sections that the driver considers relevant, it must return FALSE.

Allocate a ScrnInfoRec for each active instance of the hardware found, and fill in the basic information, including the other driver entry points. This is best done with the xf86ConfigIsaEntity() helper function for ISA instances or xf86ConfigPciEntity() for PCI instances. These functions allocate a ScrnInfoRec for active entities. Optionally xf86AllocateScreen() function may also be used to allocate the ScrnInfoRec. Any of these functions take care of initialising fields to defined “unused” values.

Claim the entities for each instance of the hardware found. This prevents other drivers from claiming the same hardware.

Must leave hardware in the same state it found it in, and must not do any hardware initialisation.

All detection can be overridden via the config file, and that parsed information is available to the driver at this stage.

Returns TRUE if one or more instances are found, and FALSE otherwise.

    int xf86MatchDevice(const char *drivername,
                        GDevPtr **driversectlist)
	  

This function takes the name of the driver and returns via driversectlist a list of device sections that match the driver name. The function return value is the number of matches found. If a fatal error is encountered the return value is -1.

The caller should use xfree() to free *driversectlist when it is no longer needed.

    ScrnInfoPtr xf86AllocateScreen(DriverPtr drv, int flags)
	  

This function allocates a new ScrnInfoRec in the xf86Screens[] array. This function is normally called by the video driver ChipProbe() functions. The return value is a pointer to the newly allocated ScrnInfoRec. The scrnIndex, origIndex, module and drv fields are initialised. The reference count in drv is incremented. The storage for any currently allocated “privates” pointers is also allocated and the privates field initialised (the privates data is of course not allocated or initialised). This function never returns on failure. If the allocation fails, the server exits with a fatal error. The flags value is not currently used, and should be set to zero.

    Bool ChipPreInit(ScrnInfoRec screen, int flags);
	  

The purpose of this function is to find out all the information required to determine if the configuration is usable, and to initialise those parts of the ScrnInfoRec that can be set once at the beginning of the first server generation.

The number of entities registered for the screen should be checked against the expected number (most drivers expect only one). The entity information for each of them should be retrieved (with xf86GetEntityInfo()) and checked for the correct bus type and that none of the sharable resources registered during the Probe phase was rejected.

Access to resources for the entities that can be controlled in a device-independent way are enabled before this function is called. If the driver needs to access any resources that it has disabled in an EntityInit() function that it registered, then it may enable them here providing that it disables them before this function returns.

This includes probing for video memory, clocks, ramdac, and all other HW info that is needed. It includes determining the depth/bpp/visual and related info. It includes validating and determining the set of video modes that will be used (and anything that is required to determine that).

This information should be determined in the least intrusive way possible. The state of the HW must remain unchanged by this function. Although video memory (including MMIO) may be mapped within this function, it must be unmapped before returning. Driver specific information should be stored in a structure hooked into the ScrnInfoRec's driverPrivate field. Any other modules which require persistent data (ie data that persists across server generations) should be initialised in this function, and they should allocate a “privates” index to hook their data into by calling xf86AllocateScrnInfoPrivateIndex(). The “privates” data is persistent.

Helper functions for some of these things are provided at the XFree86 common level, and the driver can choose to make use of them.

All additional resources that the screen needs must be registered here. This should be done with xf86RegisterResources(). If some of the fixed resources registered in the Probe phase are not needed or not decoded by the hardware when in the OPERATING server state, their status should be updated with xf86SetOperatingState().

Modules may be loaded at any point in this function, and all modules that the driver will need must be loaded before the end of this function. Either the xf86LoadSubModule() or the xf86LoadDrvSubModule() function should be used to load modules depending on whether a ScrnInfoRec has been set up. A driver may unload a module within this function if it was only needed temporarily, and the xf86UnloadSubModule() function should be used to do that. Otherwise there is no need to explicitly unload modules because the loader takes care of module dependencies and will unload submodules automatically if/when the driver module is unloaded.

The bulk of the ScrnInfoRec fields should be filled out in this function.

ChipPreInit() returns FALSE when the configuration is unusable in some way (unsupported depth, no valid modes, not enough video memory, etc), and TRUE if it is usable.

It is expected that if the ChipPreInit() function returns TRUE, then the only reasons that subsequent stages in the driver might fail are lack or resources (like xalloc failures). All other possible reasons for failure should be determined by the ChipPreInit() function.

    pointer xf86LoadSubModule(ScrnInfoPtr pScrn, const char *name);
      and
    pointer xf86LoadDrvSubModule(DriverPtr drv, const char *name);
	  

Load a module that a driver depends on. This function loads the module name as a sub module of the driver. The return value is a handle identifying the new module. If the load fails, the return value will be NULL. If a driver needs to explicitly unload a module it has loaded in this way, the return value must be saved and passed to xf86UnloadSubModule() when unloading.

    void xf86UnloadSubModule(pointer module);
	  

Unloads the module referenced by module. module should be a pointer returned previously by xf86LoadSubModule() or xf86LoadDrvSubModule() .

    Bool ChipScreenInit(int index, ScreenPtr pScreen,
                        int argc, char **argv);
	  

This is called at the start of each server generation.

Fill in all of pScreen, possibly doing some of this by calling ScreenInit functions from other layers like mi, framebuffers (cfb, etc), and extensions.

Decide which operations need to be placed under resource access control. The classes of operations are the frame buffer operations (RAC_FB), the pointer operations (RAC_CURSOR), the viewport change operations (RAC_VIEWPORT) and the colormap operations (RAC_COLORMAP). Any operation that requires resources which might be disabled during OPERATING state should be set to use RAC. This can be specified separately for memory and IO resources (the racMemFlags and racIoFlags fields of the ScrnInfoRec respectively).

Map any video memory or other memory regions.

Save the video card state. Enough state must be saved so that the original state can later be restored.

Initialise the initial video mode. The ScrnInfoRec's vtSema field should be set to TRUE just prior to changing the video hardware's state.

    Bool ChipSwitchMode(int index, DisplayModePtr mode, int flags);
	  

Initialises the new mode for the screen identified by index;. The viewport may need to be adjusted also.

    void ChipAdjustFrame(int index, int x, int y, int flags);
	  

Changes the viewport for the screen identified by index;.

It should be noted that many chipsets impose restrictions on where the viewport may be placed in the virtual resolution, either for alignment reasons, or to prevent the start of the viewport from being positioned within a pixel (as can happen in a 24bpp mode). After calculating the value the chipset's panning registers need to be set to for non-DGA modes, this function should recalculate the ScrnInfoRec's frameX0, frameY0, frameX1 and frameY1 fields to correspond to that value. If this is not done, switching to another mode might cause the position of a hardware cursor to change.

    Bool ChipEnterVT(int index, int flags);
	  

This function should initialise the current video mode and initialise the viewport, turn on the HW cursor if appropriate, etc.

Should it re-save the video state before initialising the video mode?

    void ChipLeaveVT(int index, int flags);
	  

This function should restore the saved video state. If appropriate it should also turn off the HW cursor, and invalidate any pixmap/font caches.

    (*pScreen->ModifyPixmapHeader)(pScrn->ppix,
                                   -1, -1, -1, -1, -1, NewApertureAddress);
	  

where the ppix field in a ScrnInfoRec points to the pixmap used by the screen's SaveRestoreImage() function to hold the screen's contents while switched out.

    Bool ChipCloseScreen(int index, ScreenPtr pScreen);
	  

This function should restore the saved video state and unmap the memory regions.

It should also free per-screen data structures allocated by the driver. Note that the persistent data held in the ScrnInfoRec's driverPrivate field should not be freed here because it is needed by subsequent server generations.

The ScrnInfoRec's vtSema field should be set to FALSE once the video HW state has been restored.

Before freeing the per-screen driver data the saved CloseScreen value should be restored to pScreen->CloseScreen, and that function should be called after freeing the data.

    ModeStatus ChipValidMode(int index, DisplayModePtr mode,
                             Bool verbose, int flags);
	  

Check the passed mode for hw-specific constraints, and return the appropriate status value.

    void ChipFreeScreen(int scrnindex, int flags);
	  

Free any driver-allocated data that may have been allocated up to and including an unsuccessful ChipScreenInit() call. This would predominantly be data allocated by ChipPreInit() that persists across server generations. It would include the driverPrivate, and any “privates” entries that modules may have allocated.

    void ChipSave(ScrnInfoPtr pScrn);
	  

Saves the current state. This will only be saving pre-server states or states before returning to the server. There is only one current saved state per screen and it is stored in private storage in the screen.

    void ChipRestore(ScrnInfoPtr pScrn);
	  

Restores the saved state from the private storage. Usually only used for restoring text modes.

    Bool ChipModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode);
	  

Programs the hardware for the given video mode.

    int xf86GetVerbosity();
	  

Returns the value of xf86Verbose.

    int xf86GetDepth();
	  

Returns the -depth command line setting. If not set on the command line, -1 is returned.

    rgb xf86GetWeight();
	  

Returns the -weight command line setting. If not set on the command line, {0, 0, 0} is returned.

    Gamma xf86GetGamma();
	  

Returns the -gamma or -rgamma, -ggamma, -bgamma command line settings. If not set on the command line, {0.0, 0.0, 0.0} is returned.

    Bool xf86GetFlipPixels();
	  

Returns TRUE if -flippixels is present on the command line, and FALSE otherwise.

    const char *xf86GetServerName();
	  

Returns the name of the X server from the command line.

command line -> config file -> probed/default data

    Bool xf86ServerIsExiting();
	  

Returns TRUE if the server is at the end of a generation and is in the process of exiting, and FALSE otherwise.

    Bool xf86ServerIsResetting();
	  

Returns TRUE if the server is at the end of a generation and is in the process of resetting, and FALSE otherwise.

    Bool xf86ServerIsInitialising();
	  

Returns TRUE if the server is at the beginning of a generation and is in the process of initialising, and FALSE otherwise.

    Bool xf86ServerIsOnlyProbing();
	  

Returns TRUE if the -probeonly command line flag was specified, and FALSE otherwise.

    Bool xf86CaughtSignal();
	  

Returns TRUE if the server has caught a signal, and FALSE otherwise.

    int AllocateScreenPrivateIndex();
	  

This function allocates a new element in the devPrivates field of all currently existing ScreenRecs. The return value is the index of this new element in the devPrivates array. The devPrivates field is of type DevUnion:

        typedef union _DevUnion {
            pointer             ptr;
            long                val;
            unsigned long       uval;
            pointer             (*fptr)(void);
        } DevUnion;
	      

which allows the element to be used for any of the above types. It is commonly used as a pointer to data that the caller allocates after the new index has been allocated.

This function will return -1 when there is an error allocating the new index.

    int xf86AllocateScrnInfoPrivateIndex();
	  

This function allocates a new element in the privates field of all currently existing ScrnInfoRecs. The return value is the index of this new element in the privates array. The privates field is of type DevUnion:

        typedef union _DevUnion {
            pointer             ptr;
            long                val;
            unsigned long       uval;
            pointer             (*fptr)(void);
        } DevUnion;
	      

which allows the element to be used for any of the above types. It is commonly used as a pointer to data that the caller allocates after the new index has been allocated.

This function will not return when there is an error allocating the new index. When there is an error it will cause the server to exit with a fatal error. The similar function for allocation privates in the ScreenRec (AllocateScreenPrivateIndex()) differs in this respect by returning -1 when the allocation fails.

All drivers should include these:


    "xf86.h"
    "xf86_OSproc.h"
    "xf86_ansic.h"
    "xf86Resources.h"
    

Wherever inb/outb (and related things) are used the following should be included:


    "compiler.h"
      

Note: in drivers, this must be included after "xf86_ansic.h".

Drivers that need to access the PCI config space need this:


    "xf86Pci.h"
      

Drivers that initialise a SW cursor need this:


    "mipointer.h"
      

All drivers implementing backing store need this:


    "mibstore.h"
      

All drivers using the mi colourmap code need this:


    "micmap.h"
      

If a driver uses the vgahw module, it needs this:


    "vgaHW.h"
      

Drivers supporting VGA or Hercules monochrome screens need:


    "xf1bpp.h"
      

Drivers supporting VGA or EGC 16-colour screens need:


    "xf4bpp.h"
      

Drivers using cfb need:

    #define PSZ 8
    #include "cfb.h"
    #undef PSZ
	    

Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:


    "cfb16.h"
    "cfb24.h"
    "cfb32.h"
      

If a driver uses XAA, it needs these:


    "xaa.h"
    "xaalocal.h"
      

If a driver uses the fb manager, it needs this:


    "xf86fbman.h"
      

    void LoaderInit(void);
	  

The LoaderInit() function initialises the loader, and it must be called once before calling any other loader functions. This function initialises the tables of exported symbols, and anything else that might need to be initialised.

    void LoaderSetPath(const char *path);
	  

The LoaderSetPath() function initialises a default module search path. This must be called if calls to other functions are to be made without explicitly specifying a module search path. The search path path must be a string of one or more comma separated absolute paths. Modules are expected to be located below these paths, possibly in subdirectories of these paths.

    pointer LoadModule(const char *module, const char *path,
                       const char **subdirlist, const char **patternlist,
                       pointer options, const XF86ModReqInfo * modreq,
                       int *errmaj, int *errmin);
	  

The LoadModule() function loads the module called module. The return value is a module handle, and may be used in future calls to the loader that require a reference to a loaded module. The module name module is normally the module's canonical name, which doesn't contain any directory path information, or any object/library file prefixes of suffixes. Currently a full pathname and/or filename is also accepted. This might change. The other parameters are:

path	An optional comma-separated list of module search paths. When NULL, the default search path is used.
subdirlist	An optional NULL terminated list of subdirectories to search. When NULL, the default built-in list is used (refer to stdSubdirs in loadmod.c). The default list is also substituted for entries in subdirlist with the value DEFAULT_LIST. This makes is possible to augment the default list instead of replacing it. Subdir elements must be relative, and must not contain "..". If any violate this requirement, the load fails.
patternlist	An optional NULL terminated list of POSIX regular expressions used to connect module filenames with canonical module names. Each regex should contain exactly one subexpression that corresponds to the canonical module name. When NULL, the default built-in list is used (refer to stdPatterns in loadmod.c). The default list is also substituted for entries in patternlist with the value DEFAULT_LIST. This makes it possible to augment the default list instead of replacing it.
options	An optional parameter that is passed to the newly loaded module's SetupProc function (if it has one). This argument is normally a NULL terminated list of Options, and must be interpreted that way by modules loaded directly by the XFree86 common layer. However, it may be used for application-specific parameter passing in other situations. When loading “external” modules (modules that don't have the standard entry point, for example a special shared library) the options parameter can be set to EXTERN_MODULE to tell the loader not to reject the module when it doesn't find the standard entry point.
modreq	An optional XF86ModReqInfo* containing version/ABI/vendor information to requirements to check the newly loaded module against. The main purpose of this is to allow the loader to verify that a module of the correct type/version before running its SetupProc function. The XF86ModReqInfo struct is defined as follows: typedef struct { CARD8 majorversion; /* MAJOR_UNSPEC */ CARD8 minorversion; /* MINOR_UNSPEC */ CARD16 patchlevel; /* PATCH_UNSPEC */ const char * abiclass; /* ABI_CLASS_NONE */ CARD32 abiversion; /* ABI_VERS_UNSPEC */ const char * moduleclass; /* MOD_CLASS_NONE */ } XF86ModReqInfo; The information here is compared against the equivalent information in the module's XF86ModuleVersionInfo record (which is described below). The values in comments above indicate “don't care” settings for each of the fields. The comparisons made are as follows: majorversion Must match the module's majorversion exactly. minorversion The module's minor version must be no less than this value. This comparison is only made if majorversion is specified and matches. patchlevel The module's patchlevel must be no less than this value. This comparison is only made if minorversion is specified and matches. abiclass String must match the module's abiclass string. abiversion Must be consistent with the module's abiversion (major equal, minor no older). moduleclass String must match the module's moduleclass string.
errmaj	An optional pointer to a variable holding the major part or the error code. When provided, *errmaj is filled in when LoadModule() fails.
errmin	Like errmaj, but for the minor part of the error code.

    void UnloadModule(pointer mod);
	  

This function unloads the module referred to by the handle mod. All child modules are also unloaded recursively. This function must not be used to directly unload modules that are child modules (i.e., those that have been loaded with the LoadSubModule() described below).

    typedef pointer (*ModuleSetupProc)(pointer, pointer, int *, int *);

    typedef void (*ModuleTearDownProc)(pointer);

    pointer SetupProc(pointer module, pointer options,
                      int *errmaj, int *errmin);
	    

When defined, this function is called by the loader after successfully loading a module. module is a handle for the newly loaded module, and maybe used by the SetupProc if it calls other loader functions that require a reference to it. The remaining arguments are those that were passed to the LoadModule() (or LoadSubModule()), and are described above. When the SetupProc is successful it must return a non-NULL value. The loader checks this, and if it is NULL it unloads the module and reports the failure to the caller of LoadModule(). If the SetupProc does things that need to be undone when the module is unloaded, it should define a TearDownProc, and return a pointer that the TearDownProc can use to undo what has been done.

When a module is loaded multiple times, the SetupProc is called once for each time it is loaded.

    void TearDownProc(pointer tearDownData);
	    

When defined, this function is called when the loader unloads a module. The tearDownData parameter is the return value of the SetupProc() that was called when the module was loaded. The purpose of this function is to clean up before the module is unloaded (for example, by freeing allocated resources).

    pointer LoadSubModule(pointer parent, const char *module,
                          const char **subdirlist, const char **patternlist,
                          pointer options, const XF86ModReqInfo * modreq,
                          int *errmaj, int *errmin);
	  

This function is like the LoadModule() function described above, except that the module loaded is registered as a child of the calling module. The parent parameter is the calling module's handle. Modules loaded with this function are automatically unloaded when the parent module is unloaded. The other difference is that the path parameter may not be specified. The module search path used for modules loaded with this function is the default search path as initialised with LoaderSetPath().

    void UnloadSubModule(pointer module);
	  

This function unloads the module with handle module. If that module itself has children, they are also unloaded. It is like UnloadModule(), except that it is safe to use for unloading child modules.

    pointer LoaderSymbol(const char *symbol);
	  

This function returns the address of the symbol with name symbol. This may be used to locate a module entry point with a known name.

    char **LoaderlistDirs(const char **subdirlist,
                          const char **patternlist);
	  

This function returns a NULL terminated list of canonical modules names for modules found in the default module search path. The subdirlist and patternlist parameters are as described above, and can be used to control the locations and names that are searched. If no modules are found, the return value is NULL. The returned list should be freed by calling LoaderFreeDirList() when it is no longer needed.

    void LoaderFreeDirList(char **list);
	  

This function frees a module list created by LoaderlistDirs().

    void LoaderReqSymLists(const char **list0, ...);
	  

This function allows the registration of required symbols with the loader. It is normally used by a caller of LoadSubModule(). If any symbols registered in this way are found to be unresolved when LoaderCheckUnresolved() is called then LoaderCheckUnresolved() will report a failure. The function takes one or more NULL terminated lists of symbols. The end of the argument list is indicated by a NULL argument.

    void LoaderReqSymbols(const char *sym0, ...);
	  

This function is like LoaderReqSymLists() except that its arguments are symbols rather than lists of symbols. This function is more convenient when single functions are to be registered, especially when the single function might depend on runtime factors. The end of the argument list is indicated by a NULL argument.

    void LoaderRefSymLists(const char **list0, ...);
	  

This function allows the registration of possibly unresolved symbols with the loader. When LoaderCheckUnresolved() is run it won't generate warnings for symbols registered in this way unless they were also registered as required symbols. The function takes one or more NULL terminated lists of symbols. The end of the argument list is indicated by a NULL argument.

    void LoaderRefSymbols(const char *sym0, ...);
	  

This function is like LoaderRefSymLists() except that its arguments are symbols rather than lists of symbols. This function is more convenient when single functions are to be registered, especially when the single function might depend on runtime factors. The end of the argument list is indicated by a NULL argument.

    int LoaderCheckUnresolved(int delayflag);
	  

This function checks for unresolved symbols. It generates warnings for unresolved symbols that have not been registered with LoaderRefSymLists(), and maps them to a dummy function. This behaviour may change in future. If unresolved symbols are found that have been registered with LoaderReqSymLists() or LoaderReqSymbols() then this function returns a non-zero value. If none of these symbols are unresolved the return value is zero, indicating success.

The delayflag parameter should normally be set to LD_RESOLV_IFDONE.

    LoaderErrorMsg(const char *name, const char *modname,
                   int errmaj, int errmin);
	  

This function prints an error message that includes the text “Failed to load module”, the module name modname, a message specific to the errmaj value, and the value if errmin. If name is non-NULL, it is printed as an identifying prefix to the message (followed by a “:”).

    void LoadExtension(ExtensionModule *ext);
	  

This registers the entry points for the extension identified by ext. The ExtensionModule struct is defined as:

typedef struct {
    InitExtension       initFunc;
    char *              name;
    Bool                *disablePtr;
    InitExtension       setupFunc;
} ExtensionModule;
	      

    void LoadFont(FontModule *font);
	  

This registers the entry points for the font rasteriser module identified by font. The FontModule struct is defined as:

 typedef struct {
    InitFont    initFunc;
    char *      name;
    pointer     module;
} FontModule;
	      

    ErrorF(const char *format, ...);
	  

This is the basic function for writing to the error log (typically stderr and/or a log file). Video drivers should usually avoid using this directly in favour of the more specialised functions described below. This function is useful for printing messages while debugging a driver.

    FatalError(const char *format, ...);
	  

This prints a message and causes the Xserver to abort. It should rarely be used within a video driver, as most error conditions should be flagged by the return values of the driver functions. This allows the higher layers to decide how to proceed. In rare cases, this can be used within a driver if a fatal unexpected condition is found.

    xf86ErrorF(const char *format, ...);
	  

This is like ErrorF(), except that the message is only printed when the Xserver's verbosity level is set to the default (1) or higher. It means that the messages are not printed when the server is started with the -quiet flag. Typically this function would only be used for continuing messages started with one of the more specialised functions described below.

    xf86ErrorFVerb(int verb, const char *format, ...);
	  

Like xf86ErrorF(), except the minimum verbosity level for which the message is to be printed is given explicitly. Passing a verb value of zero means the message is always printed. A value higher than 1 can be used for information would normally not be needed, but which might be useful when diagnosing problems.

    xf86Msg(MessageType type, const char *format, ...);
	  

This is like xf86ErrorF(), except that the message is prefixed with a marker determined by the value of type. The marker is used to indicate the type of message (warning, error, probed value, config value, etc). Note the xf86Verbose value is ignored for messages of type X_ERROR.

The marker values are:

X_PROBED	Value was probed.
X_CONFIG	Value was given in the config file.
X_DEFAULT	Value is a default.
X_CMDLINE	Value was given on the command line.
X_NOTICE	Notice.
X_ERROR	Error message.
X_WARNING	Warning message.
X_INFO	Informational message.
X_NONE	No prefix.
X_NOT_IMPLEMENTED	The message relates to functionality that is not yetimplemented.

    xf86MsgVerb(MessageType type, int verb, const char *format, ...);
	  

Like xf86Msg(), but with the verbosity level given explicitly.

    xf86DrvMsg(int scrnIndex, MessageType type, const char *format, ...);
	  

This is like xf86Msg() except that the driver's name (the name field of the ScrnInfoRec) followed by the scrnIndex in parentheses is printed following the prefix. This should be used by video drivers in most cases as it clearly indicates which driver/screen the message is for. If scrnIndex is negative, this function behaves exactly like xf86Msg().

NOTE: This function can only be used after the ScrnInfoRec and its name field have been allocated. Normally, this means that it can not be used before the END of the ChipProbe() function. Prior to that, use xf86Msg(), providing the driver's name explicitly. No screen number can be supplied at that point.

    xf86DrvMsgVerb(int scrnIndex, MessageType type, int verb,
                                const char *format, ...);
	  

Like xf86DrvMsg(), but with the verbosity level given explicitly.

    Bool xf86SetDepthBpp(ScrnInfoPtr scrp, int depth, int bpp,

                                int fbbpp, int depth24flags);
	  

This function sets the depth, pixmapBPP and bitsPerPixel fields of the ScrnInfoRec. It also determines the defaults for display-wide attributes and pixmap formats the screen will support, and finds the Display subsection that matches the depth/bpp. This function should normally be called very early from the ChipPreInit() function.

It requires that the confScreen field of the ScrnInfoRec be initialised prior to calling it. This is done by the XFree86 common layer prior to calling ChipPreInit().

The parameters passed are:

depth	driver's preferred default depth if no other is given. If zero, use the overall server default.
bpp	Same, but for the pixmap bpp.
fbbpp	Same, but for the framebuffer bpp.
depth24flags	Flags that indicate the level of 24/32bpp support and whether conversion between different framebuffer and pixmap formats is supported. The flags for this argument are defined as follows, and multiple flags may be ORed together: NoDepth24Support No depth 24 formats supported Support24bppFb 24bpp framebuffer supported Support32bppFb 32bpp framebuffer supported SupportConvert24to32 Can convert 24bpp pixmap to 32bpp fb SupportConvert32to24 Can convert 32bpp pixmap to 24bpp fb ForceConvert24to32 Force 24bpp pixmap to 32bpp fb conversion ForceConvert32to24 Force 32bpp pixmap to 24bpp fb conversion

It uses the command line, config file, and default values in the correct order of precedence to determine the depth and bpp values. It is up to the driver to check the results to see that it supports them. If not the ChipPreInit() function should return FALSE.

If only one of depth/bpp is given, the other is set to a reasonable (and consistent) default.

If a driver finds that the initial depth24flags it uses later results in a fb format that requires more video memory than is available it may call this function a second time with a different depth24flags setting.

On success, the return value is TRUE. On failure it prints an error message and returns FALSE.

The following fields of the ScrnInfoRec are initialised by this function:

depth, bitsPerPixel, display, imageByteOrder, bitmapScanlinePad, bitmapScanlineUnit, bitmapBitOrder, numFormats, formats, fbFormat.

    void xf86PrintDepthBpp(scrnInfoPtr scrp);
	  

This function can be used to print out the depth and bpp settings. It should be called after the final call to xf86SetDepthBpp().

    Bool xf86SetWeight(ScrnInfoPtr scrp, rgb weight, rgb mask);
	  

This function sets the weight, mask, offset and rgbBits fields of the ScrnInfoRec. It would normally be called fairly early in the ChipPreInit() function for depths > 8bpp.

It requires that the depth and display fields of the ScrnInfoRec be initialised prior to calling it.

The parameters passed are:

weight	driver's preferred default weight if no other is given. If zero, use the overall server default.
mask	Same, but for mask.

It uses the command line, config file, and default values in the correct order of precedence to determine the weight value. It derives the mask and offset values from the weight and the defaults. It is up to the driver to check the results to see that it supports them. If not the ChipPreInit() function should return FALSE.

On success, this function prints a message showing the weight values selected, and returns TRUE.

On failure it prints an error message and returns FALSE.

The following fields of the ScrnInfoRec are initialised by this function:

weight, mask, offset.

    Bool xf86SetDefaultVisual(ScrnInfoPtr scrp, int visual);
	  

This function sets the defaultVisual field of the ScrnInfoRec. It would normally be called fairly early from the ChipPreInit() function.

It requires that the depth and display fields of the ScrnInfoRec be initialised prior to calling it.

The parameters passed are:

visual

driver's preferred default visual if no other is given. If -1, use the overall server default.

It uses the command line, config file, and default values in the correct order of precedence to determine the default visual value. It is up to the driver to check the result to see that it supports it. If not the ChipPreInit() function should return FALSE.

On success, this function prints a message showing the default visual selected, and returns TRUE.

On failure it prints an error message and returns FALSE.

    Bool xf86SetGamma(ScrnInfoPtr scrp, Gamma gamma);
	  

This function sets the gamma field of the ScrnInfoRec. It would normally be called fairly early from the ChipPreInit() function in cases where the driver supports gamma correction.

It requires that the monitor field of the ScrnInfoRec be initialised prior to calling it.

The parameters passed are:

gamma

driver's preferred default gamma if no other is given. If zero (< 0.01), use the overall server default.

It uses the command line, config file, and default values in the correct order of precedence to determine the gamma value. It is up to the driver to check the results to see that it supports them. If not the ChipPreInit() function should return FALSE.

On success, this function prints a message showing the gamma value selected, and returns TRUE.

On failure it prints an error message and returns FALSE.

    void xf86SetDpi(ScrnInfoPtr pScrn, int x, int y);
	  

This function sets the xDpi and yDpi fields of the ScrnInfoRec. The driver can specify preferred defaults by setting x and y to non-zero values. The -dpi command line option overrides all other settings. Otherwise, if the DisplaySize entry is present in the screen's Monitor config file section, it is used together with the virtual size to calculate the dpi values. This function should be called after all the mode resolution has been done.

    void xf86SetBlackWhitePixels(ScrnInfoPtr pScrn);
	  

This functions sets the blackPixel and whitePixel fields of the ScrnInfoRec according to whether or not the -flipPixels command line options is present.

    const char *xf86GetVisualName(int visual);
	  

Returns a printable string with the visual name matching the numerical visual class provided. If the value is outside the range of valid visual classes, NULL is returned.

    int xf86ValidateModes(ScrnInfoPtr scrp, DisplayModePtr availModes,
                          char **modeNames, ClockRangePtr clockRanges,
                          int *linePitches, int minPitch, int maxPitch,
                          int pitchInc, int minHeight, int maxHeight,
                          int virtualX, int virtualY,
                          unsigned long apertureSize,
                          LookupModeFlags strategy);
	  

This function basically selects the set of modes to use based on those available and the various constraints. It also sets some other related parameters. It is normally called near the end of the ChipPreInit() function.

The parameters passed to the function are:

availModes	List of modes available for the monitor.
modeNames	List of mode names that the screen is requesting.
clockRanges	A list of clock ranges allowed by the driver. Each range includes whether interlaced or multiscan modes are supported for that range. See below for more on clockRanges.
linePitches	List of line pitches supported by the driver. This is optional and should be NULL when not used.
minPitch	Minimum line pitch supported by the driver. This must be supplied when linePitches is NULL, and is ignored otherwise.
maxPitch	Maximum line pitch supported by the driver. This is required when minPitch is required.
pitchInc	Granularity of horizontal pitch values as supported by the chipset. This is expressed in bits. This must be supplied.
minHeight	minimum virtual height allowed. If zero, no limit is imposed.
maxHeight	maximum virtual height allowed. If zero, no limit is imposed.
virtualX	If greater than zero, this is the virtual width value that will be used. Otherwise, the virtual width is chosen to be the smallest that can accommodate the modes selected.
virtualY	If greater than zero, this is the virtual height value that will be used. Otherwise, the virtual height is chosen to be the smallest that can accommodate the modes selected.
apertureSize	The size (in bytes) of the aperture used to access video memory.
strategy	The strategy to use when choosing from multiple modes with the same name. The options are: LOOKUP_DEFAULT ??? LOOKUP_BEST_REFRESH mode with best refresh rate LOOKUP_CLOSEST_CLOCK mode with closest matching clock LOOKUP_LIST_ORDER first usable mode in list The following options can also be combined (OR'ed) with one of the above: LOOKUP_CLKDIV2 Allow halved clocks LOOKUP_OPTIONAL_TOLERANCES Allow missing horizontal sync and/or vertical refresh ranges in the xorg.conf Monitor section LOOKUP_OPTIONAL_TOLERANCES should only be specified when the driver can ensure all modes it generates can sync on, or at least not damage, the monitor or digital flat panel. Horizontal sync and/or vertical refresh ranges specified by the user will still be honoured (and acted upon).

This function requires that the following fields of the ScrnInfoRec are initialised prior to calling it:

clock[]	List of discrete clocks (when non-programmable)
numClocks	Number of discrete clocks (when non-programmable)
progClock	Whether the clock is programmable or not
monitor	Pointer to the applicable xorg.conf monitor section
fdFormat	Format of the screen buffer
videoRam	total video memory size (in bytes)
maxHValue	Maximum horizontal timing value allowed
maxVValue	Maximum vertical timing value allowed
xInc	Horizontal timing increment in pixels (defaults to 8)

This function fills in the following ScrnInfoRec fields:

modePool	A subset of the modes available to the monitor which are compatible with the driver.
modes	One mode entry for each of the requested modes, with the status field of each filled in to indicate if the mode has been accepted or not. This list of modes is a circular list.
virtualX	The resulting virtual width.
virtualY	The resulting virtual height.
displayWidth	The resulting line pitch.
virtualFrom	Where the virtual size was determined from.

The first stage of this function checks that the virtualX and virtualY values supplied (if greater than zero) are consistent with the line pitch and maxHeight limitations. If not, an error message is printed, and the return value is -1.

The second stage sets up the mode pool, eliminating immediately any modes that exceed the driver's line pitch limits, and also the virtual width and height limits (if greater than zero). For each mode removed an informational message is printed at verbosity level 2. If the mode pool ends up being empty, a warning message is printed, and the return value is 0.

The final stage is to lookup each mode name, and fill in the remaining parameters. If an error condition is encountered, a message is printed, and the return value is -1. Otherwise, the return value is the number of valid modes found (0 if none are found).

Even if the supplied mode names include duplicates, no two names will ever match the same mode. Furthermore, if the supplied mode names do not yield a valid mode (including the case where no names are passed at all), the function will continue looking through the mode pool until it finds a mode that survives all checks, or until the mode pool is exhausted.

A message is only printed by this function when a fundamental problem is found. It is intended that this function may be called more than once if there is more than one set of constraints that the driver can work within.

If this function returns -1, the ChipPreInit() function should return FALSE.

clockRanges is a linked list of clock ranges allowed by the driver. If a mode doesn't fit in any of the defined clockRanges, it is rejected. The first clockRange that matches all requirements is used. This structure needs to be initialized to NULL when allocated.

clockRanges contains the following fields:

minClock, maxClock	The lower and upper mode clock bounds for which the rest of the clockRange parameters apply. Since these are the mode clocks, they are not scaled with the ClockMulFactor and ClockDivFactor. It is up to the driver to adjust these values if they depend on the clock scaling factors.
clockIndex	(not used yet) -1 for programmable clocks
interlaceAllowed	TRUE if interlacing is allowed for this range
doubleScanAllowed	TRUE if doublescan or multiscan is allowed for this range
ClockMulFactor, ClockDivFactor	Scaling factors that are applied to the mode clocks ONLY before selecting a clock index (when there is no programmable clock) or a SynthClock value. This is useful for drivers that support pixel multiplexing or that need to scale the clocks because of hardware restrictions (like sending 24bpp data to an 8 bit RAMDAC using a tripled clock). Note that these parameters describe what must be done to the mode clock to achieve the data transport clock between graphics controller and RAMDAC. For example for 2:1 pixel multiplexing, two pixels are sent to the RAMDAC on each clock. This allows the RAMDAC clock to be half of the actual pixel clock. Hence, ClockMulFactor=1 and ClockDivFactor=2. This means that the clock used for clock selection (ie, determining the correct clock index from the list of discrete clocks) or for the SynthClock field in case of a programmable clock is: (mode->Clock * ClockMulFactor) / ClockDivFactor.
PrivFlags	This field is copied into the mode->PrivFlags field when this clockRange is selected by xf86ValidateModes(). It allows the driver to find out what clock range was selected, so it knows it needs to set up pixel multiplexing or any other range-dependent feature. This field is purely driver-defined: it may contain flag bits, an index or anything else (as long as it is an INT).

Note that the mode->SynthClock field is always filled in by xf86ValidateModes(): it will contain the “data transport clock”, which is the clock that will have to be programmed in the chip when it has a programmable clock, or the clock that will be picked from the clocks list when it is not a programmable one. Thus:

    mode->SynthClock = (mode->Clock * ClockMulFactor) / ClockDivFactor
	      

    void xf86PruneDriverModes(ScrnInfoPtr scrp);
	  

This function deletes modes in the modes field of the ScrnInfoRec that have been marked as invalid. This is normally run after having run xf86ValidateModes() for the last time. For each mode that is deleted, a warning message is printed out indicating the reason for it being deleted.

    void xf86SetCrtcForModes(ScrnInfoPtr scrp, int adjustFlags);
	  

This function fills in the Crtc* fields for all the modes in the modes field of the ScrnInfoRec. The adjustFlags parameter determines how the vertical CRTC values are scaled for interlaced modes. They are halved if it is INTERLACE_HALVE_V. The vertical CRTC values are doubled for doublescan modes, and are further multiplied by the VScan value.

This function is normally called after calling xf86PruneDriverModes().

    void xf86PrintModes(ScrnInfoPtr scrp);
	  

This function prints out the virtual size setting, and the line pitch being used. It also prints out two lines for each mode being used. The first line includes the mode's pixel clock, horizontal sync rate, refresh rate, and whether it is interlaced, doublescanned and/or multi-scanned. The second line is the mode's Modeline.

This function is normally called after calling xf86SetCrtcForModes().

    int xf86GetNearestClock(ScrnInfoPtr scrp, int freq, Bool allowDiv2,
                            int *divider);
	  

This function returns the index of the closest clock to the frequency freq given (in kHz). It assumes that the number of clocks is greater than zero. It requires that the numClocks and clock fields of the ScrnInfoRec are initialised. The allowDiv2 field determines if the clocks can be halved. The *divider return value indicates whether clock division is used when determining the clock returned.

This function is only for non-programmable clocks.

    const char *xf86ModeStatusToString(ModeStatus status);
	  

This function converts the status value to a descriptive printable string.

    ModeStatus xf86LookupMode(ScrnInfoPtr scrp, DisplayModePtr modep,
                     ClockRangePtr clockRanges, LookupModeFlags strategy);
	  

This function takes a pointer to a mode with the name filled in, and looks for a mode in the modePool list which matches. The parameters of the matching mode are filled in to *modep. The clockRanges and strategy parameters are as for the xf86ValidateModes() function above.

This function requires the modePool, clock[], numClocks and progClock fields of the ScrnInfoRec to be initialised before being called.

The return value is MODE_OK if a mode was found. Otherwise it indicates why a matching mode could not be found.

    ModeStatus xf86InitialCheckModeForDriver(ScrnInfoPtr scrp,
                                DisplayModePtr mode, ClockRangePtr clockRanges,
                                LookupModeFlags strategy, int maxPitch,
                                int virtualX, int virtualY);
	  

This function checks the passed mode against some basic driver constraints. Apart from the ones passed explicitly, the maxHValue and maxVValue fields of the ScrnInfoRec are also used. If the ValidMode field of the ScrnInfoRec is set, that function is also called to check the mode. Next, the mode is checked against the monitor's constraints.

If the mode is consistent with all constraints, the return value is MODE_OK. Otherwise the return value indicates which constraint wasn't met.

    void xf86DeleteMode(DisplayModePtr *modeList, DisplayModePtr mode);
	  

This function deletes the mode given from the modeList. It never prints any messages, so it is up to the caller to print a message if required.

    const char *xf86TokenToString(SymTabPtr table, int token);
	  

This function returns the first string in table that matches token. If no match is found, NULL is returned (NOTE, older versions of this function would return the string "unknown" when no match is found).

    int xf86StringToToken(SymTabPtr table, const char *string);
	  

This function returns the first token in table that matches string. The xf86NameCmp() function is used to determine the match. If no match is found, -1 is returned.

    void xf86GetClocks(ScrnInfoPtr pScrn, int num,
                       Bool (*ClockFunc)(ScrnInfoPtr, int),
                       void (*ProtectRegs)(ScrnInfoPtr, Bool),
                       void (*BlankScreen)(ScrnInfoPtr, Bool),
                       int vertsyncreg, int maskval, int knownclkindex,
                       int knownclkvalue);
	  

This function uses a comparative sampling method to measure the discrete pixel clock values. The number of discrete clocks to measure is given by num. clockFunc is a function that selects the n'th clock. It should also save or restore any state affected by programming the clocks when the index passed is CLK_REG_SAVE or CLK_REG_RESTORE. ProtectRegs is a function that does whatever is required to protect the hardware state while selecting a new clock. BlankScreen is a function that blanks the screen. vertsyncreg and maskval are the register and bitmask to check for the presence of vertical sync pulses. knownclkindex and knownclkvalue are the index and value of a known clock. These are the known references on which the comparative measurements are based. The number of clocks probed is set in pScrn->numClocks, and the probed clocks are set in the pScrn->clock[] array. All of the clock values are in units of kHz.

    void xf86ShowClocks(ScrnInfoPtr scrp, MessageType from);
	  

Print out the pixel clocks scrp->clock[]. from indicates whether the clocks were probed or from the config file.

    Bool xf86IsUnblank(int mode);
	  

Returns TRUE when the screen saver mode specified by mode requires the screen be unblanked, and FALSE otherwise. The screen saver modes that require blanking are SCREEN_SAVER_ON and SCREEN_SAVER_CYCLE, and the screen saver modes that require unblanking are SCREEN_SAVER_OFF and SCREEN_SAVER_FORCER. Drivers may call this helper from their SaveScreen() function to interpret the screen saver modes.

    Bool vgaHWGetHWRec(ScrnInfoPtr pScrn);
	  

This function allocates a vgaHWRec structure, and hooks it into the ScrnInfoRec's privates. Like all information hooked into the privates, it is persistent, and only needs to be allocated once per screen. This function should normally be called from the driver's ChipPreInit() function. The vgaHWRec is zero-allocated, and the following fields are explicitly initialised:

ModeReg.DAC[]	initialised with a default colourmap
ModeReg.Attribute[0x11]	initialised with the default overscan index
ShowOverscan	initialised according to the "ShowOverscan" option
paletteEnabled	initialised to FALSE
cmapSaved	initialised to FALSE
pScrn	initialised to pScrn

In addition to the above, vgaHWSetStdFuncs() is called to initialise the register access function fields with the standard VGA set of functions.

Once allocated, a pointer to the vgaHWRec can be obtained from the ScrnInfoPtr with the VGAHWPTR(pScrn) macro.

    void vgaHWFreeHWRec(ScrnInfoPtr pScrn);
	  

This function frees a vgaHWRec structure. It should be called from a driver's ChipFreeScreen() function.

    Bool vgaHWSetRegCounts(ScrnInfoPtr pScrn, int numCRTC,
                          int numSequencer, int numGraphics, int numAttribute);
	  

This function allows the number of CRTC, Sequencer, Graphics and Attribute registers to be changed. This makes it possible for extended registers to be saved and restored with vgaHWSave() and vgaHWRestore(). This function should be called after a vgaHWRec has been allocated with vgaHWGetHWRec(). The default values are defined in vgaHW.h as follows:

#define VGA_NUM_CRTC 25
#define VGA_NUM_SEQ   5
#define VGA_NUM_GFX   9
#define VGA_NUM_ATTR 21
	      

    Bool vgaHWCopyReg(vgaRegPtr dst, vgaRegPtr src);
	  

This function copies the contents of the VGA saved registers in src to dst. Note that it isn't possible to simply do this with memcpy() (or similar). This function returns TRUE unless there is a problem allocating space for the CRTC and related fields in dst.

    void vgaHWSetStdFuncs(vgaHWPtr hwp);
	  

This function initialises the register access function fields of hwp with the standard VGA set of functions. This is called by vgaHWGetHWRec(), so there is usually no need to call this explicitly. The register access functions are described below. If the registers are shadowed in some other port I/O space (for example a PCI I/O region), these functions can be used to access the shadowed registers if hwp->PIOOffset is initialised with offset, calculated in such a way that when the standard VGA I/O port value is added to it the correct offset into the PIO area results. This value is initialised to zero in vgaHWGetHWRec(). (Note: the PIOOffset functionality is present in XFree86 4.1.0 and later.)

    void vgaHWSetMmioFuncs(vgaHWPtr hwp, CARD8 *base, int offset);
	  

This function initialised the register access function fields of hwp with a generic MMIO set of functions. hwp->MMIOBase is initialised with base, which must be the virtual address that the start of MMIO area is mapped to. hwp->MMIOOffset is initialised with offset, which must be calculated in such a way that when the standard VGA I/O port value is added to it the correct offset into the MMIO area results. That means that these functions are only suitable when the VGA I/O ports are made available in a direct mapping to the MMIO space. If that is not the case, the driver will need to provide its own register access functions. The register access functions are described below.

    Bool vgaHWMapMem(ScrnInfoPtr pScrn);
	  

This function maps the VGA memory window. It requires that the vgaHWRec be allocated. If a driver requires non-default MapPhys or MapSize settings (the physical location and size of the VGA memory window) then those fields of the vgaHWRec must be initialised before calling this function. Otherwise, this function initialiases the default values of 0xA0000 for MapPhys and (64 * 1024) for MapSize. This function must be called before attempting to save or restore the VGA state. If the driver doesn't call it explicitly, the vgaHWSave() and vgaHWRestore() functions may call it if they need to access the VGA memory (in which case they will also call vgaHWUnmapMem() to unmap the VGA memory before exiting).

    void vgaHWUnmapMem(ScrnInfoPtr pScrn);
	  

This function unmaps the VGA memory window. It must only be called after the memory has been mapped. The Base field of the vgaHWRec field is set to NULL to indicate that the memory is no longer mapped.

    void vgaHWGetIOBase(vgaHWPtr hwp);
	  

This function initialises the IOBase field of the vgaHWRec. This function must be called before using any other functions that access the video hardware.

A macro VGAHW_GET_IOBASE() is also available in vgaHW.h that returns the I/O base, and this may be used when the vgahw module is not loaded (for example, in the ChipProbe() function).

    void vgaHWUnlock(vgaHWPtr hwp);
	  

This function unlocks the VGA CRTC[0-7] registers, and must be called before attempting to write to those registers.

    void vgaHWLock(vgaHWPtr hwp);
	  

This function locks the VGA CRTC[0-7] registers.

    void vgaHWEnable(vgaHWPtr hwp);
	  

This function enables the VGA subsystem. (Note, this function is present in XFree86 4.1.0 and later.).

    void vgaHWDisable(vgaHWPtr hwp);
	  

This function disables the VGA subsystem. (Note, this function is present in XFree86 4.1.0 and later.).

    void vgaHWSave(ScrnInfoPtr pScrn, vgaRegPtr save, int flags);
	  

This function saves the VGA state. The state is written to the vgaRegRec pointed to by save. flags is set to one or more of the following flags ORed together:

VGA_SR_MODE	the mode setting registers are saved
VGA_SR_FONTS	the text mode font/text data is saved
VGA_SR_CMAP	the colourmap (LUT) is saved
VGA_SR_ALL	all of the above are saved

The vgaHWRec and its IOBase fields must be initialised before this function is called. If VGA_SR_FONTS is set in flags, the VGA memory window must be mapped. If it isn't then vgaHWMapMem() will be called to map it, and vgaHWUnmapMem() will be called to unmap it afterwards. vgaHWSave() uses the three functions below in the order vgaHWSaveColormap(), vgaHWSaveMode(), vgaHWSaveFonts() to carry out the different save phases. It is undecided at this stage whether they will remain part of the vgahw module's public interface or not.

    void vgaHWSaveMode(ScrnInfoPtr pScrn, vgaRegPtr save);
	  

This function saves the VGA mode registers. They are saved to the vgaRegRec pointed to by save. The registers saved are:

        MiscOut
        CRTC[0-0x18]
        Attribute[0-0x14]
        Graphics[0-8]
        Sequencer[0-4]
      

The number of registers actually saved may be modified by a prior call to vgaHWSetRegCounts().

    void vgaHWSaveFonts(ScrnInfoPtr pScrn, vgaRegPtr save);
	  

This function saves the text mode font and text data held in the video memory. If called while in a graphics mode, no save is done. The VGA memory window must be mapped with vgaHWMapMem() before to calling this function.

On some platforms, one or more of the font/text plane saves may be no-ops. This is the case when the platform's VC driver already takes care of this.

    void vgaHWSaveColormap(ScrnInfoPtr pScrn, vgaRegPtr save);
	  

This function saves the VGA colourmap (LUT). Before saving it, it attempts to verify that the colourmap is readable. In rare cases where it isn't readable, a default colourmap is saved instead.

    void vgaHWRestore(ScrnInfoPtr pScrn, vgaRegPtr restore, int flags);
	  

This function programs the VGA state. The state programmed is that contained in the vgaRegRec pointed to by restore. flags is the same as described above for the vgaHWSave() function.

The vgaHWRec and its IOBase fields must be initialised before this function is called. If VGA_SR_FONTS is set in flags, the VGA memory window must be mapped. If it isn't then vgaHWMapMem() will be called to map it, and vgaHWUnmapMem() will be called to unmap it afterwards. vgaHWRestore() uses the three functions below in the order vgaHWRestoreFonts(), vgaHWRestoreMode(), vgaHWRestoreColormap() to carry out the different restore phases. It is undecided at this stage whether they will remain part of the vgahw module's public interface or not.

    void vgaHWRestoreMode(ScrnInfoPtr pScrn, vgaRegPtr restore);
	  

This function restores the VGA mode registers. They are restored from the data in the vgaRegRec pointed to by restore. The registers restored are:

        MiscOut
        CRTC[0-0x18]
        Attribute[0-0x14]
        Graphics[0-8]
        Sequencer[0-4]
      

The number of registers actually restored may be modified by a prior call to vgaHWSetRegCounts().

    void vgaHWRestoreFonts(ScrnInfoPtr pScrn, vgaRegPtr restore);
	  

This function restores the text mode font and text data to the video memory. The VGA memory window must be mapped with vgaHWMapMem() before to calling this function.

On some platforms, one or more of the font/text plane restores may be no-ops. This is the case when the platform's VC driver already takes care of this.

    void vgaHWRestoreColormap(ScrnInfoPtr pScrn, vgaRegPtr restore);
	  

This function restores the VGA colourmap (LUT).

    void vgaHWInit(ScrnInfoPtr pScrn, DisplayModePtr mode);
	  

This function fills in the vgaHWRec's ModeReg field with the values appropriate for programming the given video mode. It requires that the ScrnInfoRec's depth field is initialised, which determines how the registers are programmed.

    void vgaHWSeqReset(vgaHWPtr hwp, Bool start);
	  

Do a VGA sequencer reset. If start is TRUE, the reset is started. If start is FALSE, the reset is ended.

    void vgaHWProtect(ScrnInfoPtr pScrn, Bool on);
	  

This function protects VGA registers and memory from corruption during loads. It is typically called with on set to TRUE before programming, and with on set to FALSE after programming.

    Bool vgaHWSaveScreen(ScreenPtr pScreen, int mode);
	  

This function blanks and unblanks the screen. It is blanked when mode is SCREEN_SAVER_ON or SCREEN_SAVER_CYCLE, and unblanked when mode is SCREEN_SAVER_OFF or SCREEN_SAVER_FORCER.

    void vgaHWBlankScreen(ScrnInfoPtr pScrn, Bool on);
	  

This function blanks and unblanks the screen. It is blanked when on is FALSE, and unblanked when on is TRUE. This function is provided for use in cases where the ScrnInfoRec can't be derived from the ScreenRec (while probing for clocks, for example).

    Bool vgaHWHandleColormaps(ScreenPtr pScreen);
	    

    void writeCrtc(vgaHWPtr hwp, CARD8 index, CARD8 value);
	  

Write value to CRTC register index.

    CARD8 readCrtc(vgaHWPtr hwp, CARD8 index);
	  

Return the value read from CRTC register index.

    void writeGr(vgaHWPtr hwp, CARD8 index, CARD8 value);
	  

Write value to Graphics Controller register index.

    CARD8 readGR(vgaHWPtr hwp, CARD8 index);
	  

Return the value read from Graphics Controller register index.

    void writeSeq(vgaHWPtr hwp, CARD8 index, CARD8, value);
	  

Write value to Sequencer register index.

    CARD8 readSeq(vgaHWPtr hwp, CARD8 index);
	  

Return the value read from Sequencer register index.

    void writeAttr(vgaHWPtr hwp, CARD8 index, CARD8, value);
	  

Write value to Attribute Controller register index. When writing out the index value this function should set bit 5 (0x20) according to the setting of hwp->paletteEnabled in order to preserve the palette access state. It should be cleared when hwp->paletteEnabled is TRUE and set when it is FALSE.

    CARD8 readAttr(vgaHWPtr hwp, CARD8 index);
	  

Return the value read from Attribute Controller register index. When writing out the index value this function should set bit 5 (0x20) according to the setting of hwp->paletteEnabled in order to preserve the palette access state. It should be cleared when hwp->paletteEnabled is TRUE and set when it is FALSE.

    void writeMiscOut(vgaHWPtr hwp, CARD8 value);
	  

Write “value” to the Miscellaneous Output register.

    CARD8 readMiscOut(vgwHWPtr hwp);
	  

Return the value read from the Miscellaneous Output register.

    void enablePalette(vgaHWPtr hwp);
	  

Clear the palette address source bit in the Attribute Controller index register and set hwp->paletteEnabled to TRUE.

    void disablePalette(vgaHWPtr hwp);
	  

Set the palette address source bit in the Attribute Controller index register and set hwp->paletteEnabled to FALSE.

    void writeDacMask(vgaHWPtr hwp, CARD8 value);
	  

Write value to the DAC Mask register.

    CARD8 readDacMask(vgaHWptr hwp);
	  

Return the value read from the DAC Mask register.

    void writeDacReadAddress(vgaHWPtr hwp, CARD8 value);
	  

Write value to the DAC Read Address register.

    void writeDacWriteAddress(vgaHWPtr hwp, CARD8 value);
	  

Write value to the DAC Write Address register.

    void writeDacData(vgaHWPtr hwp, CARD8 value);
	  

Write value to the DAC Data register.

    CARD8 readDacData(vgaHWptr hwp);
	  

Return the value read from the DAC Data register.

    CARD8 readEnable(vgaHWptr hwp);
	  

Return the value read from the VGA Enable register. (Note: This function is present in XFree86 4.1.0 and later.)

    void writeEnable(vgaHWPtr hwp, CARD8 value);
	  

Write value to the VGA Enable register. (Note: This function is present in XFree86 4.1.0 and later.)