The vgahw modules provides an interface for saving, restoring and programming the standard VGA registers, and for handling VGA colourmaps.
The public data structures used by the vgahw module are
vgaRegRec
and vgaHWRec
. They are
defined in vgaHW.h.
Bool vgaHWGetHWRec(ScrnInfoPtr pScrn)
This function allocates a
vgaHWRec
structure, and hooks it into theScrnInfoRec
'sprivates
. Like all information hooked into theprivates
, it is persistent, and only needs to be allocated once per screen. This function should normally be called from the driver'sChipPreInit()
function. ThevgaHWRec
is zero-allocated, and the following fields are explicitly initialised:
ModeReg.DAC[]
initialised with a default colourmapModeReg.Attribute[0x11]
initialised with the default overscan indexShowOverscan
initialised according to the "ShowOverscan" optionpaletteEnabled
initialised to FALSEcmapSaved
initialised to FALSEpScrn
initialised to pScrnIn 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 theScrnInfoPtr
with theVGAHWPTR(pScrn)
macro.
void vgaHWFreeHWRec(ScrnInfoPtr pScrn)
This function frees a
vgaHWRec
structure. It should be called from a driver'sChipFreeScreen()
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()
andvgaHWRestore()
. This function should be called after avgaHWRec
has been allocated withvgaHWGetHWRec()
. The default values are defined invgaHW.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
todst
. Note that it isn't possible to simply do this withmemcpy()
(or similar). This function returnsTRUE
unless there is a problem allocating space for theCRTC
and related fields indst
.
void vgaHWSetStdFuncs(vgaHWPtr hwp)
This function initialises the register access function fields of
hwp
with the standard VGA set of functions. This is called byvgaHWGetHWRec()
, 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 ifhwp->PIOOffset
is initialised withoffset
, 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 invgaHWGetHWRec()
. (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 withbase
, which must be the virtual address that the start of MMIO area is mapped to.hwp->MMIOOffset
is initialised withoffset
, 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-defaultMapPhys
orMapSize
settings (the physical location and size of the VGA memory window) then those fields of thevgaHWRec
must be initialised before calling this function. Otherwise, this function initialiases the default values of0xA0000
forMapPhys
and(64 * 1024)
forMapSize
. This function must be called before attempting to save or restore the VGA state. If the driver doesn't call it explicitly, thevgaHWSave()
andvgaHWRestore()
functions may call it if they need to access the VGA memory (in which case they will also callvgaHWUnmapMem()
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 thevgaHWRec
field is set toNULL
to indicate that the memory is no longer mapped.
void vgaHWGetIOBase(vgaHWPtr hwp)
This function initialises the
IOBase
field of thevgaHWRec
. This function must be called before using any other functions that access the video hardware.A macro
VGAHW_GET_IOBASE()
is also available invgaHW.h
that returns the I/O base, and this may be used when the vgahw module is not loaded (for example, in theChipProbe()
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 bysave
.flags
is set to one or more of the following flags ORed together:
VGA_SR_MODE
the mode setting registers are savedVGA_SR_FONTS
the text mode font/text data is savedVGA_SR_CMAP
the colourmap (LUT) is savedVGA_SR_ALL
all of the above are savedThe
vgaHWRec
and itsIOBase
fields must be initialised before this function is called. IfVGA_SR_FONTS
is set inflags
, the VGA memory window must be mapped. If it isn't thenvgaHWMapMem()
will be called to map it, andvgaHWUnmapMem()
will be called to unmap it afterwards.vgaHWSave()
uses the three functions below in the ordervgaHWSaveColormap()
,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 bysave
. 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 byrestore
.flags
is the same as described above for thevgaHWSave()
function.The
vgaHWRec
and itsIOBase
fields must be initialised before this function is called. IfVGA_SR_FONTS
is set inflags
, the VGA memory window must be mapped. If it isn't thenvgaHWMapMem()
will be called to map it, andvgaHWUnmapMem()
will be called to unmap it afterwards.vgaHWRestore()
uses the three functions below in the ordervgaHWRestoreFonts()
,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 byrestore
. 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
'sModeReg
field with the values appropriate for programming the given video mode. It requires that theScrnInfoRec
'sdepth
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 isFALSE
, 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 toFALSE
after programming.
Bool vgaHWSaveScreen(ScreenPtr pScreen, int mode)
This function blanks and unblanks the screen. It is blanked when
mode
isSCREEN_SAVER_ON
orSCREEN_SAVER_CYCLE
, and unblanked whenmode
isSCREEN_SAVER_OFF
orSCREEN_SAVER_FORCER
.
void vgaHWBlankScreen(ScrnInfoPtr pScrn, Bool on)
This function blanks and unblanks the screen. It is blanked when
on
isFALSE
, and unblanked whenon
isTRUE
. This function is provided for use in cases where theScrnInfoRec
can't be derived from theScreenRec
(while probing for clocks, for example).
The vgahw module uses the standard colormap support (see the Colormap Handling section. This is initialised with the following function:
Bool vgaHWHandleColormaps(ScreenPtr pScreen)
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 registerindex
.
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 registerindex
.
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 registerindex
.
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 registerindex
. When writing out the index value this function should set bit 5 (0x20
) according to the setting ofhwp->paletteEnabled
in order to preserve the palette access state. It should be cleared whenhwp->paletteEnabled
isTRUE
and set when it isFALSE
.
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 ofhwp->paletteEnabled
in order to preserve the palette access state. It should be cleared whenhwp->paletteEnabled
isTRUE
and set when it isFALSE
.
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
toTRUE
.
void disablePalette(vgaHWPtr hwp)
Set the palette address source bit in the Attribute Controller index register and set
hwp->paletteEnabled
toFALSE
.
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.)