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