19. The vgahw module

The vgahw modules provides an interface for saving, restoring and programming the standard VGA registers, and for handling VGA colourmaps.

19.1. Data Structures

The public data structures used by the vgahw module are vgaRegRec and vgaHWRec. They are defined in vgaHW.h.

19.2. General vgahw Functions

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).

19.3. VGA Colormap Functions

The vgahw module uses the standard colormap support (see the Colormap Handling section. This is initialised with the following function:

Bool vgaHWHandleColormaps(ScreenPtr pScreen)

19.4. VGA Register Access Functions

The vgahw module abstracts access to the standard VGA registers by using a set of functions held in the vgaHWRec. When the vgaHWRec is created these function pointers are initialised with the set of standard VGA I/O register access functions. In addition to these, the vgahw module includes a basic set of MMIO register access functions, and the vgaHWRec function pointers can be initialised to these by calling the vgaHWSetMmioFuncs() function described above. Some drivers/platforms may require a different set of functions for VGA access. The access functions are described here.

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.)