Add hw/xfree86/docs/README.modes, documenting new mode setting APIs.
This document covers both API and xorg.conf usage of the new mode setting APIs.
This commit is contained in:
parent
558a4f5588
commit
a59c31b0f7
|
@ -0,0 +1,474 @@
|
|||
Multi-monitor Mode Setting APIs
|
||||
Keith Packard, <keithp@keithp.com
|
||||
6 March 2007
|
||||
|
||||
1. Introduction
|
||||
|
||||
This document describes a set of mode setting APIs added in X server version
|
||||
1.3 that support multiple monitors per card. These interfaces expose the
|
||||
underlying hardware CRTC and output concepts to the xf86 DDX layer so that
|
||||
the implementation of initial server setup and mode changes through
|
||||
extensions can be shared across drivers. In addition, these new interfaces
|
||||
support a new configuration mechanism as well which allows each monitor to
|
||||
be customized separately providing a consistent cross-driver configuration
|
||||
mechanism that supports the full range of output features.
|
||||
|
||||
All of the code implementing this interface can be found in hw/xfree86/modes
|
||||
in the X server sources.
|
||||
|
||||
2. Overview
|
||||
|
||||
This document describes both the driver API and the configuration data
|
||||
placed in xorg.conf; these are entirely separate as the driver has no
|
||||
interaction with the configuration information at all. Much of the structure
|
||||
here is cloned from the RandR extension version 1.2 additions which deal
|
||||
with the same kinds of information.
|
||||
|
||||
2.1 API overview
|
||||
|
||||
The mode setting API is expressed through two new driver-visible objects,
|
||||
the 'CRTC' (xf86CrtcRec) and the 'Output' (xf86OutputRec). A CRTC refers to
|
||||
hardware within the video system that can scan a subset of the framebuffer
|
||||
and generate a video signal. An Output receives that signal and transmits it
|
||||
to a monitor, projector or other device.
|
||||
|
||||
The xf86CrtcRec and xf86OutputRec contain a small amount of state data
|
||||
related to the object along with a pointer to a set of functions provided by
|
||||
the driver that manipulate the object in fairly simple ways.
|
||||
|
||||
To emulate older behaviour, one of the outputs is picked as the 'compat'
|
||||
output; this output changes over time as outputs are detected and used, the
|
||||
goal is to always have one 'special' output which is used for operations
|
||||
which need a single defined monitor (like XFree86-VidModeExtension mode
|
||||
setting, RandR 1.1 mode setting, DDC property setting, etc.).
|
||||
|
||||
2.1.1 Output overview
|
||||
|
||||
As outputs are connected to monitors, they hold a list of modes supported by
|
||||
the monitor. If the monitor and output support DDC, then the list of modes
|
||||
generally comes from the EDID data in the monitor. Otherwise, the server
|
||||
uses the standard VESA modes, pruned by monitor timing. If the configuration
|
||||
file doesn't contain monitor timing data, the server uses default timing
|
||||
information which supports 640x480, 800x600 and 1024x768 all with a 60Hz
|
||||
refresh rate.
|
||||
|
||||
As hardware often limits possible configuration combinations, each output
|
||||
knows the set of CRTCs that it can be connected to as well as the set of
|
||||
other outputs which can be simutaneously connected to a CRTC.
|
||||
|
||||
2.1.2 CRTC overview
|
||||
|
||||
CRTCs serve only to stream frame buffer data to outputs using a mode line.
|
||||
Ideally, they would not be presented to the user at all, and in fact the
|
||||
configuration file doesn't expose them. The RandR 1.2 protocol does, but the
|
||||
hope there is that client-side applications will hide them carefully away.
|
||||
|
||||
Each crtc has an associated cursor, along with the current configuration.
|
||||
All of the data needed to determine valid configurations is contained within
|
||||
the Outputs.
|
||||
|
||||
2.2 Configuration overview
|
||||
|
||||
As outputs drive monitors, the "Monitor" section has been repurposed to
|
||||
define their configuration. This provides for a bit more syntax than
|
||||
the large list of driver-specific options that were used in the past for
|
||||
similar configuration.
|
||||
|
||||
However, the existing "Monitor" section referenced by the active "Screen"
|
||||
section no longer has any use at all; some sensible meaning for this
|
||||
parameter is needed now that a Screen can have multiple Monitors.
|
||||
|
||||
3. Public Functions
|
||||
|
||||
3.1 PreInit functions
|
||||
|
||||
These functions should be used during the driver PreInit phase, they are
|
||||
arranged in the order they should be invoked.
|
||||
|
||||
void
|
||||
xf86CrtcConfigInit (ScrnInfoPtr scrn
|
||||
const xf86CrtcConfigFuncsRec *funcs)
|
||||
|
||||
This function allocates and initializes structures needed to track CRTC and
|
||||
Output state.
|
||||
|
||||
void
|
||||
xf86CrtcSetSizeRange (ScrnInfoPtr scrn,
|
||||
int minWidth, int minHeight,
|
||||
int maxWidth, int maxHeight)
|
||||
|
||||
This sets the range of screen sizes supported by the driver.
|
||||
|
||||
xf86CrtcPtr
|
||||
xf86CrtcCreate (ScrnInfoPtr scrn,
|
||||
const xf86CrtcFuncsRec *funcs)
|
||||
|
||||
Create one CRTC object. See the discussion below for a description of the
|
||||
contents of the xf86CrtcFuncsRec. Note that this is done in PreInit, so it
|
||||
should not be re-invoked at each server generation. Create one of these for
|
||||
each CRTC present in the hardware.
|
||||
|
||||
xf86OutputPtr
|
||||
xf86OutputCreate (ScrnInfoPtr scrn,
|
||||
const xf86OutputFuncsRec *funcs,
|
||||
const char *name)
|
||||
|
||||
Create one Output object. See the discussion below for a description of the
|
||||
contents of the xf86OutputFuncsRec. This is also called from PreInit and
|
||||
need not be re-invoked at each ScreenInit time. An Output should be created
|
||||
for every Output present in the hardware, not just for outputs which have
|
||||
detected monitors.
|
||||
|
||||
Bool
|
||||
xf86OutputRename (xf86OutputPtr output, const char *name)
|
||||
|
||||
If necessary, the name of an output can be changed after it is created using
|
||||
this function.
|
||||
|
||||
Bool
|
||||
xf86InitialConfiguration (ScrnInfoPtr scrn, Bool canGrow)
|
||||
|
||||
Using the resources provided, and the configuration specified by the user,
|
||||
this function computes an initial configuration for the server. It tries to
|
||||
enable as much hardware as possible using some fairly simple heuristics.
|
||||
|
||||
The 'canGrow' parameter indicates that the frame buffer does not have a fixed
|
||||
size (fixed size frame buffers are required by XAA). When the frame buffer
|
||||
has a fixed size, the configuration selects a 'reasonablely large' frame
|
||||
buffer so that common reconfiguration options are possible. For resizable
|
||||
frame buffers, the frame buffer is set to the smallest size that encloses
|
||||
the desired configuration.
|
||||
|
||||
3.2 ScreenInit functions
|
||||
|
||||
These functions should be used during the driver ScreenInit phase.
|
||||
|
||||
Bool
|
||||
xf86DiDGAInit (ScreenPtr screen, unsigned long dga_address)
|
||||
|
||||
This function provides driver-independent accelerated DGA support for some
|
||||
of the DGA operations; using this, the driver can avoid needing to implement
|
||||
any of the rest of DGA.
|
||||
|
||||
Bool
|
||||
xf86SaveScreen(ScreenPtr pScreen, int mode)
|
||||
|
||||
Stick this in pScreen->SaveScreen and the core X screen saver will be
|
||||
implemented by disabling outputs and crtcs using their dpms functions.
|
||||
|
||||
void
|
||||
xf86DPMSSet(ScrnInfoPtr scrn, int mode, int flags)
|
||||
|
||||
Pass this function to xf86DPMSInit and all DPMS mode switching will be
|
||||
managed by using the dpms functions provided by the Outputs and CRTCs.
|
||||
|
||||
Bool
|
||||
xf86CrtcScreenInit (ScreenPtr screen)
|
||||
|
||||
This function completes the screen initialization process for the crtc and
|
||||
output objects. Call it near the end of the ScreenInit function, after the
|
||||
frame buffer and acceleration layers have been added.
|
||||
|
||||
3.3 EnterVT functions
|
||||
|
||||
Functions used during EnterVT, or whenever the current configuration needs
|
||||
to be applied to the hardware.
|
||||
|
||||
Bool
|
||||
xf86SetDesiredModes (ScrnInfoPtr scrn)
|
||||
|
||||
xf86InitialConfiguration selects the desired configuration at PreInit time;
|
||||
when the server finally hits ScreenInit, xf86SetDesiredModes is used by the
|
||||
driver to take that configuration and apply it to the hardware. In addition,
|
||||
successful mode selection at other times updates the configuration that will
|
||||
be used by this function, so LeaveVT/EnterVT pairs can simply invoke this
|
||||
and return to the previous configuration.
|
||||
|
||||
3.4 SwitchMode functions
|
||||
|
||||
Functions called from the pScrn->SwitchMode hook, which is used by the
|
||||
XFree86-VidModeExtension and the keypad mode switch commands.
|
||||
|
||||
Bool
|
||||
xf86SetSingleMode (ScrnInfoPtr scrn,
|
||||
DisplayModePtr desired,
|
||||
Rotation rotation)
|
||||
|
||||
This function applies the specified mode to all active outputs. Which is to
|
||||
say, it picks reasonable modes for all active outputs, attempting to get the
|
||||
screen to the specified size while not breaking anything that is currently
|
||||
working.
|
||||
|
||||
3.7 get_modes functions
|
||||
|
||||
Functions called during output->get_modes to help build lists of modes
|
||||
|
||||
xf86MonPtr
|
||||
xf86OutputGetEDID (xf86OutputPtr output, I2CBusPtr pDDCBus)
|
||||
|
||||
This returns the EDID data structure for the 'output' using the I2C bus
|
||||
'pDDCBus'. This has no effect on 'output' itself.
|
||||
|
||||
void
|
||||
xf86OutputSetEDID (xf86OutputPtr output, xf86MonPtr edid_mon)
|
||||
|
||||
Once the EDID data has been fetched, this call applies the EDID data to the
|
||||
output object, setting the physical size and also various properties, like
|
||||
the DDC root window property (when output is the 'compat' output), and the
|
||||
RandR 1.2 EDID output properties.
|
||||
|
||||
DisplayModePtr
|
||||
xf86OutputGetEDIDModes (xf86OutputPtr output)
|
||||
|
||||
Given an EDID data structure, this function computes a list of suitable
|
||||
modes. This function also applies a sequence of 'quirks' during this process
|
||||
so that the returned modes may not actually match the mode data present in
|
||||
the EDID data.
|
||||
|
||||
3.6 Other functions
|
||||
|
||||
These remaining functions in the API can be used by the driver as needed.
|
||||
|
||||
Bool
|
||||
xf86CrtcSetMode (xf86CrtcPtr crtc, DisplayModePtr mode, Rotation rotation,
|
||||
int x, int y)
|
||||
|
||||
Applies a mode to a CRTC. All of the outputs which are currently using the
|
||||
specified CRTC are included in the mode setting process. 'x' and 'y' are the
|
||||
offset within the frame buffer that the crtc is placed at. No checking is
|
||||
done in this function to ensure that the mode is usable by the active
|
||||
outputs.
|
||||
|
||||
void
|
||||
xf86ProbeOutputModes (ScrnInfoPtr pScrn, int maxX, int maxY)
|
||||
|
||||
This discards the mode lists for all outputs, re-detects monitor presence
|
||||
and then acquires new mode lists for all monitors which are not disconnected.
|
||||
Monitor configuration data is used to modify the mode lists returned by the
|
||||
outputs. 'maxX' and 'maxY' limit the maximum size modes that will be
|
||||
returned.
|
||||
|
||||
void
|
||||
xf86SetScrnInfoModes (ScrnInfoPtr pScrn)
|
||||
|
||||
This copies the 'compat' output mode list into the pScrn modes list which is
|
||||
used by the XFree86-VidModeExtension and the keypad mode switching
|
||||
operations. The current 'desired' mode for the CRTC associated with the
|
||||
'compat' output is placed first in this list to indicate the current mode.
|
||||
Usually, the driver won't need to call this function as
|
||||
xf86InitialConfiguration will do so automatically, as well as any RandR
|
||||
functions which reprobe for modes. However, if the driver reprobes for modes
|
||||
at other times using xf86ProbeOutputModes, this function needs to be called.
|
||||
|
||||
Bool
|
||||
xf86DiDGAReInit (ScreenPtr pScreen)
|
||||
|
||||
This is similar to xf86SetScrnInfoModes, but it applies the 'compat' output
|
||||
mode list to the set of modes advertised by the DGA extension; it needs to
|
||||
be called whenever xf86ProbeOutputModes is invoked.
|
||||
|
||||
void
|
||||
xf86DisableUnusedFunctions(ScrnInfoPtr pScrn)
|
||||
|
||||
After any sequence of calls using xf86CrtcSetMode, this function cleans up
|
||||
any leftover Output and CRTC objects by disabling them, saving power. It is
|
||||
safe to call this whenever the server is running as it only disables objects
|
||||
which are not currently in use.
|
||||
|
||||
4. CRTC operations
|
||||
|
||||
4.1 CRTC functions
|
||||
|
||||
These functions provide an abstract interface for the CRTC object; most
|
||||
manipulation of the CRTC object is done through these functions.
|
||||
|
||||
void
|
||||
crtc->funcs->dpms (xf86CrtcPtr crtc, int mode)
|
||||
|
||||
Where 'mode' is one of DPMSModeOff, DPMSModeSuspend, DPMSModeStandby or
|
||||
DPMSModeOn. This requests that the crtc go to the specified power state.
|
||||
When changing power states, the output dpms functions are invoked before the
|
||||
crtc dpms functions.
|
||||
|
||||
void
|
||||
crtc->funcs->save (xf86CrtcPtr crtc)
|
||||
|
||||
void
|
||||
crtc->funcs->restore (xf86CrtcPtr crtc)
|
||||
|
||||
Preserve/restore any register contents related to the CRTC. These are
|
||||
strictly a convenience for the driver writer; if the existing driver has
|
||||
fully operation save/restore functions, you need not place any additional
|
||||
code here. In particular, the server itself never uses this function.
|
||||
|
||||
Bool
|
||||
crtc->funcs->lock (xf86CrtcPtr crtc)
|
||||
|
||||
void
|
||||
crtc->funcs->unlock (xf86CrtcPtr crtc)
|
||||
|
||||
These functions are invoked around mode setting operations; the intent is
|
||||
that DRI locking be done here to prevent DRI applications from manipulating
|
||||
the hardware while the server is busy changing the output configuration. If
|
||||
the lock function returns FALSE, the unlock function will not be invoked.
|
||||
|
||||
Bool
|
||||
crtc->funcs->mode_fixup (xf86CrtcPtr crtc,
|
||||
DisplayModePtr mode,
|
||||
DisplayModePtr adjusted_mode)
|
||||
|
||||
This call gives the CRTC a chance to see what mode will be set and to
|
||||
comment on the mode by changing 'adjusted_mode' as needed. This function
|
||||
shall not modify the state of the crtc hardware at all. If the CRTC cannot
|
||||
accept this mode, this function may return FALSE.
|
||||
|
||||
void
|
||||
crtc->funcs->prepare (xf86CrtcPtr crtc)
|
||||
|
||||
This call is made just before the mode is set to make the hardware ready for
|
||||
the operation. A usual function to perform here is to disable the crtc so
|
||||
that mode setting can occur with clocks turned off and outputs deactivated.
|
||||
|
||||
void
|
||||
crtc->funcs->mode_set (xf86CrtcPtr crtc,
|
||||
DisplayModePtr mode,
|
||||
DisplayModePtr adjusted_mode)
|
||||
|
||||
This function applies the specified mode (possibly adjusted by the CRTC
|
||||
and/or Outputs).
|
||||
|
||||
void
|
||||
crtc->funcs->commit (xf86CrtcPtr crtc)
|
||||
|
||||
Once the mode has been applied to the CRTC and Outputs, this function is
|
||||
invoked to let the hardware turn things back on.
|
||||
|
||||
void
|
||||
crtc->funcs->gamma_set (xf86CrtcPtr crtc, CARD16 *red,
|
||||
CARD16 *green, CARD16 *blue, int size)
|
||||
|
||||
This function adjusts the gamma ramps for the specified crtc.
|
||||
|
||||
void *
|
||||
crtc->funcs->shadow_allocate (xf86CrtcPtr crtc, int width, int height)
|
||||
|
||||
This function allocates frame buffer space for a shadow frame buffer. When
|
||||
allocated, the crtc must scan from the shadow instead of the main frame
|
||||
buffer. This is used for rotation. The address returned is passed to the
|
||||
shadow_create function. This function should return NULL on failure.
|
||||
|
||||
PixmapPtr
|
||||
crtc->funcs->shadow_create (xf86CrtcPtr crtc, void *data,
|
||||
int width, int height)
|
||||
|
||||
This function creates a pixmap object that will be used as a shadow of the
|
||||
main frame buffer for CRTCs which are rotated or reflected. 'data' is the
|
||||
value returned by shadow_allocate.
|
||||
|
||||
void
|
||||
crtc->funcs->shadow_destroy (xf86CrtcPtr crtc, PixmapPtr pPixmap,
|
||||
void *data)
|
||||
|
||||
Destroys any associated shadow objects. If pPixmap is NULL, then a pixmap
|
||||
was not created, but 'data' may still be non-NULL indicating that the shadow
|
||||
had been allocated.
|
||||
|
||||
void
|
||||
crtc->funcs->destroy (xf86CrtcPtr crtc)
|
||||
|
||||
When a CRTC is destroyed (which only happens in error cases), this function
|
||||
can clean up any driver-specific data.
|
||||
|
||||
4.2 CRTC fields
|
||||
|
||||
The CRTC object is not opaque; there are several fields of interest to the
|
||||
driver writer.
|
||||
|
||||
struct _xf86Crtc {
|
||||
/**
|
||||
* Associated ScrnInfo
|
||||
*/
|
||||
ScrnInfoPtr scrn;
|
||||
|
||||
/**
|
||||
* Active state of this CRTC
|
||||
*
|
||||
* Set when this CRTC is driving one or more outputs
|
||||
*/
|
||||
Bool enabled;
|
||||
|
||||
/** Track whether cursor is within CRTC range */
|
||||
Bool cursorInRange;
|
||||
|
||||
/** Track state of cursor associated with this CRTC */
|
||||
Bool cursorShown;
|
||||
|
||||
/**
|
||||
* Active mode
|
||||
*
|
||||
* This reflects the mode as set in the CRTC currently
|
||||
* It will be cleared when the VT is not active or
|
||||
* during server startup
|
||||
*/
|
||||
DisplayModeRec mode;
|
||||
Rotation rotation;
|
||||
PixmapPtr rotatedPixmap;
|
||||
void *rotatedData;
|
||||
|
||||
/**
|
||||
* Position on screen
|
||||
*
|
||||
* Locates this CRTC within the frame buffer
|
||||
*/
|
||||
int x, y;
|
||||
|
||||
/**
|
||||
* Desired mode
|
||||
*
|
||||
* This is set to the requested mode, independent of
|
||||
* whether the VT is active. In particular, it receives
|
||||
* the startup configured mode and saves the active mode
|
||||
* on VT switch.
|
||||
*/
|
||||
DisplayModeRec desiredMode;
|
||||
Rotation desiredRotation;
|
||||
int desiredX, desiredY;
|
||||
|
||||
/** crtc-specific functions */
|
||||
const xf86CrtcFuncsRec *funcs;
|
||||
|
||||
/**
|
||||
* Driver private
|
||||
*
|
||||
* Holds driver-private information
|
||||
*/
|
||||
void *driver_private;
|
||||
#ifdef RANDR_12_INTERFACE
|
||||
/**
|
||||
* RandR crtc
|
||||
*
|
||||
* When RandR 1.2 is available, this
|
||||
* points at the associated crtc object
|
||||
*/
|
||||
RRCrtcPtr randr_crtc;
|
||||
#else
|
||||
void *randr_crtc;
|
||||
#endif
|
||||
};
|
||||
|
||||
|
||||
5. Output functions.
|
||||
|
||||
6. Configuration
|
||||
|
||||
Because the configuration file syntax is fixed,
|
||||
this was done by creating new "Driver" section options that hook specific
|
||||
outputs to specific "Monitor" sections in the file. The option:
|
||||
section of the form:
|
||||
|
||||
Option "monitor-VGA" "My VGA Monitor"
|
||||
|
||||
connects the VGA output of this driver to the "Monitor" section with
|
||||
Identifier "My VGA Monitor". All of the usual monitor options can now be
|
||||
placed in that "Monitor" section and will be applied to the VGA output
|
||||
configuration.
|
Loading…
Reference in New Issue