svn merge ^/branches/released

3 files changed, 693 insertions, 77 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.
diff --git a/xorg-server/hw/xfree86/doc/man/Xorg.man.pre b/xorg-server/hw/xfree86/doc/man/Xorg.man.pre
index fe3280038..46d0e4468 100644
--- a/xorg-server/hw/xfree86/doc/man/Xorg.man.pre
+++ b/xorg-server/hw/xfree86/doc/man/Xorg.man.pre
@@ -109,7 +109,7 @@ script.
 .B __xservername__
 supports several mechanisms for supplying/obtaining configuration and
 run-time parameters: command line options, environment variables, the
-__xconfigfile__(__filemansuffix__) configuration file, auto-detection, and
+__xconfigfile__(__filemansuffix__) configuration files, auto-detection, and
 fallback defaults.  When the same information is supplied in more than
 one way, the highest precedence mechanism is used.  The list of mechanisms
 is ordered from highest precedence to lowest.  Note that not all parameters
@@ -176,6 +176,13 @@ This option will work for any file when the server is run as root (i.e,
 with real-uid 0), or for files relative to a directory in the config
 search path for all other users.
 .TP 8
+.BI \-configdir " directory"
+Read the server configuration files from
+.IR directory .
+This option will work for any directory when the server is run as root
+(i.e, with real-uid 0), or for directories relative to a directory in the
+config directory search path for all other users.
+.TP 8
 .B \-configure
 When this option is specified, the
 .B __xservername__
@@ -421,25 +428,18 @@ The
 .B __xservername__
 server is normally configured to recognize various special combinations
 of key presses that instruct the server to perform some action, rather
-than just sending the key press event to a client application.  The
-default XKEYBOARD keymap defines the key combinations listed below.
-The kbd (__drivermansuffix__) driver also has these key combinations
-builtin to its event handler
-for cases where the XKEYBOARD extension is not being used.  When using
-the XKEYBOARD extension, which key combinations perform which actions
-is completely configurable.
+than just sending the key press event to a client application. These actions
+depend on the XKB keymap loaded by a particular keyboard device and may or
+may not be available on a given configuration.
 .PP
-The special combinations of key presses recognized directly
-by
-.B __xservername__
-are:
+The following key combinations are commonly part of the default XKEYBOARD
+keymap.
 .TP 8
 .B Ctrl+Alt+Backspace
-Immediately kills the server -- no questions asked.  This is disabled by
-default.  It can be enabled with the -retro command line flag or by setting
-the
+Immediately kills the server -- no questions asked. It can be disabled by
+setting the
 .B DontZap
-__xconfigfile__(__filemansuffix__) file option to a FALSE value.
+__xconfigfile__(__filemansuffix__) file option to a TRUE value.
 .TP 8
 .B Ctrl+Alt+Keypad-Plus
 Change video mode to next one specified in the configuration file.
@@ -463,6 +463,10 @@ __xconfigfile__(__filemansuffix__) file option.
 .B __xservername__
 typically uses a configuration file called
 .B __xconfigfile__
+and configuration files with the suffix
+.I .conf
+in a directory called
+.B __xconfigdir__
 for its initial setup.
 Refer to the __xconfigfile__(__filemansuffix__) manual page for information
 about the format of this file.
@@ -471,7 +475,9 @@ about the format of this file.
 has a mechanism for automatically generating a built-in configuration
 at run-time when no
 .B __xconfigfile__
-file is present.  The current version of this automatic configuration
+file or
+.B __xconfigdir__
+files are present.  The current version of this automatic configuration
 mechanism works in two ways.
 .PP
 The first is via enhancements that have made many components of the
@@ -493,7 +499,7 @@ supported by __xservername__.  Enhancements are planned for future releases.
 .SH FILES
 The
 .B __xservername__
-server config file can be found in a range of locations.  These are
+server config files can be found in a range of locations.  These are
 documented fully in the __xconfigfile__(__filemansuffix__) manual page.  The
 most commonly used locations are shown here.
 .TP 30
@@ -512,6 +518,21 @@ Server configuration file.
 .B __projectroot__/lib/X11/__xconfigfile__
 Server configuration file.
 .TP 30
+.B /etc/X11/__xconfigdir__
+Server configuration directory.
+.TP 30
+.B /etc/X11/__xconfigdir__-4
+Server configuration directory.
+.TP 30
+.B /etc/__xconfigdir__
+Server configuration directory.
+.TP 30
+.B __projectroot__/etc/__xconfigdir__
+Server configuration directory.
+.TP 30
+.B __projectroot__/lib/X11/__xconfigdir__
+Server configuration directory.
+.TP 30
 .BI __logdir__/__xservername__. n .log
 Server log file for display
 .IR n .
diff --git a/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre b/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre
index ace041c92..5b98bda63 100644
--- a/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre
+++ b/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre
@@ -2,27 +2,35 @@
 .ds q \N'34'
 .TH __xconfigfile__ __filemansuffix__ __vendorversion__
 .SH NAME
-__xconfigfile__ \- configuration File for __xservername__ X server
+__xconfigfile__ and __xconfigdir__ \- configuration files for
+__xservername__ X server
 .SH INTRODUCTION
 .B __xservername__
 supports several mechanisms for supplying/obtaining configuration and
 run-time parameters: command line options, environment variables, the
-__xconfigfile__ configuration file, auto-detection, and fallback defaults.
-When the same information is supplied in more than one way, the highest
-precedence mechanism is used.  The list of mechanisms is ordered from
-highest precedence to lowest.  Note that not all parameters can be
-supplied via all methods.  The available command line options and
-environment variables (and some defaults) are described in the Xserver(__appmansuffix__)
-and __xservername__(__appmansuffix__) manual pages.  Most configuration file parameters, with
-their defaults, are described below.  Driver and module specific
-configuration parameters are described in the relevant driver or module
-manual page.
+__xconfigfile__ and __xconfigdir__ configuration files, auto-detection,
+and fallback defaults. When the same information is supplied in more
+than one way, the highest precedence mechanism is used. The list of
+mechanisms is ordered from highest precedence to lowest. Note that not
+all parameters can be supplied via all methods. The available command
+line options and environment variables (and some defaults) are
+described in the Xserver(__appmansuffix__) and
+__xservername__(__appmansuffix__) manual pages. Most configuration file
+parameters, with their defaults, are described below. Driver and module
+specific configuration parameters are described in the relevant driver
+or module manual page.
 .SH DESCRIPTION
 .B __xservername__
 uses a configuration file called
 .I __xconfigfile__
+and files ending in the suffix
+.I .conf
+from the directory
+.I __xconfigdir__
 for its initial setup.
-This configuration file is searched for in the following places when the
+The
+.I __xconfigfile__
+configuration file is searched for in the following places when the
 server is started as a normal user:
 .PP
 .RS 4
@@ -93,9 +101,28 @@ directory), and
 is the machine's hostname as reported by
 .BR gethostname (__libmansuffix__).
 .PP
+Additional configuration files are searched for in the following
+directories:
+.PP
+.RS 4
+.nf
+.I /etc/X11/__xconfigdir__\-4
+.I /etc/X11/__xconfigdir__
+.I /etc/__xconfigdir__
+.IR __projectroot__/etc/X11/__xconfigdir__. <hostname>
+.I __projectroot__/etc/X11/__xconfigdir__\-4
+.I __projectroot__/etc/X11/__xconfigdir__
+.IR __projectroot__/lib/X11/__xconfigdir__. <hostname>
+.I __projectroot__/lib/X11/__xconfigdir__\-4
+.I __projectroot__/lib/X11/__xconfigdir__
+.fi
+.RE
+.PP
 The
 .I __xconfigfile__
-file is composed of a number of sections which may be present in any order,
+and
+.I __xconfigdir__
+files are composed of a number of sections which may be present in any order,
 or omitted to use default configuration values.
 Each section has the form:
 .PP
@@ -117,6 +144,7 @@ The section names are:
 .BR "Module         " "Dynamic module loading"
 .BR "Extensions     " "Extension enabling"
 .BR "InputDevice    " "Input device description"
+.BR "InputClass     " "Input class description"
 .BR "Device         " "Graphics device description"
 .BR "VideoAdaptor   " "Xv video adaptor description"
 .BR "Monitor        " "Monitor description"
@@ -769,11 +797,28 @@ Example: the MIT-SHM extension can be disabled with the following entry:
 The config file may have multiple
 .B InputDevice
 sections.
-If HAL is not being used for input device configuration, there will normally
-be at least two: one for the core (primary) keyboard,
-and one of the core pointer.
+Recent X servers employ input hotplugging to add input devices, with the HAL
+backend being the default backend for X servers since 1.4. It is usually not
+necessary to provide
+.B InputDevice
+sections in the xorg.conf if hotplugging is enabled.
+.PP
+If hotplugging is disabled, there will normally
+be at least two: one for the core (primary) keyboard
+and one for the core pointer.
 If either of these two is missing, a default configuration for the missing
-ones will be used.
+ones will be used. In the absence of an explicitly specified core input
+device, the first
+.B InputDevice
+marked as
+.B CorePointer
+(or
+.BR CoreKeyboard )
+is used.
+If there is no match there, the first
+.B InputDevice
+that uses the \(lqmouse\(rq (or \(lqkbd\(rq) driver is used.
+The final fallback is to use built\-in default configurations.
 Currently the default configuration may not work as expected on all platforms.
 .PP
 .B InputDevice
@@ -828,17 +873,6 @@ and
 .BR mousedrv (__drivermansuffix__)
 on other platforms.
 .PP
-In the absence of an explicitly specified core input device, the first
-.B InputDevice
-marked as
-.B CorePointer
-(or
-.BR CoreKeyboard )
-is used.
-If there is no match there, the first
-.B InputDevice
-that uses the \(lqmouse\(rq (or \(lqkbd\(rq) driver is used.
-The final fallback is to use built\-in default configurations.
 .PP
 .B InputDevice
 sections recognise some driver\-independent
@@ -847,48 +881,135 @@ which are described here.
 See the individual input driver manual pages for a description of the
 device\-specific options.
 .TP 7
+.BI "Option \*qAutoServerLayout\*q  \*q" boolean \*q
+Always add the device to the ServerLayout section used by this instance of
+the server. This affects implied layouts as well as explicit layouts
+specified in the configuration and/or on the command line.
+.TP 7
 .BI "Option \*qCorePointer\*q"
-When this is set, the input device is installed as the core (primary)
-pointer device.
-There must be exactly one core pointer.
-If this option is not set here, or in the
-.B ServerLayout
-section, or from the
-.B \-pointer
-command line option, then the first input device that is capable of
-being used as a core pointer will be selected as the core pointer.
-This option is implicitly set when the obsolete
-.B Pointer
-section is used.
+Deprecated, use
+.B SendCoreEvents
+instead.
 .TP 7
 .BI "Option \*qCoreKeyboard\*q"
-When this is set, the input device is to be installed as the core
-(primary) keyboard device.
-There must be exactly one core keyboard.
-If this option is not set here, in the
-.B ServerLayout
-section, or from the
-.B \-keyboard
-command line option, then the first input device that is capable of
-being used as a core keyboard will be selected as the core keyboard.
-This option is implicitly set when the obsolete
-.B Keyboard
-section is used.
+Deprecated, use
+.B SendCoreEvents
+instead.
 .TP 7
 .BI "Option \*qAlwaysCore\*q  \*q" boolean \*q
+.B
+Deprecated, use
+.B SendCoreEvents
+instead.
 .TP 7
 .BI "Option \*qSendCoreEvents\*q  \*q" boolean \*q
 Both of these options are equivalent, and when enabled cause the
-input device to always report core events.
-This can be used, for example, to allow an additional pointer device to
-generate core pointer events (like moving the cursor, etc).
-.TP 4
-.BI "Option \*qHistorySize\*q  \*q" number \*q
-Sets the motion history size.
-Default: 0.
+input device to report core events through the master device. They are
+enabled by default.  Any device configured to send core events will be
+attached to the virtual core pointer or keyboard and control the cursor by
+default. Devices with
+.B SendCoreEvents
+disabled will be \*qfloating\*q and only accessible by clients employing the
+X Input extension. This option controls the startup behavior only, a device
+may be reattached or set floating at runtime.
 .TP 7
 .BI "Option \*qSendDragEvents\*q  \*q" boolean \*q
 ???
+.SH "INPUTCLASS SECTION"
+The config file may have multiple
+.B InputClass
+sections.
+These sections are optional and are used to provide configuration for a
+class of input devices as they are automatically added. An input device can
+match more than one
+.B InputClass
+section. Each class can only supplement settings from a previous class, so
+it is best to arrange the sections with the most generic matches last.
+.PP
+.B InputClass
+sections have the following format:
+.PP
+.RS 4
+.nf
+.B  "Section \*qInputClass\*q"
+.BI "    Identifier  \*q" name \*q
+.I  "    entries"
+.I  "    ..."
+.I  "    options"
+.I  "    ..."
+.B  "EndSection"
+.fi
+.RE
+.PP
+The
+.B Identifier
+entry is required in all
+.B InputClass
+sections.
+All other entries are optional.
+.PP
+The
+.B Identifier
+entry specifies the unique name for this input class.
+The
+.B Driver
+entry specifies the name of the driver to use for this input device.
+After all classes have been examined, the
+.RI \*q inputdriver \*q
+module from the final
+.B Driver
+entry will be enabled when using the loadable server.
+.PP
+When an input device is automatically added, its characteristics are
+checked against all
+.B InputClass
+sections. Each section can contain optional entries to narrow the match
+of the class. If none of the optional entries appear, the
+.B InputClass
+section is generic and will match any input device. If more than one of
+these entries appear, they all must match for the configuration to apply.
+The allowed matching entries are shown below.
+.PP
+.TP 7
+.BI "MatchProduct  \*q" matchproduct \*q
+This entry can be used to check if the substring
+.RI \*q matchproduct \*q
+occurs in the device's product name.
+.TP 7
+.BI "MatchVendor  \*q" matchvendor \*q
+This entry can be used to check if the substring
+.RI \*q matchvendor \*q
+occurs in the device's vendor name.
+.TP 7
+.BI "MatchDevicePath \*q" matchdevice \*q
+This entry can be used to check if the device file matches the
+.RI \*q matchdevice \*q
+pathname pattern.
+.TP 7
+.BI "MatchIsKeyboard     \*q" bool \*q
+.TP 7
+.BI "MatchIsPointer      \*q" bool \*q
+.TP 7
+.BI "MatchIsJoystick     \*q" bool \*q
+.TP 7
+.BI "MatchIsTablet       \*q" bool \*q
+.TP 7
+.BI "MatchIsTouchpad     \*q" bool \*q
+.TP 7
+.BI "MatchIsTouchscreen  \*q" bool \*q
+Match device types. These entries take a boolean argument similar to
+.B Option
+entries.
+.PP
+When an input device has been matched to the
+.B InputClass
+section, any
+.B Option
+entries are applied to the device. See the
+.B InputDevice
+section above for a description of the various
+.B Option
+entries.
 .SH "DEVICE SECTION"
 The config file may have multiple
 .B Device