diff options
Diffstat (limited to 'xorg-server/hw/xfree86/doc/README.modes')
| -rw-r--r-- | xorg-server/hw/xfree86/doc/README.modes | 948 |
1 files changed, 474 insertions, 474 deletions
diff --git a/xorg-server/hw/xfree86/doc/README.modes b/xorg-server/hw/xfree86/doc/README.modes index 894e21313..da9d41eb5 100644 --- a/xorg-server/hw/xfree86/doc/README.modes +++ b/xorg-server/hw/xfree86/doc/README.modes @@ -1,474 +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. + 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.
|