This section describe ``helper'' functions that video driver might find useful. While video drivers are not required to use any of these to be considered ``compliant'', the use of appropriate helpers is strongly encouraged to improve the consistency of driver behaviour.
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 averb
value of zero means the message is always printed. A value higher than1
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 oftype
. The marker is used to indicate the type of message (warning, error, probed value, config value, etc). Note thexf86Verbose
value is ignored for messages of typeX_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.
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 (thename
field of theScrnInfoRec
) followed by thescrnIndex
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. IfscrnIndex
is negative, this function behaves exactly likexf86Msg()
.NOTE: This function can only be used after the
ScrnInfoRec
and itsname
field have been allocated. That means that it can not be used before the END of theChipProbe()
function. Prior to that, usexf86Msg()
, 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
andbitsPerPixel
fields of theScrnInfoRec
. 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 theChipPreInit()
function.It requires that the
confScreen
field of theScrnInfoRec
be initialised prior to calling it. This is done by the XFree86 common layer prior to callingChipPreInit()
.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 supportedSupport24bppFb
24bpp framebuffer supportedSupport32bppFb
32bpp framebuffer supportedSupportConvert24to32
Can convert 24bpp pixmap to 32bpp fbSupportConvert32to24
Can convert 32bpp pixmap to 24bpp fbForceConvert24to32
Force 24bpp pixmap to 32bpp fb conversionForceConvert32to24
Force 32bpp pixmap to 24bpp fb conversionIt 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 returnFALSE
.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 differentdepth24flags
setting.On success, the return value is
TRUE
. On failure it prints an error message and returnsFALSE
.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
andrgbBits
fields of theScrnInfoRec
. It would normally be called fairly early in theChipPreInit()
function for depths > 8bpp.It requires that the
depth
anddisplay
fields of theScrnInfoRec
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 returnFALSE
.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 theScrnInfoRec
. It would normally be called fairly early from theChipPreInit()
function.It requires that the
depth
anddisplay
fields of theScrnInfoRec
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 returnFALSE
.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 theScrnInfoRec
. It would normally be called fairly early from theChipPreInit()
function in cases where the driver supports gamma correction.It requires that the
monitor
field of theScrnInfoRec
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 returnFALSE
.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
andyDpi
fields of theScrnInfoRec
. The driver can specify preferred defaults by settingx
andy
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
andwhitePixel
fields of theScrnInfoRec
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.
The primary mode helper functions are those which would normally be used by a driver, unless it has unusual requirements which cannot be catered for the by the helpers.
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 supported 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
isNULL
, 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 rateLOOKUP_CLOSEST_CLOCK
mode with closest matching clockLOOKUP_LIST_ORDER
first usable mode in listThe following options can also be combined (OR'ed) with one of the above:
LOOKUP_CLKDIV2
Allow halved clocksLOOKUP_OPTIONAL_TOLERANCES
Allow missing horizontal sync and/or vertical refresh ranges in the XF86Config 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 notmonitor
Pointer to the applicable XF86Config monitor sectionfdFormat
Format of the screen buffervideoRam
total video memory size (in bytes)maxHValue
Maximum horizontal timing value allowedmaxVValue
Maximum vertical timing value allowedxInc
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
andvirtualY
values supplied (if greater than zero) are consistent with the line pitch andmaxHeight
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 is0
.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
, theChipPreInit()
function should returnFALSE
.
clockRanges
is a linked list of clock ranges allowed by the driver. If a mode doesn't fit in any of the definedclockRanges
, it is rejected. The firstclockRange
that matches all requirements is used.
clockRanges
contains the following fields:
minClock
maxClockThe 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 theClockMulFactor
andClockDivFactor
. 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 clocksinterlaceAllowed
TRUE
if interlacing is allowed for this rangedoubleScanAllowed
TRUE
if doublescan or multiscan is allowed for this rangeClockMulFactor
ClockDivFactorScaling 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
andClockDivFactor=2
. This means that the clock used for clock selection (ie, determining the correct clock index from the list of discrete clocks) or for theSynthClock
field in case of a programmable clock is: (mode->Clock * ClockMulFactor) / ClockDivFactor
.PrivFlags
This field is copied into the
mode->PrivFlags
field when thisclockRange
is selected byxf86ValidateModes()
. 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 anINT
).Note that the
mode->SynthClock
field is always filled in byxf86ValidateModes()
: 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 runxf86ValidateModes()
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 themodes
field of theScrnInfoRec
. TheadjustFlags
parameter determines how the vertical CRTC values are scaled for interlaced modes. They are halved if it isINTERLACE_HALVE_V
. The vertical CRTC values are doubled for doublescan modes, and are further multiplied by theVScan
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 one line for each mode being used, including its pixel clock, horizontal sync rate, refresh rate, and whether it is interlaced or multiscan.
This function is normally called after calling
xf86SetCrtcForModes()
.
The secondary mode helper functions are functions which are normally used by the primary mode helper functions, and which are not normally called directly by a driver. If a driver has unusual requirements and needs to do its own mode validation, it might be able to make use of some of these secondary mode helper functions.
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 thenumClocks
andclock
fields of theScrnInfoRec
are initialised. TheallowDiv2
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
. TheclockRanges
andstrategy
parameters are as for thexf86ValidateModes()
function above.This function requires the
modePool
,clock[]
,numClocks
andprogClock
fields of theScrnInfoRec
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
andmaxVValue
fields of theScrnInfoRec
are also used. If theValidMode
field of theScrnInfoRec
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 themodeList
. It never prints any messages, so it is up to the caller to print a message if required.
Tables associating strings and numerical tokens combined with the following functions provide a compact way of handling strings from the config file, and for converting tokens into printable strings. The table data structure is:
typedef struct { int token; const char * name; } SymTabRec, *SymTabPtr;
A table is an initialised array of SymTabRec
. The
tokens must be non-negative integers. Multiple names may be mapped
to a single token. The table is terminated with an element with a
token
value of -1
and
NULL
for the name
.
const char *xf86TokenToString(SymTabPtr table, int token)
This function returns the first string in
table
that matchestoken
. 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 matchesstring
. Thexf86NameCmp()
function is used to determine the match. If no match is found,-1
is returned.
These functions can be used to select the appropriate config file entries that match the detected hardware. They are described above in the Probe and Available Functions sections.
The xf86GetClocks()
function may be used to assist
in finding the discrete pixel clock values on older hardware.
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 then
'th clock. It should also save or restore any state affected by programming the clocks when the index passed isCLK_REG_SAVE
orCLK_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
andmaskval
are the register and bitmask to check for the presence of vertical sync pulses.knownclkindex
andknownclkvalue
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 inpScrn->numClocks
, and the probed clocks are set in thepScrn->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
FALSE
when the screen saver mode specified bymode
requires the screen be unblanked, andTRUE
otherwise. The screen saver modes that require blanking areSCREEN_SAVER_ON
andSCREEN_SAVER_CYCLE
, and the screen saver modes that require unblanking areSCREEN_SAVER_OFF
andSCREEN_SAVER_FORCER
. Drivers may call this helper from theirSaveScreen()
function to interpret the screen saver modes.