xfree86/doc/README.modes

		    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.