aboutsummaryrefslogtreecommitdiff
path: root/xorg-server/hw/xfree86/doc
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2009-06-28 22:07:26 +0000
committermarha <marha@users.sourceforge.net>2009-06-28 22:07:26 +0000
commit3562e78743202e43aec8727005182a2558117eca (patch)
tree8f9113a77d12470c5c851a2a8e4cb02e89df7d43 /xorg-server/hw/xfree86/doc
downloadvcxsrv-3562e78743202e43aec8727005182a2558117eca.tar.gz
vcxsrv-3562e78743202e43aec8727005182a2558117eca.tar.bz2
vcxsrv-3562e78743202e43aec8727005182a2558117eca.zip
Checked in the following released items:
xkeyboard-config-1.4.tar.gz ttf-bitstream-vera-1.10.tar.gz font-alias-1.0.1.tar.gz font-sun-misc-1.0.0.tar.gz font-sun-misc-1.0.0.tar.gz font-sony-misc-1.0.0.tar.gz font-schumacher-misc-1.0.0.tar.gz font-mutt-misc-1.0.0.tar.gz font-misc-misc-1.0.0.tar.gz font-misc-meltho-1.0.0.tar.gz font-micro-misc-1.0.0.tar.gz font-jis-misc-1.0.0.tar.gz font-isas-misc-1.0.0.tar.gz font-dec-misc-1.0.0.tar.gz font-daewoo-misc-1.0.0.tar.gz font-cursor-misc-1.0.0.tar.gz font-arabic-misc-1.0.0.tar.gz font-winitzki-cyrillic-1.0.0.tar.gz font-misc-cyrillic-1.0.0.tar.gz font-cronyx-cyrillic-1.0.0.tar.gz font-screen-cyrillic-1.0.1.tar.gz font-xfree86-type1-1.0.1.tar.gz font-adobe-utopia-type1-1.0.1.tar.gz font-ibm-type1-1.0.0.tar.gz font-bitstream-type1-1.0.0.tar.gz font-bitstream-speedo-1.0.0.tar.gz font-bh-ttf-1.0.0.tar.gz font-bh-type1-1.0.0.tar.gz font-bitstream-100dpi-1.0.0.tar.gz font-bh-lucidatypewriter-100dpi-1.0.0.tar.gz font-bh-100dpi-1.0.0.tar.gz font-adobe-utopia-100dpi-1.0.1.tar.gz font-adobe-100dpi-1.0.0.tar.gz font-util-1.0.1.tar.gz font-bitstream-75dpi-1.0.0.tar.gz font-bh-lucidatypewriter-75dpi-1.0.0.tar.gz font-adobe-utopia-75dpi-1.0.1.tar.gz font-bh-75dpi-1.0.0.tar.gz bdftopcf-1.0.1.tar.gz font-adobe-75dpi-1.0.0.tar.gz mkfontscale-1.0.6.tar.gz openssl-0.9.8k.tar.gz bigreqsproto-1.0.2.tar.gz xtrans-1.2.2.tar.gz resourceproto-1.0.2.tar.gz inputproto-1.4.4.tar.gz compositeproto-0.4.tar.gz damageproto-1.1.0.tar.gz zlib-1.2.3.tar.gz xkbcomp-1.0.5.tar.gz freetype-2.3.9.tar.gz pthreads-w32-2-8-0-release.tar.gz pixman-0.12.0.tar.gz kbproto-1.0.3.tar.gz evieext-1.0.2.tar.gz fixesproto-4.0.tar.gz recordproto-1.13.2.tar.gz randrproto-1.2.2.tar.gz scrnsaverproto-1.1.0.tar.gz renderproto-0.9.3.tar.gz xcmiscproto-1.1.2.tar.gz fontsproto-2.0.2.tar.gz xextproto-7.0.3.tar.gz xproto-7.0.14.tar.gz libXdmcp-1.0.2.tar.gz libxkbfile-1.0.5.tar.gz libfontenc-1.0.4.tar.gz libXfont-1.3.4.tar.gz libX11-1.1.5.tar.gz libXau-1.0.4.tar.gz libxcb-1.1.tar.gz xorg-server-1.5.3.tar.gz
Diffstat (limited to 'xorg-server/hw/xfree86/doc')
-rw-r--r--xorg-server/hw/xfree86/doc/Makefile.am10
-rw-r--r--xorg-server/hw/xfree86/doc/Makefile.in696
-rw-r--r--xorg-server/hw/xfree86/doc/README.DRI1256
-rw-r--r--xorg-server/hw/xfree86/doc/README.fonts1158
-rw-r--r--xorg-server/hw/xfree86/doc/README.rapidaccess48
-rw-r--r--xorg-server/hw/xfree86/doc/devel/DebuggingHints192
-rw-r--r--xorg-server/hw/xfree86/doc/devel/Domain.note159
-rw-r--r--xorg-server/hw/xfree86/doc/devel/Makefile.am10
-rw-r--r--xorg-server/hw/xfree86/doc/devel/Makefile.in542
-rw-r--r--xorg-server/hw/xfree86/doc/devel/RAC.Notes696
-rw-r--r--xorg-server/hw/xfree86/doc/devel/README.DRIcomp556
-rw-r--r--xorg-server/hw/xfree86/doc/devel/Registry409
-rw-r--r--xorg-server/hw/xfree86/doc/devel/exa-driver.txt94
-rw-r--r--xorg-server/hw/xfree86/doc/man/Makefile.am24
-rw-r--r--xorg-server/hw/xfree86/doc/man/Makefile.in646
-rw-r--r--xorg-server/hw/xfree86/doc/man/Xorg.man.pre693
-rw-r--r--xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre2223
-rw-r--r--xorg-server/hw/xfree86/doc/sgml/DESIGN.sgml7414
-rw-r--r--xorg-server/hw/xfree86/doc/sgml/Makefile.am54
-rw-r--r--xorg-server/hw/xfree86/doc/sgml/Makefile.in581
20 files changed, 17461 insertions, 0 deletions
diff --git a/xorg-server/hw/xfree86/doc/Makefile.am b/xorg-server/hw/xfree86/doc/Makefile.am
new file mode 100644
index 000000000..6d8f4d213
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/Makefile.am
@@ -0,0 +1,10 @@
+if BUILDDOCS
+SUBDIRS = devel man sgml
+else
+SUBDIRS = man
+endif
+
+EXTRA_DIST = \
+ README.DRI \
+ README.fonts \
+ README.rapidaccess
diff --git a/xorg-server/hw/xfree86/doc/Makefile.in b/xorg-server/hw/xfree86/doc/Makefile.in
new file mode 100644
index 000000000..434646e22
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/Makefile.in
@@ -0,0 +1,696 @@
+# Makefile.in generated by automake 1.10.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+VPATH = @srcdir@
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = hw/xfree86/doc
+DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \
+ $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+ $(ACLOCAL_M4)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/include/do-not-use-config.h \
+ $(top_builddir)/include/xorg-server.h \
+ $(top_builddir)/include/dix-config.h \
+ $(top_builddir)/include/xgl-config.h \
+ $(top_builddir)/include/xorg-config.h \
+ $(top_builddir)/include/xkb-config.h \
+ $(top_builddir)/include/xwin-config.h \
+ $(top_builddir)/include/kdrive-config.h
+CONFIG_CLEAN_FILES =
+SOURCES =
+DIST_SOURCES =
+RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \
+ html-recursive info-recursive install-data-recursive \
+ install-dvi-recursive install-exec-recursive \
+ install-html-recursive install-info-recursive \
+ install-pdf-recursive install-ps-recursive install-recursive \
+ installcheck-recursive installdirs-recursive pdf-recursive \
+ ps-recursive uninstall-recursive
+RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \
+ distclean-recursive maintainer-clean-recursive
+ETAGS = etags
+CTAGS = ctags
+DIST_SUBDIRS = man devel sgml
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+ACLOCAL = @ACLOCAL@
+ADMIN_MAN_DIR = @ADMIN_MAN_DIR@
+ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@
+ALLOCA = @ALLOCA@
+AMTAR = @AMTAR@
+APPDEFAULTDIR = @APPDEFAULTDIR@
+APPLE_APPLICATIONS_DIR = @APPLE_APPLICATIONS_DIR@
+APP_MAN_DIR = @APP_MAN_DIR@
+APP_MAN_SUFFIX = @APP_MAN_SUFFIX@
+AR = @AR@
+AS = @AS@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BASE_FONT_PATH = @BASE_FONT_PATH@
+BUILD_DATE = @BUILD_DATE@
+BUILD_TIME = @BUILD_TIME@
+CC = @CC@
+CCAS = @CCAS@
+CCASDEPMODE = @CCASDEPMODE@
+CCASFLAGS = @CCASFLAGS@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+COMPILEDDEFAULTFONTPATH = @COMPILEDDEFAULTFONTPATH@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CXX = @CXX@
+CXXCPP = @CXXCPP@
+CXXDEPMODE = @CXXDEPMODE@
+CXXFLAGS = @CXXFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DARWIN_LIBS = @DARWIN_LIBS@
+DBUS_CFLAGS = @DBUS_CFLAGS@
+DBUS_LIBS = @DBUS_LIBS@
+DEFAULT_LIBRARY_PATH = @DEFAULT_LIBRARY_PATH@
+DEFAULT_LOGPREFIX = @DEFAULT_LOGPREFIX@
+DEFAULT_MODULE_PATH = @DEFAULT_MODULE_PATH@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DGA_CFLAGS = @DGA_CFLAGS@
+DGA_LIBS = @DGA_LIBS@
+DIX_CFLAGS = @DIX_CFLAGS@
+DLLTOOL = @DLLTOOL@
+DMXEXAMPLES_DEP_CFLAGS = @DMXEXAMPLES_DEP_CFLAGS@
+DMXEXAMPLES_DEP_LIBS = @DMXEXAMPLES_DEP_LIBS@
+DMXMODULES_CFLAGS = @DMXMODULES_CFLAGS@
+DMXMODULES_LIBS = @DMXMODULES_LIBS@
+DMXXIEXAMPLES_DEP_CFLAGS = @DMXXIEXAMPLES_DEP_CFLAGS@
+DMXXIEXAMPLES_DEP_LIBS = @DMXXIEXAMPLES_DEP_LIBS@
+DMXXMUEXAMPLES_DEP_CFLAGS = @DMXXMUEXAMPLES_DEP_CFLAGS@
+DMXXMUEXAMPLES_DEP_LIBS = @DMXXMUEXAMPLES_DEP_LIBS@
+DRI2PROTO_CFLAGS = @DRI2PROTO_CFLAGS@
+DRI2PROTO_LIBS = @DRI2PROTO_LIBS@
+DRIPROTO_CFLAGS = @DRIPROTO_CFLAGS@
+DRIPROTO_LIBS = @DRIPROTO_LIBS@
+DRIVER_MAN_DIR = @DRIVER_MAN_DIR@
+DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@
+DRI_DRIVER_PATH = @DRI_DRIVER_PATH@
+DSYMUTIL = @DSYMUTIL@
+DTRACE = @DTRACE@
+ECHO = @ECHO@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+EXEEXT = @EXEEXT@
+F77 = @F77@
+FFLAGS = @FFLAGS@
+FILE_MAN_DIR = @FILE_MAN_DIR@
+FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@
+FREETYPE_CFLAGS = @FREETYPE_CFLAGS@
+FREETYPE_LIBS = @FREETYPE_LIBS@
+GLX_ARCH_DEFINES = @GLX_ARCH_DEFINES@
+GLX_DEFINES = @GLX_DEFINES@
+GL_CFLAGS = @GL_CFLAGS@
+GL_LIBS = @GL_LIBS@
+GREP = @GREP@
+HAL_CFLAGS = @HAL_CFLAGS@
+HAL_LIBS = @HAL_LIBS@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+KDRIVE_CFLAGS = @KDRIVE_CFLAGS@
+KDRIVE_INCS = @KDRIVE_INCS@
+KDRIVE_LIBS = @KDRIVE_LIBS@
+KDRIVE_LOCAL_LIBS = @KDRIVE_LOCAL_LIBS@
+KDRIVE_PURE_INCS = @KDRIVE_PURE_INCS@
+KDRIVE_PURE_LIBS = @KDRIVE_PURE_LIBS@
+LAUNCHD = @LAUNCHD@
+LDFLAGS = @LDFLAGS@
+LD_EXPORT_SYMBOLS_FLAG = @LD_EXPORT_SYMBOLS_FLAG@
+LEX = @LEX@
+LEXLIB = @LEXLIB@
+LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@
+LIBDRM_CFLAGS = @LIBDRM_CFLAGS@
+LIBDRM_LIBS = @LIBDRM_LIBS@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIB_MAN_DIR = @LIB_MAN_DIR@
+LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@
+LINUXDOC = @LINUXDOC@
+LN_S = @LN_S@
+LTLIBOBJS = @LTLIBOBJS@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+MAKE_HTML = @MAKE_HTML@
+MAKE_PDF = @MAKE_PDF@
+MAKE_PS = @MAKE_PS@
+MAKE_TEXT = @MAKE_TEXT@
+MESA_SOURCE = @MESA_SOURCE@
+MISC_MAN_DIR = @MISC_MAN_DIR@
+MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@
+MKDIR_P = @MKDIR_P@
+MKFONTDIR = @MKFONTDIR@
+MKFONTSCALE = @MKFONTSCALE@
+NMEDIT = @NMEDIT@
+OBJC = @OBJC@
+OBJCCLD = @OBJCCLD@
+OBJCDEPMODE = @OBJCDEPMODE@
+OBJCFLAGS = @OBJCFLAGS@
+OBJCLINK = @OBJCLINK@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OPENSSL_CFLAGS = @OPENSSL_CFLAGS@
+OPENSSL_LIBS = @OPENSSL_LIBS@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PCIACCESS_CFLAGS = @PCIACCESS_CFLAGS@
+PCIACCESS_LIBS = @PCIACCESS_LIBS@
+PCI_TXT_IDS_PATH = @PCI_TXT_IDS_PATH@
+PERL = @PERL@
+PKG_CONFIG = @PKG_CONFIG@
+PROJECTROOT = @PROJECTROOT@
+PS2PDF = @PS2PDF@
+RANLIB = @RANLIB@
+RAWCPP = @RAWCPP@
+RAWCPPFLAGS = @RAWCPPFLAGS@
+SED = @SED@
+SERVER_MISC_CONFIG_PATH = @SERVER_MISC_CONFIG_PATH@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+SOLARIS_ASM_CFLAGS = @SOLARIS_ASM_CFLAGS@
+SOLARIS_INOUT_ARCH = @SOLARIS_INOUT_ARCH@
+STRIP = @STRIP@
+TSLIB_CFLAGS = @TSLIB_CFLAGS@
+TSLIB_LIBS = @TSLIB_LIBS@
+UTILS_SYS_LIBS = @UTILS_SYS_LIBS@
+VENDOR_MAN_VERSION = @VENDOR_MAN_VERSION@
+VENDOR_NAME = @VENDOR_NAME@
+VENDOR_NAME_SHORT = @VENDOR_NAME_SHORT@
+VENDOR_RELEASE = @VENDOR_RELEASE@
+VERSION = @VERSION@
+X11APP_ARCHS = @X11APP_ARCHS@
+X11EXAMPLES_DEP_CFLAGS = @X11EXAMPLES_DEP_CFLAGS@
+X11EXAMPLES_DEP_LIBS = @X11EXAMPLES_DEP_LIBS@
+XDMCP_CFLAGS = @XDMCP_CFLAGS@
+XDMCP_LIBS = @XDMCP_LIBS@
+XDMXCONFIG_DEP_CFLAGS = @XDMXCONFIG_DEP_CFLAGS@
+XDMXCONFIG_DEP_LIBS = @XDMXCONFIG_DEP_LIBS@
+XDMX_CFLAGS = @XDMX_CFLAGS@
+XDMX_LIBS = @XDMX_LIBS@
+XDMX_SYS_LIBS = @XDMX_SYS_LIBS@
+XEGLMODULES_CFLAGS = @XEGLMODULES_CFLAGS@
+XEGL_LIBS = @XEGL_LIBS@
+XEGL_SYS_LIBS = @XEGL_SYS_LIBS@
+XEPHYR_CFLAGS = @XEPHYR_CFLAGS@
+XEPHYR_DRI_LIBS = @XEPHYR_DRI_LIBS@
+XEPHYR_INCS = @XEPHYR_INCS@
+XEPHYR_LIBS = @XEPHYR_LIBS@
+XF86CONFIGFILE = @XF86CONFIGFILE@
+XF86MISC_CFLAGS = @XF86MISC_CFLAGS@
+XF86MISC_LIBS = @XF86MISC_LIBS@
+XF86VIDMODE_CFLAGS = @XF86VIDMODE_CFLAGS@
+XF86VIDMODE_LIBS = @XF86VIDMODE_LIBS@
+XGLMODULES_CFLAGS = @XGLMODULES_CFLAGS@
+XGLMODULES_LIBS = @XGLMODULES_LIBS@
+XGLXMODULES_CFLAGS = @XGLXMODULES_CFLAGS@
+XGLXMODULES_LIBS = @XGLXMODULES_LIBS@
+XGLX_LIBS = @XGLX_LIBS@
+XGLX_SYS_LIBS = @XGLX_SYS_LIBS@
+XGL_LIBS = @XGL_LIBS@
+XGL_MODULE_PATH = @XGL_MODULE_PATH@
+XGL_SYS_LIBS = @XGL_SYS_LIBS@
+XKB_BASE_DIRECTORY = @XKB_BASE_DIRECTORY@
+XKB_BIN_DIRECTORY = @XKB_BIN_DIRECTORY@
+XKB_COMPILED_DIR = @XKB_COMPILED_DIR@
+XKM_OUTPUT_DIR = @XKM_OUTPUT_DIR@
+XLIB_CFLAGS = @XLIB_CFLAGS@
+XLIB_LIBS = @XLIB_LIBS@
+XNESTMODULES_CFLAGS = @XNESTMODULES_CFLAGS@
+XNESTMODULES_LIBS = @XNESTMODULES_LIBS@
+XNEST_LIBS = @XNEST_LIBS@
+XNEST_SYS_LIBS = @XNEST_SYS_LIBS@
+XORGCFG_DEP_CFLAGS = @XORGCFG_DEP_CFLAGS@
+XORGCFG_DEP_LIBS = @XORGCFG_DEP_LIBS@
+XORGCONFIG_DEP_CFLAGS = @XORGCONFIG_DEP_CFLAGS@
+XORGCONFIG_DEP_LIBS = @XORGCONFIG_DEP_LIBS@
+XORG_CFLAGS = @XORG_CFLAGS@
+XORG_INCS = @XORG_INCS@
+XORG_LIBS = @XORG_LIBS@
+XORG_MODULES_CFLAGS = @XORG_MODULES_CFLAGS@
+XORG_MODULES_LIBS = @XORG_MODULES_LIBS@
+XORG_OS = @XORG_OS@
+XORG_OS_SUBDIR = @XORG_OS_SUBDIR@
+XORG_SYS_LIBS = @XORG_SYS_LIBS@
+XPRINTMODULES_CFLAGS = @XPRINTMODULES_CFLAGS@
+XPRINTMODULES_LIBS = @XPRINTMODULES_LIBS@
+XPRINTPROTO_CFLAGS = @XPRINTPROTO_CFLAGS@
+XPRINTPROTO_LIBS = @XPRINTPROTO_LIBS@
+XPRINT_CFLAGS = @XPRINT_CFLAGS@
+XPRINT_LIBS = @XPRINT_LIBS@
+XPRINT_SYS_LIBS = @XPRINT_SYS_LIBS@
+XRESEXAMPLES_DEP_CFLAGS = @XRESEXAMPLES_DEP_CFLAGS@
+XRESEXAMPLES_DEP_LIBS = @XRESEXAMPLES_DEP_LIBS@
+XSDL_INCS = @XSDL_INCS@
+XSDL_LIBS = @XSDL_LIBS@
+XSERVERCFLAGS_CFLAGS = @XSERVERCFLAGS_CFLAGS@
+XSERVERCFLAGS_LIBS = @XSERVERCFLAGS_LIBS@
+XSERVERLIBS_CFLAGS = @XSERVERLIBS_CFLAGS@
+XSERVERLIBS_LIBS = @XSERVERLIBS_LIBS@
+XSERVER_LIBS = @XSERVER_LIBS@
+XSERVER_SYS_LIBS = @XSERVER_SYS_LIBS@
+XTSTEXAMPLES_DEP_CFLAGS = @XTSTEXAMPLES_DEP_CFLAGS@
+XTSTEXAMPLES_DEP_LIBS = @XTSTEXAMPLES_DEP_LIBS@
+XVFB_LIBS = @XVFB_LIBS@
+XVFB_SYS_LIBS = @XVFB_SYS_LIBS@
+XWINMODULES_CFLAGS = @XWINMODULES_CFLAGS@
+XWINMODULES_LIBS = @XWINMODULES_LIBS@
+XWIN_LIBS = @XWIN_LIBS@
+XWIN_SERVER_NAME = @XWIN_SERVER_NAME@
+XWIN_SYS_LIBS = @XWIN_SYS_LIBS@
+YACC = @YACC@
+YFLAGS = @YFLAGS@
+__XCONFIGFILE__ = @__XCONFIGFILE__@
+abi_ansic = @abi_ansic@
+abi_extension = @abi_extension@
+abi_font = @abi_font@
+abi_videodrv = @abi_videodrv@
+abi_xinput = @abi_xinput@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_CXX = @ac_ct_CXX@
+ac_ct_F77 = @ac_ct_F77@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+driverdir = @driverdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+extdir = @extdir@
+ft_config = @ft_config@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+launchagentsdir = @launchagentsdir@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+logdir = @logdir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+moduledir = @moduledir@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sbindir = @sbindir@
+sdkdir = @sdkdir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+xglmoduledir = @xglmoduledir@
+xpconfigdir = @xpconfigdir@
+@BUILDDOCS_FALSE@SUBDIRS = man
+@BUILDDOCS_TRUE@SUBDIRS = devel man sgml
+EXTRA_DIST = \
+ README.DRI \
+ README.fonts \
+ README.rapidaccess
+
+all: all-recursive
+
+.SUFFIXES:
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps)
+ @for dep in $?; do \
+ case '$(am__configure_deps)' in \
+ *$$dep*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \
+ && exit 0; \
+ exit 1;; \
+ esac; \
+ done; \
+ echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign hw/xfree86/doc/Makefile'; \
+ cd $(top_srcdir) && \
+ $(AUTOMAKE) --foreign hw/xfree86/doc/Makefile
+.PRECIOUS: Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ @case '$?' in \
+ *config.status*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+ *) \
+ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+ esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+
+# This directory's subdirectories are mostly independent; you can cd
+# into them and run `make' without going through this Makefile.
+# To change the values of `make' variables: instead of editing Makefiles,
+# (1) if the variable is set in `config.status', edit `config.status'
+# (which will cause the Makefiles to be regenerated when you run `make');
+# (2) otherwise, pass the desired values on the `make' command line.
+$(RECURSIVE_TARGETS):
+ @failcom='exit 1'; \
+ for f in x $$MAKEFLAGS; do \
+ case $$f in \
+ *=* | --[!k]*);; \
+ *k*) failcom='fail=yes';; \
+ esac; \
+ done; \
+ dot_seen=no; \
+ target=`echo $@ | sed s/-recursive//`; \
+ list='$(SUBDIRS)'; for subdir in $$list; do \
+ echo "Making $$target in $$subdir"; \
+ if test "$$subdir" = "."; then \
+ dot_seen=yes; \
+ local_target="$$target-am"; \
+ else \
+ local_target="$$target"; \
+ fi; \
+ (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \
+ || eval $$failcom; \
+ done; \
+ if test "$$dot_seen" = "no"; then \
+ $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \
+ fi; test -z "$$fail"
+
+$(RECURSIVE_CLEAN_TARGETS):
+ @failcom='exit 1'; \
+ for f in x $$MAKEFLAGS; do \
+ case $$f in \
+ *=* | --[!k]*);; \
+ *k*) failcom='fail=yes';; \
+ esac; \
+ done; \
+ dot_seen=no; \
+ case "$@" in \
+ distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \
+ *) list='$(SUBDIRS)' ;; \
+ esac; \
+ rev=''; for subdir in $$list; do \
+ if test "$$subdir" = "."; then :; else \
+ rev="$$subdir $$rev"; \
+ fi; \
+ done; \
+ rev="$$rev ."; \
+ target=`echo $@ | sed s/-recursive//`; \
+ for subdir in $$rev; do \
+ echo "Making $$target in $$subdir"; \
+ if test "$$subdir" = "."; then \
+ local_target="$$target-am"; \
+ else \
+ local_target="$$target"; \
+ fi; \
+ (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \
+ || eval $$failcom; \
+ done && test -z "$$fail"
+tags-recursive:
+ list='$(SUBDIRS)'; for subdir in $$list; do \
+ test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) tags); \
+ done
+ctags-recursive:
+ list='$(SUBDIRS)'; for subdir in $$list; do \
+ test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) ctags); \
+ done
+
+ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES)
+ list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
+ unique=`for i in $$list; do \
+ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
+ done | \
+ $(AWK) '{ files[$$0] = 1; nonemtpy = 1; } \
+ END { if (nonempty) { for (i in files) print i; }; }'`; \
+ mkid -fID $$unique
+tags: TAGS
+
+TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \
+ $(TAGS_FILES) $(LISP)
+ tags=; \
+ here=`pwd`; \
+ if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \
+ include_option=--etags-include; \
+ empty_fix=.; \
+ else \
+ include_option=--include; \
+ empty_fix=; \
+ fi; \
+ list='$(SUBDIRS)'; for subdir in $$list; do \
+ if test "$$subdir" = .; then :; else \
+ test ! -f $$subdir/TAGS || \
+ tags="$$tags $$include_option=$$here/$$subdir/TAGS"; \
+ fi; \
+ done; \
+ list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
+ unique=`for i in $$list; do \
+ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
+ done | \
+ $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
+ END { if (nonempty) { for (i in files) print i; }; }'`; \
+ if test -z "$(ETAGS_ARGS)$$tags$$unique"; then :; else \
+ test -n "$$unique" || unique=$$empty_fix; \
+ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
+ $$tags $$unique; \
+ fi
+ctags: CTAGS
+CTAGS: ctags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \
+ $(TAGS_FILES) $(LISP)
+ tags=; \
+ list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
+ unique=`for i in $$list; do \
+ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
+ done | \
+ $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
+ END { if (nonempty) { for (i in files) print i; }; }'`; \
+ test -z "$(CTAGS_ARGS)$$tags$$unique" \
+ || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \
+ $$tags $$unique
+
+GTAGS:
+ here=`$(am__cd) $(top_builddir) && pwd` \
+ && cd $(top_srcdir) \
+ && gtags -i $(GTAGS_ARGS) $$here
+
+distclean-tags:
+ -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags
+
+distdir: $(DISTFILES)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ list='$(DISTFILES)'; \
+ dist_files=`for file in $$list; do echo $$file; done | \
+ sed -e "s|^$$srcdirstrip/||;t" \
+ -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+ case $$dist_files in \
+ */*) $(MKDIR_P) `echo "$$dist_files" | \
+ sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+ sort -u` ;; \
+ esac; \
+ for file in $$dist_files; do \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+ cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
+ fi; \
+ cp -pR $$d/$$file $(distdir)$$dir || exit 1; \
+ else \
+ test -f $(distdir)/$$file \
+ || cp -p $$d/$$file $(distdir)/$$file \
+ || exit 1; \
+ fi; \
+ done
+ list='$(DIST_SUBDIRS)'; for subdir in $$list; do \
+ if test "$$subdir" = .; then :; else \
+ test -d "$(distdir)/$$subdir" \
+ || $(MKDIR_P) "$(distdir)/$$subdir" \
+ || exit 1; \
+ distdir=`$(am__cd) $(distdir) && pwd`; \
+ top_distdir=`$(am__cd) $(top_distdir) && pwd`; \
+ (cd $$subdir && \
+ $(MAKE) $(AM_MAKEFLAGS) \
+ top_distdir="$$top_distdir" \
+ distdir="$$distdir/$$subdir" \
+ am__remove_distdir=: \
+ am__skip_length_check=: \
+ distdir) \
+ || exit 1; \
+ fi; \
+ done
+check-am: all-am
+check: check-recursive
+all-am: Makefile
+installdirs: installdirs-recursive
+installdirs-am:
+install: install-recursive
+install-exec: install-exec-recursive
+install-data: install-data-recursive
+uninstall: uninstall-recursive
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-recursive
+install-strip:
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ `test -z '$(STRIP)' || \
+ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+ -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+clean: clean-recursive
+
+clean-am: clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-recursive
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic distclean-tags
+
+dvi: dvi-recursive
+
+dvi-am:
+
+html: html-recursive
+
+info: info-recursive
+
+info-am:
+
+install-data-am:
+
+install-dvi: install-dvi-recursive
+
+install-exec-am:
+
+install-html: install-html-recursive
+
+install-info: install-info-recursive
+
+install-man:
+
+install-pdf: install-pdf-recursive
+
+install-ps: install-ps-recursive
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-recursive
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-recursive
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-recursive
+
+pdf-am:
+
+ps: ps-recursive
+
+ps-am:
+
+uninstall-am:
+
+.MAKE: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) install-am \
+ install-strip
+
+.PHONY: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) CTAGS GTAGS \
+ all all-am check check-am clean clean-generic clean-libtool \
+ ctags ctags-recursive distclean distclean-generic \
+ distclean-libtool distclean-tags distdir dvi dvi-am html \
+ html-am info info-am install install-am install-data \
+ install-data-am install-dvi install-dvi-am install-exec \
+ install-exec-am install-html install-html-am install-info \
+ install-info-am install-man install-pdf install-pdf-am \
+ install-ps install-ps-am install-strip installcheck \
+ installcheck-am installdirs installdirs-am maintainer-clean \
+ maintainer-clean-generic mostlyclean mostlyclean-generic \
+ mostlyclean-libtool pdf pdf-am ps ps-am tags tags-recursive \
+ uninstall uninstall-am
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/xorg-server/hw/xfree86/doc/README.DRI b/xorg-server/hw/xfree86/doc/README.DRI
new file mode 100644
index 000000000..7fc52eb32
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/README.DRI
@@ -0,0 +1,1256 @@
+ DRI User Guide
+
+ VA Linux Systems, Inc. Professional Services - Graphics.
+
+ 15 June 2001
+
+1. Preamble
+
+1.1 Copyright
+
+Copyright 2000-2001 by VA Linux Systems, Inc. All Rights Reserved.
+
+Permission is granted to make and distribute verbatim copies of this document
+provided the copyright notice and this permission notice are preserved on all
+copies.
+
+1.2 Trademarks
+
+OpenGL is a registered trademark and SGI is a trademark of Silicon Graphics,
+Inc. Unix is a registered trademark of The Open Group. The `X' device and X
+Window System are trademarks of The Open Group. XFree86 is a trademark of
+The XFree86 Project. Linux is a registered trademark of Linus Torvalds.
+Intel is a registered trademark of Intel Corporation. 3Dlabs, GLINT, and
+Oxygen are either registered trademarks or trademarks of 3Dlabs Inc. Ltd.
+3dfx, Voodoo3, Voodoo4, and Voodoo5 are registered trademarks of 3dfx Inter-
+active, Incorporated. Matrox is a registered trademark of Matrox Electronic
+Systems Ltd. ATI Rage and Radeon are registered trademarks of ATI Technolo-
+gies, Inc. All other trademarks mentioned are the property of their respec-
+tive owners.
+
+2. Introduction
+
+With XFree86 4.x and the Direct Rendering Interface (DRI), hardware acceler-
+ated 3D graphics can be considered a standard feature on Linux workstations.
+Support for other operating systems, such as FreeBSD, is underway.
+
+This document describes how to use the DRI system and troubleshoot problems
+which may occur. Readers should have a basic understanding of Linux, X and
+OpenGL. See the resources section at the end for more documentation and
+software downloads.
+
+This document does not cover compilation or installation of XFree86 4.x. It
+is assumed that you've already installed a Linux distribution which includes
+XFree86 4.x or that you're an experienced Linux developer who has compiled
+the DRI for himself. DRI download, compilation and installation instructions
+can be found at http://dri.sourceforge.net/DRIcompile.html
+
+Edits, corrections and updates to this document may be mailed to <brian@tung-
+stengrahpics.com>.
+
+3. Supported Architectures & Hardware
+
+3.1 CPU Architectures
+
+The architectures currently supported by the DRI have grown from the initial
+Intel i386 systems to now include the Alpha Processor and the Sun SPARC
+machines.
+
+Intel's SSE (a.k.a. Katmai) instructions are used in optimized vertex trans-
+formation functions in Mesa-based drivers. This requires a recent Linux ker-
+nel both at compile and runtime. See the DRI Compile Guide for compile-time
+requirements. At runtime a check is made to determine if the CPU can execute
+SSE instructions. They're disabled otherwise.
+
+AMD's 3DNow! instructions are also used in optimized vertex transformation
+functions in the Mesa-based DRI drivers. 3DNow! is supported in most ver-
+sions of Linux. Like the SSE optimizations, a runtime check is made to
+determine if the CPU can execute 3DNow! instructions.
+
+Alpha-based systems can use Compaq's optimized math library for improved 3D
+performance. See the DRI Compilation Guide for details.
+
+3.2 Graphics Hardware
+
+XFree86 4.2 (or later versions) includes 3D acceleration for the following
+graphics hardware:
+
+ o 3dfx, supported on Intel x86, AMD and Alpha:
+
+ o Voodoo5 5500
+
+ o Voodoo4 4500
+
+ o Voodoo3 3500 TV
+
+ o Voodoo3 3000 AGP
+
+ o Voodoo3 3000 PCI
+
+ o Voodoo3 2000 AGP
+
+ o Voodoo3 2000 PCI
+
+ o Voodoo Banshee
+
+ o Velocity 100/200
+
+ There are many configurations of 3dfx cards on the market. Not all have
+ been tested.
+
+ o Matrox, supported on Intel x86 and AMD:
+
+ o Matrox G200
+
+ o Matrox G400
+
+ o Intel i810/i815/i830 (motherboard chipsets)
+
+ o i810
+
+ o i810-dc100
+
+ o i810e
+
+ o i815
+
+ o i830
+
+ o ATI Rage 128, supported on Intel x86, AMD and Alpha:
+
+ o Rage Fury
+
+ o Rage Magnum
+
+ o XPERT 2000
+
+ o XPERT 128
+
+ o XPERT 99
+
+ o All-in-Wonder 128
+
+ o Rage 128 PCI (Alpha-based systems)
+
+ Note that both PCI and AGP versions of Rage 128 based cards are sup-
+ ported at this time.
+
+ o ATI Radeon, supported on Intel x86, AMD and Alpha:
+
+ o Radeon SDR AGP
+
+ o Radeon DDR AGP
+
+ o Radeon 32MB SDR PCI (Alpha-based systems)
+
+ o Radeon 7000, M6 (RV100)
+
+ o Radeon 7200 (R100)
+
+ o Radeon 7500, M7 (RV200)
+
+ o Radeon 8500, 9100 (R200)
+
+ o Radeon 9000, M9 (RV250)
+
+ o 3Dlabs, supported on Intel x86 and AMD:
+
+ o Oxygen GMX 2000 (MX/Gamma based). Note: this driver is no longer
+ being actively developed.
+
+Support for other hardware is underway. Most of the DRI development work is
+funded by contracts with IHVs. These contracts often prevent us from
+announcing drivers before they're released. Queries about upcoming drivers
+may not be answerable.
+
+4. Prerequisite Software
+
+ o The DRI is available in XFree86 4.0 and later.
+
+ o Some hardware drivers require specific versions of the Linux kernel for
+ AGP support, etc. See section 10 for specifics.
+
+ o You DO NOT need to install Mesa separately. The parts of Mesa needed
+ for hardware acceleration are already in the XFree86/DRI project.
+
+5. Kernel Modules
+
+3D hardware acceleration requires a DRI kernel module that's specific to your
+graphics hardware.
+
+The DRI kernel module version must exactly match your running kernel version.
+Since there are so many versions of the kernel, it's difficult to provide
+precompiled kernel modules.
+
+While the Linux source tree includes the DRI kernel module sources, the lat-
+est DRI kernel sources will be found in the DRI source tree.
+
+See the DRI Compilation Guide for information on compiling the DRI kernel
+modules.
+
+XFree86 4.0.1 added automatic kernel module loading to the X server. On
+Linux, the X server uses modprobe to load kernel modules. In Linux 2.4.x the
+DRM kernel modules should be kept in /lib/modules/2.4.x/ker-
+nel/drivers/char/drm/ for automatic loading to work.
+
+Optionally, DRM kernel modules can be loaded manually with insmod prior to
+starting the X server.
+
+You can verify that the kernel module was installed with lsmod, checking the
+X server startup log, and checking that /proc/dri/0 exists.
+
+6. XF86Config file
+
+The XFree86 configuration file is usually found in /etc/X11/XF86Config. This
+section describes the parts which must be specially set for the DRI.
+
+First, the XF86Config file must load the GLX and DRI modules:
+
+ Section "Module"
+ ...
+ # This loads the GLX module
+ Load "glx"
+ # This loads the DRI module
+ Load "dri"
+ EndSection
+
+Next, the DRI section can be used to restrict access to direct rendering. A
+client can only use direct rendering if it has permission to open the
+/dev/dri/card? file(s). The permissions on these DRI device files is con-
+trolled by the "DRI" section in the XF86Config file.
+
+If you want all of the users on your system to be able to use direct-render-
+ing, then use a simple DRI section like this:
+
+ Section "DRI"
+ Mode 0666
+ EndSection
+
+This section will allow any user with a current connection to the X server to
+use direct rendering.
+
+If you want to restrict the use of direct-rendering to a certain group of
+users, then create a group for those users by editing the /etc/group file on
+your system. For example, you may want to create a group called xf86dri and
+place two users (e.g., fred and jane) in that group. To do that, you might
+add the following line to /etc/group:
+
+ xf86dri:x:8000:fred,jane
+
+You have to be careful that the group id (8000 in this example) is unique.
+
+Then you would use the following DRI section:
+
+ Section "DRI"
+ Group "xf86dri"
+ Mode 0660
+ EndSection
+
+This would limit access to direct-rendering to those users in the xf86dri
+group (fred and jane in this example). When other users tried to use direct
+rendering, they would fall back to unaccelerated indirect rendering.
+
+[Note that there is a known bug in XFree86 4.0 that prevents some changes to
+the DRI section from taking effect. Until this bug is fixed, if you change
+the DRI section, please also remove the /dev/dri directory with the rm -rf
+/dev/dri command.]
+
+Finally, the XF86Config file needs Device and Screen sections specific to
+your hardware. Look in section 10: Hardware-Specific Information and Trou-
+bleshooting for details.
+
+7. Memory usage
+
+Using the 3D features of a graphics card requires more memory than when it's
+just used as a 2D device. Double buffering, depth buffering, stencil
+buffers, textures, etc. all require extra graphics memory. These features
+may require four times the memory used for a simple 2D display.
+
+If your graphics card doesn't have a lot of memory (less than 16MB, for exam-
+ple), you may have to reduce your screen size and/or color depth in order to
+use 3D features. Reducing the screen resolution will also leave more space
+for texture images, possibly improving 3D performance. If, for example, you
+play Quake3 at 1024x768 but start your display at 1600x1200 you might con-
+sider restarting X at 1024x768 in order to maximize your texture memory
+space.
+
+The documentation included with your card should have information about maxi-
+mum screen size when using 3D.
+
+8. Using 3D Acceleration
+
+This section describes how to link your application with libGL.so and verify
+that you are in fact using 3D acceleration.
+
+8.1 libGL.so
+
+Your OpenGL program must link with the libGL.so.1.2 library provided by
+XFree86. The libGL.so.1.2 library contains a GLX protocol encoder for indi-
+rect/remote rendering and DRI code for accessing hardware drivers. In par-
+ticular, be sure you're not using libGL.so from another source such as Mesa
+or the Utah GLX project.
+
+Unless it was built in a special way, the libGL.so library does not contain
+any 3D hardware driver code. Instead, libGL.so dynamically loads the appro-
+priate 3D driver during initialization.
+
+Most simple OpenGL programs also use the GLUT and GLU libraries. A source
+for these libraries is listed in the Resources section below.
+
+8.2 Compiling and linking an OpenGL program
+
+A simple GLUT/OpenGL program may be compiled and linked as follows:
+
+ gcc program.c -I/usr/local/include -L/usr/local/lib -L/usr/X11R6/lib -lglut -lGLU -lGL -o program
+
+The -I option is used to specify where the GL/glut.h (and possibly the
+GL/gl.h and GL/glu.h) header file may be found.
+
+The -L options specify where the libglut.so and the X libraries are located.
+libGL.so and libGLU.so should be in /usr/lib, as specified by the
+Linux/OpenGL ABI standard.
+
+The -lglut -lGLU -lGL arguments specify that the application should link with
+the GLUT, GLU and GL libraries, in that order.
+
+8.3 Running your OpenGL program
+
+Simply typing ./program in your shell should execute the program.
+
+If you get an error message such as
+
+ gears: error in loading shared libraries: libGL.so.1: cannot
+ open shared object file: No such file or directory
+
+if means that the libGL.so.1 file is not the right location. Proceed to the
+trouble shooting section.
+
+8.4 libOSMesa.so
+
+OSMesa (Off-Screen Mesa) is an interface and driver for rendering 3D images
+into a user-allocated block of memory rather than an on-screen window. It
+was originally developed for Mesa before Mesa became part of the XFree86/DRI
+project. It can now be used with the XFree86/DRI libGL.so as well.
+
+libOSMesa.so implements the OSMesa interface and it must be linked with your
+application if you want to use the OSMesa functions. You must also link with
+libGL.so. For example:
+
+ gcc osdemo.c -lOSMesa -lGLU -lGL -o osdemo
+
+In stand-alone Mesa this interface was compiled into the monolithic libGL.so
+(formerly libMesaGL.so) library. In XFree86 4.0.1 and later this interface
+is implemented in a separate library.
+
+8.5 glxinfo
+
+glxinfo is a useful program for checking which version of libGL you're using
+as well as which DRI-based driver. Simply type glxinfo and examine the
+OpenGL vendor, renderer, and version lines. Among the output you should see
+something like this:
+
+ OpenGL vendor string: VA Linux Systems, Inc.
+ OpenGL renderer string: Mesa DRI Voodoo3 20000224
+ OpenGL version string: 1.2 Mesa 3.4
+
+or this:
+
+ OpenGL vendor string: VA Linux Systems, Inc.
+ OpenGL renderer string: Mesa GLX Indirect
+ OpenGL version string: 1.2 Mesa 3.4
+
+The first example indicates that the 3dfx driver is using Voodoo3 hardware.
+The second example indicates that no hardware driver was found and indirect,
+unaccelerated rendering is being used.
+
+If you see that indirect rendering is being used when direct rendering was
+expected, proceed to the troubleshooting section.
+
+glxinfo also lists all of the GLX-enhanced visuals available so you can
+determine which visuals are double-bufferd, have depth (Z) buffers, stencil
+buffers, accumulation buffers, etc.
+
+8.6 Environment Variables
+
+The libGL.so library recognizes three environment variables. Normally, none
+of them need to be defined. If you're using the csh or tcsh shells, type
+setenv VARNAME value to set the variable. Otherwise, if you're using sh or
+bash, type export VARNAME=value.
+
+ 1. LIBGL_DEBUG, if defined will cause libGL.so to print error and diagnos-
+ tic messages. This can help to solve problems. Setting LIBGL_DEBUG to
+ verbose may provide additional information.
+
+ 2. LIBGL_ALWAYS_INDIRECT, if defined this will force libGL.so to always
+ use indirect rendering instead of hardware acceleration. This can be
+ useful to isolate rendering errors.
+
+ 3. LIBGL_DRIVERS_PATH can be used to override the default directories
+ which are searched for 3D drivers. The value is one or more paths sep-
+ arated by colons. In a typical XFree86 installation, the 3D drivers
+ should be in /usr/X11R6/lib/modules/dri/ and LIBGL_DRIVERS_PATH need
+ not be defined. Note that this feature is disabled for set-uid pro-
+ grams. This variable replaces the LIBGL_DRIVERS_DIR env var used in
+ XFree86 4.0.
+
+ 4. MESA_DEBUG, if defined, will cause Mesa-based 3D drivers to print user
+ error messages to stderr. These are errors that you'd otherwise detect
+ by calling glGetError.
+
+Mesa-based drivers (this includes most of the drivers listed above) also
+observe many of the existing Mesa environment variables. These include the
+MESA_DEBUG and MESA_INFO variables.
+
+9. General Trouble Shooting
+
+This section contains information to help you diagnose general problems. See
+below for additional information for specific hardware.
+
+9.1 Bus Mastering
+
+DMA-based DRI drivers (that's most DRI drivers) cannot function unless bus
+mastering is enabled for your graphics card. By default, some systems don't
+having bus mastering on. You should enable it in your BIOS.
+
+Alternately, you can check the status of bus mastering and change the setting
+from within Linux. There may be similar procedures for other operating sys-
+tems.
+
+Run lspci (as root) and find the information describing your graphics
+adapter. For example:
+
+ 00:00.0 Host bridge: Intel Corporation 440BX/ZX - 82443BX/ZX Host bridge (rev 03)
+ 00:01.0 PCI bridge: Intel Corporation 440BX/ZX - 82443BX/ZX AGP bridge (rev 03)
+ 00:07.0 ISA bridge: Intel Corporation 82371AB PIIX4 ISA (rev 02)
+ 00:07.1 IDE interface: Intel Corporation 82371AB PIIX4 IDE (rev 01)
+ 00:07.2 USB Controller: Intel Corporation 82371AB PIIX4 USB (rev 01)
+ 00:07.3 Bridge: Intel Corporation 82371AB PIIX4 ACPI (rev 02)
+ 00:11.0 Ethernet controller: Intel Corporation 82557 [Ethernet Pro 100] (rev 08)
+ 00:12.0 SCSI storage controller: Symbios Logic Inc. (formerly NCR) 53c895 (rev 02)
+ 00:14.0 Multimedia audio controller: Ensoniq ES1371 [AudioPCI-97] (rev 08)
+ 01:00.0 VGA compatible controller: 3Dfx Interactive, Inc.: Unknown device 0009 (rev 01)
+
+The bus, device, and function number comprise the device id, which is conven-
+tionally written in the form bus:dev.func, or in this case 01:00.0.
+
+Use the setpci command to examine bit two of register 4 for your graphics
+card. This will indicate whether or not bus mastering is enabled.
+
+ setpci -s 01:00.0 4.w
+
+A hexadecimal value will be printed. Convert the least significant digit to
+binary. For example, if you see 3, that's 0011 in binary (bit two is 0). If
+you see 7, that's 0111 in binary (bit two is 1). In the first example, bus
+mastering is disabled. It's enabled in the second example.
+
+The following shell script will enabled bus mastering for your graphics card
+and host bridge. Run it as root.
+
+ #!/bin/bash
+ dev=01:00.0 # change as appropriate
+ echo Enabling bus mastering on device $dev
+ setpci -s $dev 4.w=$(printf %x $((0x$(setpci -s $dev 4.w)|4)))
+ dev=00:00.0
+ echo Enabling bus mastering on host bridge $dev
+ setpci -s $dev 4.w=$(printf %x $((0x$(setpci -s $dev 4.w)|4)))
+
+You can check if this worked by running the first setpci command again.
+
+9.2 The X Server
+
+ 1. Before you start the X server, verify the appropriate 3D kernel module
+ is installed. Type lsmod and look for the appropriate kernel module.
+ For 3dfx hardware you should see tdfx, for example.
+
+ 2. Verify you're running XFree86 4.0 (or newer) and not an older version.
+ If you run xdpyinfo and look for the following line near the top:
+
+ vendor release number: 4000
+
+ 3. Verify that your XF86Config file (usually found at /etc/X11/XF86Config)
+ loads the glx and dri modules and has a DRI section.
+
+ See the Software Resources section below for sample XF86Config files.
+
+ 4. Examine the messages printed during X server startup and check that the
+ DRM module loaded. Using the Voodoo3 as an example:
+
+ (==) TDFX(0): Write-combining range (0xf0000000,0x2000000)
+ (II) TDFX(0): Textures Memory 7.93 MB
+ (0): [drm] created "tdfx" driver at busid "PCI:1:0:0"
+ (0): [drm] added 4096 byte SAREA at 0xc65dd000
+ (0): [drm] mapped SAREA 0xc65dd000 to 0x40013000
+ (0): [drm] framebuffer handle = 0xf0000000
+ (0): [drm] added 1 reserved context for kernel
+ (II) TDFX(0): [drm] Registers = 0xfc000000
+ (II) TDFX(0): visual configs initialized
+ (II) TDFX(0): Using XFree86 Acceleration Architecture (XAA)
+ Screen to screen bit blits
+ Solid filled rectangles
+ 8x8 mono pattern filled rectangles
+ Indirect CPU to Screen color expansion
+ Solid Lines
+ Dashed Lines
+ Offscreen Pixmaps
+ Driver provided NonTEGlyphRenderer replacement
+ Setting up tile and stipple cache:
+ 10 128x128 slots
+ (==) TDFX(0): Backing store disabled
+ (==) TDFX(0): Silken mouse enabled
+ (0): X context handle = 0x00000001
+ (0): [drm] installed DRM signal handler
+ (0): [DRI] installation complete
+ (II) TDFX(0): direct rendering enabled
+
+ 5. After the X server has started, verify that the required X server
+ extensions are loaded. Run xdpyinfo and look for the following entries
+ in the extensions list:
+
+ GLX
+ SGI-GLX
+ XFree86-DRI
+
+9.3 Linking, running and verifying 3D acceleration
+
+After you've verified that the X server and DRI have started correctly it's
+time to verify that the GL library and hardware drivers are working cor-
+rectly.
+
+ 1. Verify that you're using the correct libGL.so library with ldd. The
+ /usr/lib and /usr/X11R6/lib directories are expected locations for
+ libGL.so.
+
+ Example:
+
+ % ldd /usr/local/bin/glxinfo
+ libglut.so.3 => /usr/local/lib/libglut.so.3 (0x40019000)
+ libGLU.so.1 => /usr/local/lib/libGLU.so.1 (0x40051000)
+ libGL.so.1 => /usr/lib/libGL.so.1 (0x40076000)
+ libXmu.so.6 => /usr/X11R6/lib/libXmu.so.6 (0x402ee000)
+ libXi.so.6 => /usr/X11R6/lib/libXi.so.6 (0x40301000)
+ libm.so.6 => /lib/libm.so.6 (0x40309000)
+ libc.so.6 => /lib/libc.so.6 (0x40325000)
+ libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x40419000)
+ libXt.so.6 => /usr/X11R6/lib/libXt.so.6 (0x404bd000)
+ libSM.so.6 => /usr/X11R6/lib/libSM.so.6 (0x40509000)
+ libICE.so.6 => /usr/X11R6/lib/libICE.so.6 (0x40512000)
+ libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x40529000)
+ libvga.so.1 => /usr/lib/libvga.so.1 (0x40537000)
+ libpthread.so.0 => /lib/libpthread.so.0 (0x4057d000)
+ /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+
+ 2. You may also double check that libGL.so is in fact DRI-capable. Run
+ strings libGL.so.1.2 | grep DRI and look for symbols prefixed with
+ "XF86DRI", such as "XF86DRIQueryExtension".
+
+ 3. To be safe one should run ldconfig after installing libGL.so to be sure
+ the runtime loader will find the proper library.
+
+ 4. Verify that the appropriate 3D driver is in /usr/X11R6/lib/modules/dri/
+ For example, the 3dfx driver will be named tdfx_dri.so.
+
+ 5. Set the LIBGL_DEBUG environment variable. This will cause libGL.so to
+ print an error message if it fails to load a DRI driver. Any error
+ message printed should be self-explanatory.
+
+ 6. Run glxinfo. Note the line labeled "OpenGL renderer string". It
+ should have a value which starts with "Mesa DRI" followed by the name
+ of your hardware.
+
+ 7. Older Linux OpenGL applications may have been linked against Mesa's GL
+ library and will not automatically use libGL.so. In some cases, making
+ symbolic links from the Mesa GL library to libGL.so.1 will solve the
+ problem:
+
+ ln -s libGL.so.1 libMesaGL.so.3
+
+ In other cases, the application will have to be relinked against the
+ new XFree86 libGL.so.
+
+ It is reported that part of the problem is that running ldconfig will
+ silently rewrite symbolic links based on the SONAME field in libraries.
+
+If you're still having trouble, look in the next section for information spe-
+cific to your graphics card.
+
+10. Hardware-Specific Information and Troubleshooting
+
+This section presents hardware-specific information for normal use and trou-
+bleshooting.
+
+10.1 3dfx Banshee, Voodoo3, Voodoo4 and Voodoo5 Series
+
+10.1.1 Requirements
+
+The 3dfx DRI driver requires special versions of the 3dfx Glide library.
+Different versions of Glide are needed for Banshee/Voodoo3 than for
+Voodoo4/5. The Glide libraries can be downloaded from the DRI website.
+
+10.1.2 Configuration
+
+Your XF86Config file's device section must specify the tdfx device. For
+example:
+
+ Section "Device"
+ Identifier "Voodoo3"
+ VendorName "3dfx"
+ Driver "tdfx"
+ EndSection
+
+Or,
+
+ Section "Device"
+ Identifier "Voodoo5"
+ VendorName "3dfx"
+ Driver "tdfx"
+ EndSection
+
+The Screen section should then reference the Voodoo device:
+
+ Section "Screen"
+ Identifier "Screen 1"
+ Device "Voodoo3"
+ Monitor "High Res Monitor"
+ DefaultDepth 16
+ Subsection "Display"
+ Depth 16
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ EndSection
+
+Or,
+
+ Section "Screen"
+ Identifier "Screen 1"
+ Device "Voodoo5"
+ Monitor "High Res Monitor"
+ DefaultDepth 24
+ Subsection "Display"
+ Depth 16
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ Subsection "Display"
+ Depth 24
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ EndSection
+
+The kernel module for 3dfx hardware is named tdfx.o and should be installed
+in /lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically
+loaded by the Xserver if needed.
+
+The DRI 3D driver for 3dfx hardware should be in /usr/X11R6/lib/mod-
+ules/dri/tdfx_dri.so. This will be automatically loaded by libGL.so.
+
+The Voodoo5 supports 3D rendering in 16 and 32 bpp modes. When running in
+32bpp mode an 8-bit stencil buffer and 24-bit Z (depth) buffer are offered.
+When running in 16bpp mode only a 16-bit Z (depth) buffer is offered and
+stencil is implemented in software.
+
+A software-based accumulation buffer is available in both 16 and 32bpp modes.
+
+10.1.3 Troubleshooting
+
+ o If you try to run an OpenGL application and see an error message similar
+ to
+
+ gd error (glide): gd error (glide): grSstSelect: non-existent SSTgd error (glide): grSstSelect: non-existent SSTS
+
+ it means that you have the wrong version of the Glide library for your
+ hardware.
+
+ o 3D acceleration for Banshee and Voodoo3 is only supported in the 16
+ bit/pixel screen mode. Use xdpyinfo to verify that all your visuals are
+ depth 16. Edit your XF86Config file if needed.
+
+ o The /dev/3dfx device is not used for DRI; it's only for Glide on older
+ 3dfx hardware.
+
+ o Different versions of Glide are needed for Voodoo3 and Voodoo5. See the
+ DRI website's resources page to download the right version of Glide.
+
+ o Voodoo4/5 may be run at 24bpp (instead of 32bpp, the default) but 3D
+ acceleration is not supported in that mode. 32bpp mode is fully 3D
+ accelerated.
+
+10.1.4 Performance and Features
+
+ o Normally, buffer swapping in double-buffered applications is synchro-
+ nized to your monitor's refresh rate. This may be overridden by setting
+ the FX_GLIDE_SWAPINTERVAL environment variable. The value of this vari-
+ able indicates the maximum number of swap buffer commands can be
+ buffered. Zero allows maximum frame rate.
+
+ o On Voodoo4/5, rendering with 16-bits/texel textures is faster than using
+ 32-bit per texel textures. The internalFormat parameter to glTexImage2D
+ can be used to control texel size. Quake3 and other games let you con-
+ trol this as well.
+
+ o The glTexEnv mode GL_BLEND is not directly supported by the Voodoo3
+ hardware. It can be accomplished with a multipass algorithm but it's
+ not implemented at this time. Applications which use that mode, such as
+ the Performer Town demo, may become sluggish when falling back to soft-
+ ware rendering to render in that mode.
+
+ o The Voodoo3/Banshee driver reverts to software rendering under the fol-
+ lowing conditions:
+
+ o Setting GL_LIGHT_MODEL_COLOR_CONTROL to GL_SEPARATE_SPECULAR_COLOR.
+
+ o Enabling line stippling or polygon stippling.
+
+ o Enabling point smoothing or polygon smoothing.
+
+ o Enabling line smoothing when line width is not 1.0. That is,
+ antialiased lines are done in hardware only when the line width is
+ 1.0.
+
+ o Using 1-D or 3-D texture maps.
+
+ o Using the GL_BLEND texture environment.
+
+ o Using stencil operations.
+
+ o Using the accumulation buffer.
+
+ o Using glBlendEquation(GL_LOGIC_OP).
+
+ o Using glDrawBuffer(GL_FRONT_AND_BACK).
+
+ o Using glPolygonMode(face, GL_POINT) or glPolygonMode(face,
+ GL_LINE).
+
+ o Using point size attenuation (i.e. GL_DISTANCE_ATTENUATION_EXT).
+
+ o Using glColorMask(r, g, b, a) when r!=g or g!=b.
+
+ o The Voodoo5 driver reverts to software rendering under the same condi-
+ tions Voodoo3 with three exceptions. First, stencil operations are
+ implemented in hardware when the screen is configured for 32 bits/pixel.
+ Second, the GL_BLEND texture env mode is fully supported in hardware.
+ Third, glColorMask is fully supported in hardware when the screen is
+ configured for 32 bits/pixel.
+
+ o As of January, 2001 the second VSA-100 chip on the Voodoo5 is not yet
+ operational. Therefore, the board isn't being used to its full capac-
+ ity. The second VSA-100 chip will allow Scan-Line Interleave (SLI) mode
+ for full-screen applications and games, potentially doubling the sys-
+ tem's fill rate. When the second VSA-100 chip is activated glGet-
+ String(GL_RENDERER) will report Voodoo5 instead of Voodoo4.
+
+ o The lowest mipmap level is sometimes miscolored in trilinear- sampled
+ polygons.
+
+ o The GL_EXT_texture_env_combine extension is supported on the Voodoo4 and
+ Voodoo5.
+
+10.1.5 Known Problems
+
+ o The lowest mipmap level is sometimes miscolored in trilinear- sampled
+ polygons (Voodoo3/Banshee).
+
+ o Fog doesn't work with orthographic projections.
+
+ o The accuracy of blending operations on Voodoo4/5 isn't always very good.
+ If you run Glean, you'll find some test failures.
+
+ o The Glide library cannot be used directly; it's only meant to be used
+ via the tdfx DRI driver.
+
+ o SSystem has problems because of poorly set near and far clipping planes.
+ The office.unc Performer model also suffers from this problem.
+
+10.2 Intel i810
+
+10.2.1 Requirements
+
+A kernel with AGP GART support (such as Linux 2.4.x) is needed.
+
+10.2.2 Configuration
+
+Your XF86Config file's device section must specify the i810 device, and spec-
+ify a usable amount of video ram to reserve.
+
+ Section "Device"
+ Identifier "i810"
+ VendorName "Intel"
+ Driver "i810"
+ Option "AGPMode" "1"
+ VideoRam 10000
+ EndSection
+
+The Screen section should then reference the i810 device:
+
+ Section "Screen"
+ Identifier "Screen 1"
+ Device "i810"
+ Monitor "High Res Monitor"
+ DefaultDepth 16
+ Subsection "Display"
+ Depth 16
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ EndSection
+
+The kernel module for the i810 is named i810.o and should be installed in
+/lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically loaded
+by the Xserver if needed.
+
+The DRI 3D driver for the i810 should be in /usr/X11R6/lib/mod-
+ules/dri/i810_dri.so. This will be automatically loaded by libGL.so.
+
+10.2.3 Troubleshooting
+
+ o 3D acceleration for the i810 is only available in the 16 bit/pixel
+ screen mode at this time. 32bpp acceleration is not supported by this
+ hardware. Use xdpyinfo to verify that all your visuals are depth 16.
+ Edit your XF86Config file if needed.
+
+ o The i810 uses system ram for video and 3d graphics. The X server will
+ ordinarily reserve 4mb of ram for graphics, which is too little for an
+ effective 3d setup. To tell the driver to use a larger amount, specify
+ a VideoRam option in the Device section of your XF86Config file. A num-
+ ber between 10000 and 16384 seems adequate for most requirements. If
+ too little memory is available for DMA buffers, back and depth buffers
+ and textures, direct rendering will be disabled.
+
+10.2.4 Performance and Features
+
+Basically all of the i810 features which can be exposed through OpenGL 1.2
+are implemented. However, the following OpenGL features are implemented in
+software and will be slow:
+
+ o Stencil buffer and accumulation buffer operations
+
+ o Blend subtract, min/max and logic op blend modes
+
+ o glColorMask when any mask is set to false
+
+ o GL_SEPARATE_SPECULAR_COLOR lighting mode
+
+ o glDrawBuffer(GL_FRONT_AND_BACK)
+
+ o Using 1D or 3D textures
+
+ o Using texture borders
+
+10.3 Matrox G200 and G400
+
+10.3.1 Requirements
+
+A kernel with AGP GART support (such as Linux 2.4.x) is needed.
+
+10.3.2 Configuration
+
+Your XF86Config file's device section must specify the mga device:
+
+ Section "Device"
+ Identifier "MGA"
+ VendorName "Matrox"
+ Driver "mga"
+ Option "AGPMode" "1"
+ VideoRam 32768
+ EndSection
+
+The Screen section should then reference the MGA device:
+
+ Section "Screen"
+ Identifier "Screen 1"
+ Device "MGA"
+ Monitor "High Res Monitor"
+ DefaultDepth 16
+ Subsection "Display"
+ Depth 16
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ EndSection
+
+To use a 32bpp screen mode, use this Screen section instead:
+
+ Section "Screen"
+ Identifier "Screen 1"
+ Device "MGA"
+ Monitor "High Res Monitor"
+ DefaultDepth 24
+ DefaultFbBpp 32
+ Subsection "Display"
+ Depth 24
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ EndSection
+
+The kernel module for the G200/G400 is named mga.o and should be installed in
+/lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically loaded
+by the Xserver if needed.
+
+The DRI 3D driver for the G200/G400 should be in /usr/X11R6/lib/mod-
+ules/dri/mga_dri.so. This will be automatically loaded by libGL.so.
+
+10.3.3 Performance and Features
+
+Software rendering will be used under any of the following conditions:
+
+ o Using glDrawBuffer(GL_FRONT_AND_BACK).
+
+ o Using point, line, or triangle smoothing.
+
+ o Using glLogicOp.
+
+ o Using glPolygonStipple or glLineStipple.
+
+ o Using 1D or 3D textures.
+
+ o Using texture borders.
+
+ o Using glDepthFunc(GL_NEVER).
+
+ o Using the accumulation buffer.
+
+The AGP mode may be set to 1, 2, or 4. One is used by default. Higher AGP
+speeds may result in unreliable performance depending on your motherboard.
+
+Compaq has funded the implementation of AGP accelerated ReadPixels and Draw-
+Pixels in this driver. With this implementation, on a G400 drawing directly
+from AGP memory (exported to the client), throughput of up to 1 GB/sec has
+been measured.
+
+Additionally Compaq's funding has produced several new extensions in Mesa,
+including one (packed_depth_stencil_MESA) which enables Read/DrawPixels func-
+tionality to operate directly on the packed 24/8 depth/stencil buffers of
+this hardware.
+
+In order to access this functionality, the application must ensure that all
+pixel processing operations are disabled. There are in addition a fairly
+complex set of rules regarding which packing/unpacking modes must be used,
+and which data formats are supported, and alignment constraints. See the
+files in lib/GL/mesa/src/drv/mga/DOCS for a summary of these. The extension
+definitions are included in the Mesa 3.4 source distribution.
+
+10.3.4 IRQ Assignment
+
+There have been problems in the past with the MGA driver being very sluggish
+when the DRI is enabled (to the point of being unusable.) This is caused by
+the graphics card not having an interrupt assigned to it. The current DRI
+trunk will attempt to detect this condition and bail out gracefully.
+
+The solution to the above problem is to assign an interrupt to your graphics
+card. This is something you must turn on in your system BIOS configuration.
+Please consult your system BIOS manual for instructions on how to enable an
+interrupt for your graphics card.
+
+10.3.5 MGA HAL lib
+
+MGAHALlib.a is a binary library Matrox has provided for use under Linux to
+expose functionality for which they can not provide documentation. (For
+example TV-Out requires MacroVision be enabled on the output.) This binary
+library also sets the pixel/memory clocks to the optimal settings for your
+Matrox card.
+
+Currently the MGAHAL library is required for the G450 to work. You can down-
+load this from the driver section on Matrox's website: www.matrox.com/mga
+
+Here modifications to the DRI build instructions which make the mga ddx
+driver use the MGAHAL library:
+
+ 1.Put the following define in your host.def file
+ #define UseMatroxHal YES
+ 2. Place mgaHALlib.a in the following directory
+ xc/programs/Xserver/hw/xfree86/drivers/mga/HALlib/
+
+You can use DualHead on the G400/G450 DH cards by creating two device sec-
+tions which both point to the same BusID. For most AGP devices the BusID
+will be "PCI:1:0:0". Configure your screen section as you would normally
+configure XFree86 4.x Multihead. It should be noted that currently the sec-
+ond head does not support direct rendering.
+
+10.3.6 Known Problems
+
+None.
+
+10.4 ATI Rage 128
+
+10.4.1 Requirements
+
+A kernel with AGP GART support (such as Linux 2.4.x) is needed.
+
+10.4.2 Configuration
+
+Your XF86Config file's device section must specify the ati device:
+
+ Section "Device"
+ Identifier "Rage128"
+ VendorName "ATI"
+ Driver "ati"
+ Option "AGPMode" "1"
+ Option "UseCCEFor2D" "false"
+ EndSection
+
+The Screen section should then reference the Rage 128 device:
+
+ Section "Screen"
+ Identifier "Screen 1"
+ Device "Rage128"
+ Monitor "High Res Monitor"
+ DefaultDepth 16
+ Subsection "Display"
+ Depth 16
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ Subsection "Display"
+ Depth 32
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ EndSection
+
+The kernel module for the Rage 128 is named r128.o and should be installed in
+/lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically loaded
+by the Xserver if needed.
+
+The DRI 3D driver for the Rage 128 should be in /usr/X11R6/lib/mod-
+ules/dri/r128_dri.so. This will be automatically loaded by libGL.so.
+
+You may also set your screen depth to 32 for 32bpp mode.
+
+10.4.3 Performance and Features
+
+While PCI Rage 128 based cards are supported, they do not yet support PCI
+GART, so they will not perform as well as their AGP counterparts.
+
+For AGP cards, the AGP mode may be set to 1, 2, or 4. One is used by
+default. Higher AGP speeds may result in unreliable performance depending on
+your motherboard.
+
+Note that even at 32bpp there is no alpha channel.
+
+The following OpenGL features are implemented in software and will be slow:
+
+ o accumulation buffer operations
+
+ o stencil, when using a 16bpp screen
+
+ o Blend subtract, min/max and logic op blend modes
+
+ o GL_SEPARATE_SPECULAR_COLOR lighting mode
+
+ o glDrawBuffer(GL_FRONT_AND_BACK)
+
+ o Using 1D or 3D textures
+
+ o Using texture borders
+
+10.4.4 Known Problems
+
+If you experience stability problems you may try setting the UseCCEFor2D
+option to true. This will effectively disable 2D hardware acceleration.
+Performance will be degraded, of course.
+
+10.5 ATI Radeon
+
+10.5.1 Requirements
+
+A kernel with AGP GART support (such as Linux 2.4.x) is needed.
+
+10.5.2 Configuration
+
+Your XF86Config file's device section must specify the ati device:
+
+ Section "Device"
+ Identifier "Radeon"
+ VendorName "ATI"
+ Driver "ati"
+ Option "AGPMode" "1"
+ EndSection
+
+The Screen section should then reference the Radeon device:
+
+ Section "Screen"
+ Identifier "Screen 1"
+ Device "Radeon"
+ Monitor "High Res Monitor"
+ DefaultDepth 16
+ Subsection "Display"
+ Depth 16
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ Subsection "Display"
+ Depth 32
+ Modes "1280x1024" "1024x768" "800x600" "640x480"
+ ViewPort 0 0
+ EndSubsection
+ EndSection
+
+The kernel module for the Radeon is named radeon.o and should be installed in
+/lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically loaded
+by the Xserver if needed.
+
+The DRI 3D driver for the Radeon should be in /usr/X11R6/lib/mod-
+ules/dri/radeon_dri.so. This will be automatically loaded by libGL.so.
+
+You may also set your screen depth to 32 for 32bpp mode.
+
+10.5.3 Performance and Features
+
+While this driver supports many of the features of ATI Radeon cards, we do
+not yet fully support the card's TCL features. This work is progressing, but
+is not yet ready.
+
+The AGP mode may be set to 1, 2, or 4. One is used by default. Higher AGP
+speeds may result in unreliable performance depending on your motherboard.
+
+The following OpenGL features are implemented in software and will be slow:
+
+ o Blend subtract, blend min/max and blend logicops
+
+ o Stencil and accumulation operations
+
+ o 1D and 3D textures
+
+ o Texture borders
+
+The GL_EXT_texture_env_combine, GL_EXT_texture_env_add and GL_EXT_tex-
+ture_env_dot3 extensions are supported (or will be soon supported in the new
+driver based on Mesa 3.5).
+
+We hope to implement support for the following features in the future:
+
+ o Vertex transformation, clipping and lighting (TCL)
+
+ o Hardware stencil buffer
+
+ o Cube map textures
+
+ o 3D textures
+
+ o Three texture units
+
+10.5.4 Known Problems
+
+Certain (early?) revisions of the AMD Irongate chipset have AGPGART problems
+which effect Radeon, and other graphics cards. The card may work unreliably,
+or not work at all. If the DRM kernel module is not loaded, the 2D Xserver
+may work. There's hope that this can be fixed in the future.
+
+10.6 3DLabs Oxygen GMX 2000
+
+The driver for this hardware was experimental and is no longer being devel-
+oped or supported.
+
+11. General Limitations and Known Bugs
+
+11.1 OpenGL
+
+The following OpenGL features are not supported at this time: overlays,
+stereo, hardware-accelerated indirect rendering.
+
+OpenGL-like functionality is provided with the Mesa library. XFree86 4.1.0
+uses Mesa 3.4.2. Subsequent releases of XFree86 will use newer versions of
+Mesa. When newer versions of Mesa are available, the 3D drivers can be
+updated without reinstalling XFree86 or libGL.so.
+
+11.2 GLX
+
+The GLX 1.3 API is exported but none of the new 1.3 functions are opera-
+tional.
+
+The new glXGetProcAddressARB function is fully supported.
+
+GLXPixmap rendering is only supported for indirect rendering contexts. This
+is a common OpenGL limitation. Attempting to use a direct rendering context
+with a GLXPixmap will result in an X protocol error.
+
+11.3 Debugging
+
+Debugging DRI drivers with gdb can be difficult because of the locking
+involved. When debugging OpenGL applications, you should avoid stepping
+inside the GL functions. If you're trying to debug a DRI driver it's recom-
+mended that you do so remotely, from a second system.
+
+11.4 Scheduling
+
+When you run multiple GL applications at once you may notice poor time slic-
+ing. This is due to an interaction problem with the Linux scheduler which
+will be addressed in the future.
+
+11.5 libGL.so and dlopen()
+
+A number of popular OpenGL applications on Linux (such as Quake3, HereticII,
+Heavy Gear 2, etc) dynamically open the libGL.so library at runtime with
+dlopen(), rather than linking with -lGL at compile/link time.
+
+If dynamic loading of libGL.so is not implemented carefully, there can be a
+number of serious problems. Here are the things to be careful of in your
+application:
+
+ o Specify the RTLD_GLOBAL flag to dlopen(). If you don't do this then
+ you'll likely see a runtime error message complaining that _glapi_Con-
+ text is undefined when libGL.so tries to open a hardware-specific
+ driver. Without this flag, nested opening of dynamic libraries does not
+ work.
+
+ o Do not close the library with dlclose() until after XCloseDisplay() has
+ been called. When libGL.so initializes itself it registers several
+ callbacks functions with Xlib. When XCloseDisplay() is called those
+ callback functions are called. If libGL.so has already been unloaded
+ with dlclose() this will cause a segmentation fault.
+
+ o Your application should link with -lpthread. On Linux, libGL.so uses
+ the pthreads library in order to provide thread safety. There is appar-
+ ently a bug in the dlopen()/dlclose() code which causes crashes if the
+ library uses pthreads but the parent application doesn't. The only
+ known work-around is to link the application with -lpthread.
+
+Some applications don't yet incorporate these procedures and may fail. For
+example, changing the graphics settings in some video games will expose this
+problem. The DRI developers are working with game vendors to prevent this
+problem in the future.
+
+11.6 Bug Database
+
+The DRI bug database which includes bugs related to specific drivers is at
+the SourceForge DRI Bug Database
+
+Please scan both the open and closed bug lists to determine if your problem
+has already been reported and perhaps fixed.
+
+12. Resources
+
+12.1 Software
+
+A collection of useful configuration files, libraries, headers, utilities and
+demo programs is available from http://dri.sourceforge.net/res.phtml
+
+12.2 Documentation
+
+ o General OpenGL information is available at the OpenGL Home Page
+
+ o XFree86 information is available at the XFree86 Home Page
+
+ o Information about the design of the DRI is available from Precision
+ Insight, Inc.
+
+ o Visit the DRI project on SourceForge.net for the latest development news
+ about the DRI and 3D drivers.
+
+ o The DRI Compilation Guide explains how to download, compile and install
+ the DRI for yourself.
+
+12.3 Support
+
+ o The DRI-users mailing list at SourceForge is a forum for people to dis-
+ cuss DRI problems.
+
+ o In the future there may be IHV and Linux vendor support resources for
+ the DRI.
+
+ Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml,v 1.28 dawes Exp $
+
+
diff --git a/xorg-server/hw/xfree86/doc/README.fonts b/xorg-server/hw/xfree86/doc/README.fonts
new file mode 100644
index 000000000..0ad2b49d0
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/README.fonts
@@ -0,0 +1,1158 @@
+ Fonts in X11R6.9
+
+ Juliusz Chroboczek, <jch@pps.jussieu.fr>
+
+ 25 March 2004
+
+1. Introduction
+
+This document describes the support for fonts in X11R6.9. Installing fonts
+(section 2., page 1) is aimed at the casual user wishing to install fonts in
+X11R6.9 the rest of the document describes the font support in more detail.
+
+We assume some familiarity with digital fonts. If anything is not clear to
+you, please consult Appendix: Background (section 5., page 1) at the end of
+this document for background information.
+
+1.1 Two font systems
+
+X includes two font systems: the original core X11 fonts system, which is
+present in all implementations of X11, and the Xft fonts system, which may
+not be distributed with implementations of X11 that are not based on X11R6.9
+but will hopefully be included by them in the future
+
+The core X11 fonts system is directly derived from the fonts system included
+with X11R1 in 1987, which could only use monochrome bitmap fonts. Over the
+years, it has been more or less happily coerced into dealing with scalable
+fonts and rotated glyphs.
+
+Xft was designed from the start to provide good support for scalable fonts,
+and do so efficiently. Unlike the core fonts system, it supports features
+such as anti-aliasing and sub-pixel rasterisation. Perhaps more importantly,
+it gives applications full control over the way glyphs are rendered, making
+fine typesetting and WYSIWIG display possible. Finally, it allows applica-
+tions to use fonts that are not installed system-wide for displaying docu-
+ments with embedded fonts.
+
+Xft is not compatible with the core fonts system: usage of Xft requires mak-
+ing fairly extensive changes to toolkits (user-interface libraries). While
+X.org will continue to maintain the core fonts system, toolkit authors are
+encouraged to switch to Xft as soon as possible.
+
+2. Installing fonts
+
+This section explains how to configure both Xft and the core fonts system to
+access newly-installed fonts.
+
+2.1 Configuring Xft
+
+Xft has no configuration mechanism itself, rather it relies upon the fontcon-
+fig library to configure and customize fonts. That library is not specific
+to X11R6.9 or indeed on any particular font output mechanism. This discus-
+sion describes how fontconfig, rather than Xft, works.
+
+2.1.1 Installing fonts in Xft
+
+Fontconfig looks for fonts in a set of well-known directories that include
+all of X11R6.9's standard font directories (`/usr/X11R6/lib/X11/lib/fonts/*')
+by default) as well as a directory called `.fonts/' in the user's home direc-
+tory. Installing a font for use by Xft applications is as simple as copying
+a font file into one of these directories.
+
+ $ cp lucbr.ttf ~/.fonts/
+
+Fontconfig will notice the new font at the next opportunity and rebuild its
+list of fonts. If you want to trigger this update from the command line (for
+example in order to globally update the system-wide Fontconfig information),
+you may run the command `fc-cache'.
+
+ $ fc-cache
+
+2.1.2 Fine-tuning Xft
+
+Fontconfig's behaviour is controlled by a set of configuration files: a sys-
+tem-wide configuration file, `/etc/fonts/fonts.conf', and a user-specific
+file called `.fonts.conf' in the user's home directory (this can be overrid-
+den with the `FONTCONFIG_FILE' environment variable).
+
+Every Fontconfig configuration file must start with the following boiler-
+plate:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+ <fontconfig>
+
+In addition, every Fontconfig configuration file must end with the following
+line:
+
+ </fontconfig>
+
+The default Fontconfig configuration file includes the directory `~/.fonts/'
+in the list of directories searched for font files, and this is where user-
+specific font files should be installed. In the unlikely case that a new
+font directory needs to be added, this can be done with the following syntax:
+
+ <dir>/usr/local/share/fonts/</dir>
+
+Another useful option is the ability to disable anti-aliasing (font smooth-
+ing) for selected fonts. This can be done with the following syntax:
+
+ <match target="font">
+ <test qual="any" name="family">
+ <string>Lucida Console</string>
+ </test>
+ <edit name="antialias" mode="assign">
+ <bool>false</bool>
+ </edit>
+ </match>
+
+Anti-aliasing can be disabled for all fonts by the following incantation:
+
+ <match target="font">
+ <edit name="antialias" mode="assign">
+ <bool>false</bool>
+ </edit>
+ </match>
+
+Xft supports sub-pixel rasterisation on LCD displays. X11R6.9 should auto-
+matically enable this feature on laptops and when using an LCD monitor con-
+nected with a DVI cable; you can check whether this was done by typing
+
+ $ xdpyinfo -ext RENDER | grep sub-pixel
+
+If this doesn't print anything, you will need to configure Render for your
+particular LCD hardware manually; this is done with the following syntax:
+
+ <match target="font">
+ <edit name="rgba" mode="assign">
+ <const>rgb</const>
+ </edit>
+ </match>
+
+The string `rgb' within the `<const>'...`</const>' specifies the order of
+pixel components on your display, and should be changed to match your hard-
+ware; it can be one of `rgb (normal LCD screen), `bgr' (backwards LCD
+screen), `vrgb' (LCD screen rotated clockwise) or `vbgr' (LCD screen rotated
+counterclockwise).
+
+2.1.3 Configuring applications
+
+Because most current applications use the core fonts system by default, it is
+necessary to explicitly configure them to use Xft. How this is done depends
+on the application.
+
+XTerm can be set to use Xft by using the `-fa' command line option or by set-
+ting the `XTerm*faceName' resource:
+
+ XTerm*faceName: Courier
+
+or
+
+ $ xterm -fa "Courier"
+
+For applications based on GTK+ 2.0 (including GNOME 2 applications), the
+environment variable `GDK_USE_XFT' should be set to `1':
+
+ $ export GDK_USE_XFT=1
+
+GTK+ 2.2 uses Xft by default.
+
+For KDE applications, you should select ``Anti-alias fonts'' in the ``Fonts''
+panel of KDE's ``Control Center''. Note that this option is misnamed: it
+switches KDE to using Xft but doesn't enable anti-aliasing in case it was
+disabled by your Xft configuration file.
+
+(What about Mozilla?)
+
+2.1.4 Troubleshooting
+
+If some Xft-based applications don't seem to notice the changes you are mak-
+ing to your configuration files, they may be linked against an old version of
+Xft. In order to fix the problem, you should relink them against a current
+version of Xft; on most systems, it is enough to install the current version
+of the Xft and Fontconfig libraries.
+
+If, for some reason, you cannot upgrade the shared libraries, please check
+the Xft(3) manual page included with XFree86 4.2 for the configuration mecha-
+nisms of the previous version of Xft.
+
+2.2 Configuring the core X11 fonts system
+
+Installing fonts in the core system is a two step process. First, you need
+to create a font directory that contains all the relevant font files as well
+as some index files. You then need to inform the X server of the existence
+of this new directory by including it in the font path.
+
+2.2.1 Installing bitmap fonts
+
+The X11R6.9 server can use bitmap fonts in both the cross-platform BDF format
+and the somewhat more efficient binary PCF format. (X11R6.9 also supports
+the obsolete SNF format.)
+
+Bitmap fonts are normally distributed in the BDF format. Before installing
+such fonts, it is desirable (but not absolutely necessary) to convert the
+font files to the PCF format. This is done by using the command `bdftopcf',
+e.g.
+
+ $ bdftopcf courier12.bdf
+
+You will then want to compress the resulting PCF font files:
+
+ $ gzip courier12.pcf
+
+After the fonts have been converted, you should copy all the font files that
+you wish to make available into a arbitrary directory, say
+`/usr/local/share/fonts/bitmap/'. You should then create the index file
+`fonts.dir' by running the command `mkfontdir' (please see the mkfontdir(1)
+manual page for more information):
+
+ $ mkdir /usr/local/share/fonts/bitmap/
+ $ cp *.pcf.gz /usr/local/share/fonts/bitmap/
+ $ mkfontdir /usr/local/share/fonts/bitmap/
+
+All that remains is to tell the X server about the existence of the new font
+directory; see Setting the server font path (section 2.2.4, page 1) below.
+
+2.2.2 Installing scalable fonts
+
+The X11R6.9 server supports scalable fonts in three formats: Type 1, TrueType
+and CIDFont. This section only applies to the first two; for information on
+CIDFonts, please see Installing CIDFonts (section 2.2.3, page 1) later in
+this document. Previous versions also included support for the Speedo scal-
+able font format, but that is disabled in the default builds of X11R6.9 and
+not included in X11R7.0 and later releases.
+
+Installing scalable fonts is very similar to installing bitmap fonts: you
+create a directory with the font files, and run `mkfontdir' to create an
+index file called `fonts.dir'.
+
+There is, however, a big difference: `mkfontdir' cannot automatically recog-
+nise scalable font files. For that reason, you must first index all the font
+files in a file called `fonts.scale'. While this can be done by hand, it is
+best done by using the `mkfontscale' utility.
+
+ $ mkfontscale /usr/local/share/fonts/Type1/
+ $ mkfontdir /usr/local/share/fonts/Type1/
+
+Under some circumstances, it may be necessary to modify the `fonts.scale'
+file generated by mkfontscale; for more information, please see the mkfont-
+dir(1) and mkfontscale(1) manual pages and Core fonts and internationalisa-
+tion (section 4.1, page 1) later in this document.
+
+2.2.3 Installing CID-keyed fonts
+
+The CID-keyed font format was designed by Adobe Systems for fonts with large
+character sets. A CID-keyed font, or CIDFont for short, contains a collec-
+tion of glyphs indexed by character ID (CID).
+
+In order to map such glyphs to meaningful indices, Adobe provide a set of
+CMap files. The PostScript name of a font generated from a CIDFont consists
+of the name of the CIDFont and the name of the CMap separated by two dashes.
+For example, the font generated from the CIDFont `Munhwa-Regular' using the
+CMap `UniKS-UCS2-H' is called
+
+ Munhwa-Regular--UniKS-UCS2-H
+
+The CIDFont code in X11R6.9 requires a very rigid directory structure. The
+main directory must be called `CID' (its location defaults to
+`/usr/X11R6/lib/X11/fonts/CID' but it may be located anywhere), and it should
+contain a subdirectory for every CID collection. Every subdirectory must
+contain subdirectories called CIDFont (containing the actual CIDFont files),
+CMap (containing all the needed CMaps), AFM (containing the font metric
+files) and CFM (initially empty). For example, in the case of the font
+Munhwa-Regular that uses the CID collection Adobe-Korea1-0, the directory
+structure should be as follows:
+
+ CID/Adobe-Korea1/CIDFont/Munhwa-Regular
+ CID/Adobe-Korea1/CMap/UniKS-UCS2-H
+ CID/Adobe-Korea1/AFM/Munhwa-Regular.afm
+ CID/Adobe-Korea1/CFM/
+ CID/fonts.dir
+ CID/fonts.scale
+
+After creating this directory structure and copying the relevant files, you
+should create a `fonts.scale' file. This file has the same format as in the
+case of (non-CID) scalable fonts, except that its first column contains
+PostScript font names with the extension `.cid' appended rather than actual
+filenames:
+
+ 1
+ Adobe-Korea1/Munhwa-Regular--UniKS-UCS2-H.cid \
+ -adobe-munhwa-medium-r-normal--0-0-0-0-p-0-iso10646-1
+
+(both names on the same line). Running `mkfontdir' creates the `fonts.dir'
+file:
+
+ $ cd /usr/local/share/fonts/CID
+ $ mkfontdir
+
+Finally, you should create the font metrics summary files in the directory
+`CFM' by running the command `mkcfm':
+
+ $ mkcfm /usr/local/share/fonts/CID
+
+If no CFM files are available, the server will still be able to use the CID
+fonts but querying them will take a long time. You should run `mkcfm' again
+whenever a change is made to any of the CID-keyed fonts, or when the CID-
+keyed fonts are copied to a machine with a different architecture.
+
+2.2.4 Setting the server's font path
+
+The list of directories where the server looks for fonts is known as the font
+path. Informing the server of the existence of a new font directory consists
+of putting it on the font path.
+
+The font path is an ordered list; if a client's request matches multiple
+fonts, the first one in the font path is the one that gets used. When match-
+ing fonts, the server makes two passes over the font path: during the first
+pass, it searches for an exact match; during the second, it searches for
+fonts suitable for scaling.
+
+For best results, scalable fonts should appear in the font path before the
+bitmap fonts; this way, the server will prefer bitmap fonts to scalable fonts
+when an exact match is possible, but will avoid scaling bitmap fonts when a
+scalable font can be used. (The `:unscaled' hack, while still supported,
+should no longer be necessary in X11R6.9.)
+
+You may check the font path of the running server by typing the command
+
+ $ xset q
+
+2.2.4.1 Temporary modification of the font path
+
+The `xset' utility may be used to modify the font path for the current ses-
+sion. The font path is set with the command xset fp; a new element is added
+to the front with xset +fp, and added to the end with xset fp+. For example,
+
+ $ xset +fp /usr/local/fonts/Type1
+ $ xset fp+ /usr/local/fonts/bitmap
+
+Conversely, an element may be removed from the front of the font path with
+`xset -fp', and removed from the end with `xset fp-'. You may reset the font
+path to its default value with `xset fp default'.
+
+For more information, please consult the xset(1) manual page.
+
+2.2.4.2 Permanent modification of the font path
+
+The default font path (the one used just after server startup or after `xset
+fp default') is specified in the X server's `xorg.conf' file. It is computed
+by appending all the directories mentioned in the `FontPath' entries of the
+`Files' section in the order in which they appear.
+
+ FontPath "/usr/local/fonts/Type1"
+ ...
+ FontPath "/usr/local/fonts/bitmap"
+
+For more information, please consult the xorg.conf(5) manual page.
+
+2.2.5 Troubleshooting
+
+If you seem to be unable to use some of the fonts you have installed, the
+first thing to check is that the `fonts.dir' files are correct and that they
+are readable by the server (the X server usually runs as root, beware of NFS-
+mounted font directories). If this doesn't help, it is quite possible that
+you are trying to use a font in a format that is not supported by your
+server.
+
+X11R6.9 supports the BDF, PCF, SNF, Type 1, TrueType, OpenType and CIDFont
+font formats. However, not all X11R6.9 servers come with all the font back-
+ends configured in.
+
+On most platforms, the X11R6.9 servers are modular: the font backends are
+included in modules that are loaded at runtime. The modules to be loaded are
+specified in the `xorg.conf' file using the `Load' directive:
+
+ Load "type1"
+
+If you have trouble installing fonts in a specific format, you may want to
+check the server's log file in order to see whether the relevant modules are
+properly loaded. The list of font modules distributed with X11R6.9 is as
+follows:
+
+ o "bitmap": bitmap fonts (`*.bdf', `*.pcf' and `*.snf');
+
+ o "freetype": TrueType fonts (`*.ttf' and `*.ttc'), OpenType fonts
+ (`*.otf' and `*.otc') and Type 1 fonts (`*.pfa' and `*.pfb');
+
+ o "type1": alternate Type 1 backend (`*.pfa' and `*.pfb') and CIDFont
+ backend;
+
+ o "xtt": alternate TrueType backend (`*.ttf' and `*.ttc').
+
+Please note that the argument of the `Load' directive is case-sensitive.
+
+3. Fonts included with X11R6.9
+
+3.1 Standard bitmap fonts
+
+The Sample Implementation of X11 (SI) comes with a large number of bitmap
+fonts, including the `fixed' family, and bitmap versions of Courier, Times,
+Helvetica and some members of the Lucida family. In the SI, these fonts are
+provided in the ISO 8859-1 encoding (ISO Latin Western-European).
+
+In X11R6.9, a number of these fonts are provided in Unicode-encoded font
+files instead. At build time, these fonts are split into font files encoded
+according to legacy encodings, a process which allows us to provide the stan-
+dard fonts in a number of regional encodings with no duplication of work.
+
+For example, the font file
+
+ /usr/X11R6/lib/X11/fonts/misc/6x13.bdf
+
+with XLFD
+
+ -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1
+
+is a Unicode-encoded version of the standard `fixed' font with added support
+for the Latin, Greek, Cyrillic, Georgian, Armenian, IPA and other scripts
+plus numerous technical symbols. It contains over 2800 glyphs, covering all
+characters of ISO 8859 parts 1-5, 7-10, 13-15, as well as all European IBM
+and Microsoft code pages, KOI8, WGL4, and the repertoires of many other char-
+acter sets.
+
+This font is used at build time for generating the font files
+
+ 6x13-ISO8859-1.bdf
+ 6x13-ISO8859-2.bdf
+ ...
+ 6x13-ISO8859-15.bdf
+ 6x13-KOI8-R.bdf
+
+with respective XLFDs
+
+ -misc-fixed-medium-r-normal--13-120-75-75-c-60-iso8859-1
+ ...
+ -misc-fixed-medium-r-normal--13-120-75-75-c-60-iso8859-15
+ -misc-fixed-medium-r-normal--13-120-75-75-c-60-koi8-r
+
+The standard short name `fixed' is normally an alias for
+
+ -misc-fixed-medium-r-normal--13-120-75-75-c-60-iso8859-1
+
+3.2 The ClearlyU Unicode font family
+
+The ClearlyU family of fonts provides a set of 12 pt, 100 dpi proportional
+fonts with many of the glyphs needed for Unicode text. Together, the fonts
+contain approximately 7500 glyphs.
+
+The main ClearlyU font has the XLFD
+
+ -mutt-clearlyu-medium-r-normal--17-120-100-100-p-101-iso10646-1
+
+and resides in the font file
+
+ /usr/X11R6/lib/X11/fonts/misc/cu12.pcf.gz
+
+Additional ClearlyU fonts include
+
+ -mutt-clearlyu alternate glyphs-medium-r-normal--17-120-100-100-p-91-iso10646-1
+ -mutt-clearlyu pua-medium-r-normal--17-120-100-100-p-111-iso10646-1
+ -mutt-clearlyu arabic extra-medium-r-normal--17-120-100-100-p-103-fontspecific-0
+ -mutt-clearlyu ligature-medium-r-normal--17-120-100-100-p-141-fontspecific-0
+
+The Alternate Glyphs font contains additional glyph shapes that are needed
+for certain languages. A second alternate glyph font will be provided later
+for cases where a character has more than one commonly used alternate shape
+(e.g. the Urdu heh).
+
+The PUA font contains extra glyphs that are useful for certain rendering pur-
+poses.
+
+The Arabic Extra font contains the glyphs necessary for characters that don't
+have all of their possible shapes encoded in ISO 10646. The glyphs are
+roughly ordered according to the order of the characters in the ISO 10646
+standard.
+
+The Ligature font contains ligatures for various scripts that may be useful
+for improved presentation of text.
+
+3.3 Standard scalable fonts
+
+X11R6.9 includes all the scalable fonts distributed with X11R6.
+
+3.3.1 Standard Type 1 fonts
+
+The IBM Courier set of fonts cover ISO 8859-1 and ISO 8859-2 as well as Adobe
+Standard Encoding. These fonts have XLFD
+
+ -adobe-courier-medium-*-*--0-0-0-0-m-0-*-*
+
+and reside in the font files
+
+ /usr/X11R6/lib/X11/fonts/Type1/cour*.pfa
+
+The Adobe Utopia set of fonts only cover ISO 8859-1 as well as Adobe Standard
+Encoding. These fonts have XLFD
+
+ -adobe-utopia-*-*-normal--0-0-0-0-p-0-iso8859-1
+
+and reside in the font files
+
+ /usr/X11R6/lib/X11/fonts/Type1/UT*.pfa
+
+Finally, X11R6.9 also comes with Type 1 versions of Bitstream Courier and
+Charter. These fonts have XLFD
+
+ -bitstream-courier-*-*-normal--0-0-0-0-m-0-iso8859-1
+ -bitstream-charter-*-*-normal--0-0-0-0-p-0-iso8859-1
+
+and reside in the font files
+
+ /usr/X11R6/lib/X11/fonts/Type1/c*bt_.pfb
+
+3.4 The Bigelow & Holmes Luxi family
+
+X11R6.9 includes the Luxi family of scalable fonts, in both TrueType and
+Type 1 format. This family consists of the fonts Luxi Serif, with XLFD
+
+ -b&h-luxi serif-medium-*-normal--*-*-*-*-p-*-*-*
+
+Luxi Sans, with XLFD
+
+ -b&h-luxi sans-medium-*-normal--*-*-*-*-p-*-*-*
+
+and Luxi Mono, with XLFD
+
+ -b&h-luxi mono-medium-*-normal--*-*-*-*-m-*-*-*
+
+Each of these fonts comes Roman, oblique, bold and bold oblique variants The
+TrueType version have glyphs covering the basic ASCII Unicode range, the
+Latin 1 range, as well as the Extended Latin range and some additional punc-
+tuation characters. In particular, these fonts include all the glyphs needed
+for ISO 8859 parts 1, 2, 3, 4, 9, 13 and 15, as well as all the glyphs in the
+Adobe Standard encoding and the Windows 3.1 character set.
+
+The glyph coverage of the Type 1 versions is somewhat reduced, and only cov-
+ers ISO 8859 parts 1, 2 and 15 as well as the Adobe Standard encoding.
+
+The Luxi fonts are original designs by Kris Holmes and Charles Bigelow. Luxi
+fonts include seriffed, sans serif, and monospaced styles, in roman and
+oblique, and normal and bold weights. The fonts share stem weight, x-height,
+capital height, ascent and descent, for graphical harmony.
+
+The character width metrics of Luxi roman and bold fonts match those of core
+fonts bundled with popular operating and window systems.
+
+The license terms for the Luxi fonts are included in the file `COPYRIGHT.BH',
+as well as in the License document.
+
+Charles Bigelow and Kris Holmes from Bigelow and Holmes Inc. developed the
+Luxi typeface designs in Ikarus digital format.
+
+URW++ Design and Development GmbH converted the Ikarus format fonts to True-
+Type and Type1 font programs and implemented the grid-fitting "hints" and
+kerning tables in the Luxi fonts.
+
+For more information, please contact <design@bigelowandholmes.com> or
+<info@urwpp.de>, or consult the URW++ web site <URL:http://www.urwpp.de>.
+
+An earlier version of the Luxi fonts was made available under the name
+Lucidux. This name should no longer be used due to trademark uncertainties,
+and all traces of the Lucidux name have been removed from X11R6.9.
+
+4. More about core fonts
+
+This section describes X11R6.9-specific enhancements to the core X11 fonts
+system.
+
+4.1 Core fonts and internationalisation
+
+The scalable font backends (Type 1 and TrueType) can automatically re-encode
+fonts to the encoding specified in the XLFD in `fonts.dir'. For example, a
+`fonts.dir' file can contain entries for the Type 1 Courier font such as
+
+ cour.pfa -adobe-courier-medium-r-normal--0-0-0-0-m-0-iso8859-1
+ cour.pfa -adobe-courier-medium-r-normal--0-0-0-0-m-0-iso8859-2
+
+which will lead to the font being recoded to ISO 8859-1 and ISO 8859-2
+respectively.
+
+4.1.1 The fontenc layer
+
+Two of the scalable backends (Type 1 and the FreeType TrueType backend) use a
+common fontenc layer for font re-encoding. This allows these backends to
+share their encoding data, and allows simple configuration of new locales
+independently of font type.
+
+Please note: the X-TrueType (X-TT) backend is not included in X11R6.9. That
+functionality has been merged into the FreeType backend.>
+
+In the fontenc layer, an encoding is defined by a name (such as iso8859-1),
+possibly a number of aliases (alternate names), and an ordered collection of
+mappings. A mapping defines the way the encoding can be mapped into one of
+the target encodings known to fontenc; currently, these consist of Unicode,
+Adobe glyph names, and arbitrary TrueType ``cmap''s.
+
+A number of encodings are hardwired into fontenc, and are therefore always
+available; the hardcoded encodings cannot easily be redefined. These
+include:
+
+ o iso10646-1: Unicode;
+
+ o iso8859-1: ISO Latin-1 (Western Europe);
+
+ o iso8859-2: ISO Latin-2 (Eastern Europe);
+
+ o iso8859-3: ISO Latin-3 (Southern Europe);
+
+ o iso8859-4: ISO Latin-4 (Northern Europe);
+
+ o iso8859-5: ISO Cyrillic;
+
+ o iso8859-6: ISO Arabic;
+
+ o iso8859-7: ISO Greek;
+
+ o iso8859-8: ISO Hebrew;
+
+ o iso8859-9: ISO Latin-5 (Turkish);
+
+ o iso8859-10: ISO Latin-6 (Nordic);
+
+ o iso8859-15: ISO Latin-9, or Latin-0 (Revised Western-European);
+
+ o koi8-r: KOI8 Russian;
+
+ o koi8-u: KOI8 Ukrainian (see RFC 2319);
+
+ o koi8-ru: KOI8 Russian/Ukrainian;
+
+ o koi8-uni: KOI8 ``Unified'' (Russian, Ukrainian, and Byelorussian);
+
+ o koi8-e: KOI8 ``European,'' ISO-IR-111, or ECMA-Cyrillic;
+
+ o microsoft-symbol and apple-roman: these are only likely to be useful
+ with TrueType symbol fonts.
+
+Additional encodings can be added by defining encoding files. When a font
+encoding is requested that the fontenc layer doesn't know about, the backend
+checks the directory in which the font file resides (not necessarily the
+directory with fonts.dir!) for a file named `encodings.dir'. If found, this
+file is scanned for the requested encoding, and the relevant encoding defini-
+tion file is read in. The `mkfontdir' utility, when invoked with the `-e'
+option followed by the name of a directory containing encoding files, can be
+used to automatically build `encodings.dir' files. Please see the mkfont-
+dir(1) manual page for more details.
+
+A number of encoding files for common encodings are included with X11R6.9.
+Information on writing new encoding files can be found in Format of encodings
+directory files (section 4.1.3, page 1) and Format of encoding files (section
+4.1.4, page 1) later in this document.
+
+4.1.2 Backend-specific notes about fontenc
+
+4.1.2.1 The FreeType backend
+
+For TrueType and OpenType fonts, the FreeType backend scans the mappings in
+order. Mappings with a target of PostScript are ignored; mappings with a
+TrueType or Unicode target are checked against all the cmaps in the file.
+The first applicable mapping is used.
+
+For Type 1 fonts, the FreeType backend first searches for a mapping with a
+target of PostScript. If one is found, it is used. Otherwise, the backend
+searches for a mapping with target Unicode, which is then composed with a
+built-in table mapping codes to glyph names. Note that this table only cov-
+ers part of the Unicode code points that have been assigned names by Adobe.
+
+Specifying an encoding value of adobe-fontspecific for a Type 1 font disables
+the encoding mechanism. This is useful with symbol and incorrectly encoded
+fonts (see Incorrectly encoded fonts (section 4.1.6, page 1) below).
+
+If a suitable mapping is not found, the FreeType backend defaults to
+ISO 8859-1.
+
+4.1.2.2 Type 1
+
+The Type 1 backend behaves similarly to the FreeType backend with Type 1
+fonts, except that it limits all encodings to 8-bit codes.
+
+4.1.3 Format of encoding directory files
+
+In order to use a font in an encoding that the font backend does not know
+about, you need to have an `encodings.dir' file either in the same directory
+as the font file used or in a system-wide location
+(`/usr/X11R6/lib/X11/fonts/encodings/' by default).
+
+The `encodings.dir' file has a similar format to `fonts.dir'. Its first line
+specifies the number of encodings, while every successive line has two
+columns, the name of the encoding, and the name of the encoding file; this
+can be relative to the current directory, or absolute. Every encoding name
+should agree with the encoding name defined in the encoding file. For exam-
+ple,
+
+ 3
+ mulearabic-0 /usr/X11R6/lib/X11/fonts/encodings/mulearabic-0.enc
+ mulearabic-1 /usr/X11R6/lib/X11/fonts/encodings/mulearabic-1.enc
+ mulearabic-2 /usr/X11R6/lib/X11/fonts/encodings/mulearabic-2.enc
+
+The name of an encoding must be specified in the encoding file's `STARTENCOD-
+ING' or `ALIAS' line. It is not enough to create an `encodings.dir' entry.
+
+If your platform supports it (it probably does), encoding files may be com-
+pressed or gzipped.
+
+The `encoding.dir' files are best maintained by the `mkfontdir' utility.
+Please see the mkfontdir(1) manual page for more information.
+
+4.1.4 Format of encoding files
+
+The encoding files are ``free form,'' i.e. any string of whitespace is equiv-
+alent to a single space. Keywords are parsed in a non-case-sensitive manner,
+meaning that `size', `SIZE', and `SiZE' all parse as the same keyword; on the
+other hand, case is significant in glyph names.
+
+Numbers can be written in decimal, as in `256', in hexadecimal, as in
+`0x100', or in octal, as in `0400'.
+
+Comments are introduced by a hash sign `#'. A `#' may appear at any point in
+a line, and all characters following the `#' are ignored, up to the end of
+the line.
+
+The encoding file starts with the definition of the name of the encoding, and
+possibly its alternate names (aliases):
+
+ STARTENCODING mulearabic-0
+ ALIAS arabic-0
+
+The name of the encoding and its aliases should be suitable for use in an
+XLFD font name, and therefore contain exactly one dash `-'.
+
+The encoding file may then optionally declare the size of the encoding. For
+a linear encoding (such as ISO 8859-1), the SIZE line specifies the maximum
+code plus one:
+
+ SIZE 0x2B
+
+For a matrix encoding, it should specify two numbers. The first is the num-
+ber of the last row plus one, the other, the highest column number plus one.
+In the case of `jisx0208.1990-0' (JIS X 0208(1990), double-byte encoding,
+high bit clear), it should be
+
+ SIZE 0x75 0x80
+
+In the case of a matrix encoding, a `FIRSTINDEX' line may be included to
+specify the minimum glyph index in an encoding. The keyword `FIRSTINDEX' is
+followed by two integers, the minimum row number followed by the minimum col-
+umn number:
+
+ FIRSTINDEX 0x20 0x20
+
+In the case of a linear encoding, a `FIRSTINDEX' line is not very useful. If
+for some reason however you chose to include on, it should be followed by a
+single integer.
+
+Note that in most font backends inclusion of a `FIRSTINDEX' line has the side
+effect of disabling default glyph generation, and this keyword should there-
+fore be avoided unless absolutely necessary.
+
+Codes outside the region defined by the `SIZE' and `FIRSTINDEX' lines are
+understood to be undefined. Encodings default to linear encoding with a size
+of 256 (0x100). This means that you must declare the size of all 16 bit
+encodings.
+
+What follows is one or more mapping sections. A mapping section starts with
+a `STARTMAPPING' line stating the target of the mapping. The target may be
+one of:
+
+ o Unicode (ISO 10646):
+
+ STARTMAPPING unicode
+
+ o a given TrueType ``cmap'':
+
+ STARTMAPPING cmap 3 1
+
+ o PostScript glyph names:
+
+ STARTMAPPING postscript
+
+Every line in a mapping section maps one from the encoding being defined to
+the target of the mapping. In mappings with a Unicode or TrueType mapping,
+codes are mapped to codes:
+
+ 0x21 0x0660
+ 0x22 0x0661
+ ...
+
+As an abbreviation, it is possible to map a contiguous range of codes in a
+single line. A line consisting of three integers
+
+ <it/start/ <it/end/ <it/target/
+
+is an abbreviation for the range of lines
+
+ start target
+
+ start+1 target+1
+
+ ...
+
+ end target+end-start
+
+For example, the line
+
+ 0x2121 0x215F 0x8140
+
+is an abbreviation for
+
+ 0x2121 0x8140
+ 0x2122 0x8141
+ ...
+ 0x215F 0x817E
+
+Codes not listed are assumed to map through the identity (i.e. to the same
+numerical value). In order to override this default mapping, you may specify
+a range of codes to be undefined by using an `UNDEFINE' line:
+
+ UNDEFINE 0x00 0x2A
+
+or, for a single code,
+
+ UNDEFINE 0x1234
+
+PostScript mappings are different. Every line in a PostScript mapping maps a
+code to a glyph name
+
+ 0x41 A
+ 0x42 B
+ ...
+
+and codes not explicitly listed are undefined.
+
+A mapping section ends with an ENDMAPPING line
+
+ ENDMAPPING
+
+After all the mappings have been defined, the file ends with an ENDENCODING
+line
+
+ ENDENCODING
+
+In order to make future extensions to the format possible, lines starting
+with an unknown keyword are silently ignored, as are mapping sections with an
+unknown target.
+
+4.1.5 Using symbol fonts
+
+Type 1 symbol fonts should be installed using the adobe-fontspecific encod-
+ing.
+
+In an ideal world, all TrueType symbol fonts would be installed using one of
+the microsoft-symbol and apple-roman encodings. A number of symbol fonts,
+however, are not marked as such; such fonts should be installed using
+microsoft-cp1252, or, for older fonts, microsoft-win3.1.
+
+In order to guarantee consistent results (especially between Type 1 and True-
+Type versions of the same font), it is possible to define a special encoding
+for a given font. This has already been done for the ZapfDingbats font; see
+the file `encodings/adobe-dingbats.enc'.
+
+4.1.6 Hints about using badly encoded fonts
+
+A number of text fonts are incorrectly encoded. Incorrect encoding is some-
+times done by design, in order to make a font for an exotic script appear
+like an ordinary Western text font on systems which are not easily extended
+with new locale data. It is often the result of the font designer's laziness
+or incompetence; for some reason, most people seem to find it easier to
+invent idiosyncratic glyph names rather than follow the Adobe glyph list.
+
+There are two ways of dealing with such fonts: using them with the encoding
+they were designed for, and creating an ad hoc encoding file.
+
+4.1.6.1 Using fonts with the designer's encoding
+
+In the case of Type 1 fonts, the font designer can specify a default encod-
+ing; this encoding is requested by using the `adobe-fontspecific' encoding in
+the XLFD name. Sometimes, the font designer omitted to specify a reasonable
+default encoding, in which case you should experiment with `adobe-standard',
+`iso8859-1', `microsoft-cp1252', and `microsoft-win3.1'. (The encoding
+`microsoft-symbol' doesn't make sense for Type 1 fonts).
+
+TrueType fonts do not have a default encoding. However, most TrueType fonts
+are designed with either Microsoft or Apple platforms in mind, so one of
+`microsoft-symbol', `microsoft-cp1252', `microsoft-win3.1', or `apple-roman'
+should yield reasonable results.
+
+4.1.6.2 Specifying an ad hoc encoding file
+
+It is always possible to define an encoding file to put the glyphs in a font
+in any desired order. Again, see the `encodings/adobe-dingbats.enc' file to
+see how this is done.
+
+4.1.6.3 Specifying font aliases
+
+By following the directions above, you will find yourself with a number of
+fonts with unusual names --- with encodings such as `adobe-fontspecific',
+`microsoft-win3.1' etc. In order to use these fonts with standard applica-
+tions, it may be useful to remap them to their proper names.
+
+This is done by writing a `fonts.alias' file. The format of this file is very
+simple: it consists of a series of lines each mapping an alias name to a font
+name. A `fonts.alias' file might look as follows:
+
+ "-ogonki-alamakota-medium-r-normal--0-0-0-0-p-0-iso8859-2" \
+ "-ogonki-alamakota-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific"
+
+(both XLFD names on a single line). The syntax of the `fonts.alias' file is
+more precisely described in the mkfontdir(1) manual page.
+
+4.2 Additional notes about scalable core fonts
+
+The FreeType (libfreetype-xtt2) backend (module `freetype', formerly known as
+xfsft) is able to deal with both TrueType and Type 1 fonts. This puts it in
+conflict with the X-TT and Type 1 backends respectively.
+
+If both the FreeType and the Type 1 backends are loaded, the FreeType backend
+will be used for Type 1 fonts. If both the FreeType and X-TT backends are
+loaded, X-TT will be used for TrueType fonts.
+
+4.2.1 About the FreeType backend
+
+The FreeType (libfreetype-xtt2) backend (formerly xfsft) is a backend based
+on version 2 of the FreeType library (see the FreeType web site
+<URL:http://www.freetype.org/>) and has the X-TT functionalities for CJKV
+support provided by the After X-TT Project (see the After X-TT Project web
+site <URL:http://x-tt.sourceforge.jp/>). The FreeType module has support for
+the ``fontenc'' style of internationalisation (see The fontenc layer (section
+4.1.1, page 1)). This backend supports TrueType font files (`*.ttf'), Open-
+Type font files (`*.otf'), TrueType Collections (`*.ttc'), OpenType Collec-
+tions (`*.otc') and Type 1 font files (`*.pfa' and `*.pfb').
+
+In order to access the faces in a TrueType Collection file, the face number
+must be specified in the fonts.dir file before the filename, within a pair of
+colons, or by setting the 'fn' TTCap option. For example,
+
+ :1:mincho.ttc -misc-pmincho-medium-r-normal--0-0-0-0-p-0-jisx0208.1990-0
+
+refers to face 1 in the `mincho.ttc' TrueType Collection file.
+
+The new FreeType backend supports the extended `fonts.dir' syntax introduced
+by X-TrueType with a number of options, collectively known as `TTCap'. A
+`TTCap' entry follows the general syntax
+
+ option=value:
+
+and should be specified before the filename. The new FreeType almost per-
+fectly supports TTCap options that are compatible with X-TT 1.4. The Auto-
+matic Italic (`ai'), Double Strike (`ds') and Bounding box Width (`bw')
+options are indispensable in CJKV. For example,
+
+ mincho.ttc -misc-mincho-medium-r-normal--0-0-0-0-c-0-jisx0208.1990-0
+ ds=y:mincho.ttc -misc-mincho-bold-r-normal--0-0-0-0-c-0-jisx0208.1990-0
+ ai=0.2:mincho.ttc -misc-mincho-medium-i-normal--0-0-0-0-c-0-jisx0208.1990-0
+ ds=y:ai=0.2:mincho.ttc -misc-mincho-bold-i-normal--0-0-0-0-c-0-jisx0208.1990-0
+ bw=0.5:mincho.ttc -misc-mincho-medium-r-normal--0-0-0-0-c-0-jisx0201.1976-0
+ bw=0.5:ds=y:mincho.ttc -misc-mincho-bold-r-normal--0-0-0-0-c-0-jisx0201.1976-0
+ bw=0.5:ai=0.2:mincho.ttc -misc-mincho-medium-i-normal--0-0-0-0-c-0-jisx0201.1976-0
+ bw=0.5:ds=y:ai=0.2:mincho.ttc -misc-mincho-bold-i-normal--0-0-0-0-c-0-jisx0201.1976-0
+
+setup the complete combination of jisx0208 and jisx0201 using mincho.ttc
+only. More information on the TTCap syntax is found on the After X-TT Pro-
+ject page <URL:http://x-tt.sourceforge.jp/>.
+
+The FreeType backend uses the fontenc layer in order to support recoding of
+fonts; this was described in The fontenc layer (section 4.1.1, page 1) and
+especially FreeType-specific notes about fontenc (section 4.1.2.1, page 1)
+earlier in this document.
+
+4.2.2 About the X-TrueType TrueType backend
+
+The `X-TrueType' backend is a backend based on version 1 of the FreeType
+library. X-TrueType doesn't use the `fontenc' layer for managing font encod-
+ings, but instead uses its own database of encodings.
+
+Since the functionalities for CJKV support introduced by X-TT have been
+merged into the new FreeType backend, the X-TT backend will be removed from
+X11R6.9's tree near the future. Therefore, the use of FreeType backend is
+preferred over the X-TT backend.
+
+General information on X-TrueType may be found at the After X-TT Project page
+<URL:http://x-tt.sourceforge.jp/>.
+
+4.2.3 Delayed glyph rasterisation
+
+When loading a proportional fonts which contain a huge number of glyphs, the
+old FreeType delayed glyph rasterisation until the time at which the glyph
+was first used. The new FreeType (libfreetype-xtt2) has an improved `very
+lazy' metric calculation method to speed up the process when loading TrueType
+or OpenType fonts. Although the X-TT module also has this method, the
+"vl=y" TTCap option must be set if you want to use it. This is the default
+method for FreeType when it loads multi-byte fonts. Even if you use a uni-
+code font which has tens of thousands of glyphs, this delay will not be wor-
+risome as long as you use the new FreeType backend -- its `very lazy' method
+is super-fast.
+
+The maximum error of bitmap position using `very lazy' method is 1 pixel, and
+is the same as that of a character-cell spacing. When the X-TT backend is
+used with the `vl=y' option, a chipped bitmap is displayed with certain
+fonts. However, the new FreeType backend has minimal problem with this,
+since it corrects left- and right-side bearings using `italicAngle' in the
+TrueType/OpenType post table, and does automatic correction of bitmap posi-
+tions when rasterisation so that chipped bitmaps are not displayed. Never-
+theless if you don't want to use the `very lazy' method when using multi-
+bytes fonts, set `vl=n' in the TTCap option to disable it:
+
+ vl=n:luxirr.ttf -b&h-Luxi Serif-medium-r-normal--0-0-0-0-p-0-iso10646-1
+
+Of course, both backends also support an optimisation for character-cell
+fonts (fonts with all glyph metrics equal, or terminal fonts). A font with
+an XLFD specifying a character-cell spacing `c', as in
+
+ -misc-mincho-medium-r-normal--0-0-0-0-c-0-jisx0208.1990-0
+
+or
+
+ fs=c:mincho.ttc -misc-mincho-medium-r-normal--0-0-0-0-p-0-jisx0208.1990-0
+
+will not compute the metric for each glyph, but instead trust the font to be
+a character-cell font. You are encouraged to make use of this optimisation
+when useful, but be warned that not all monospaced fonts are character-cell
+fonts.
+
+5. Appendix: background and terminology
+
+5.1 Characters and glyphs
+
+A computer text-processing system inputs keystrokes and outputs glyphs, small
+pictures that are assembled on paper or on a computer screen. Keystrokes and
+glyphs do not, in general, coincide: for example, if the system does generate
+ligatures, then to the sequence of two keystrokes <f><i> will typically cor-
+respond a single glyph. Similarly, if the system shapes Arabic glyphs in a
+vaguely reasonable manner, then multiple different glyphs may correspond to a
+single keystroke.
+
+The complex transformation rules from keystrokes to glyphs are usually fac-
+tored into two simpler transformations, from keystrokes to characters and
+from characters to glyphs. You may want to think of characters as the basic
+unit of text that is stored e.g. in the buffer of your text editor. While
+the definition of a character is intrinsically application-specific, a number
+of standardised collections of characters have been defined.
+
+A coded character set is a set of characters together with a mapping from
+integer codes --- known as codepoints --- to characters. Examples of coded
+character sets include US-ASCII, ISO 8859-1, KOI8-R, and JIS X 0208(1990).
+
+A coded character set need not use 8 bit integers to index characters. Many
+early systems used 6 bit character sets, while 16 bit (or more) character
+sets are necessary for ideographic writing systems.
+
+5.2 Font files, fonts, and XLFD
+
+Traditionally, typographers speak about typefaces and founts. A typeface is
+a particular style or design, such as Times Italic, while a fount is a
+molten-lead incarnation of a given typeface at a given size.
+
+Digital fonts come in font files. A font file contains the information nec-
+essary for generating glyphs of a given typeface, and applications using font
+files may access glyph information in an arbitrary order.
+
+Digital fonts may consist of bitmap data, in which case they are said to be
+bitmap fonts. They may also consist of a mathematical description of glyph
+shapes, in which case they are said to be scalable fonts. Common formats for
+scalable font files are Type 1 (sometimes incorrectly called ATM fonts or
+PostScript fonts), TrueType and OpenType.
+
+The glyph data in a digital font needs to be indexed somehow. How this is
+done depends on the font file format. In the case of Type 1 fonts, glyphs
+are identified by glyph names. In the case of TrueType fonts, glyphs are
+indexed by integers corresponding to one of a number of indexing schemes
+(usually Unicode --- see below).
+
+The X11 core fonts system uses the data in a font file to generate font
+instances, which are collections of glyphs at a given size indexed according
+to a given encoding.
+
+X11 core font instances are usually specified using a notation known as the X
+Logical Font Description (XLFD). An XLFD starts with a dash `-', and con-
+sists of fourteen fields separated by dashes, for example:
+
+ -adobe-courier-medium-r-normal--12-120-75-75-m-70-iso8859-1
+
+Or particular interest are the last two fields `iso8859-1', which specify the
+font instance's encoding.
+
+A scalable font is specified by an XLFD which contains zeroes instead of some
+fields:
+
+ -adobe-courier-medium-r-normal--0-0-0-0-m-0-iso8859-1
+
+X11 font instances may also be specified by short name. Unlike an XLFD, a
+short name has no structure and is simply a conventional name for a font
+instance. Two short names are of particular interest, as the server will not
+start if font instances with these names cannot be opened. These are
+`fixed', which specifies the fallback font to use when the requested font
+cannot be opened, and `cursor', which specifies the set of glyphs to be used
+by the mouse pointer.
+
+Short names are usually implemented as aliases to XLFDs; the standard `fixed'
+and `cursor' aliases are defined in
+
+ /usr/X11R6/lib/X11/font/misc/fonts.alias
+
+5.3 Unicode
+
+Unicode (urlnam <URL:http://www.unicode.org>) is a coded character set with
+the goal of uniquely identifying all characters for all scripts, current and
+historical. While Unicode was explicitly not designed as a glyph encoding
+scheme, it is often possible to use it as such.
+
+Unicode is an open character set, meaning that codepoint assignments may be
+added to Unicode at any time (once specified, though, an assignment can never
+be changed). For this reason, a Unicode font will be sparse, meaning that it
+only defines glyphs for a subset of the character registry of Unicode.
+
+The Unicode standard is defined in parallel with the international standard
+ISO 10646. Assignments in the two standards are always equivalent, and we
+often use the terms Unicode and ISO 10646 interchangeably.
+
+When used in the X11 core fonts system, Unicode-encoded fonts should have the
+last two fields of their XLFD set to `iso10646-1'.
+
+6. References
+
+X11R6.9 comes with extensive documentation in the form of manual pages and
+typeset documents. Before installing fonts, you really should read the font-
+config(3) and mkfontdir(1) manual pages; other manual pages of interest
+include X(7), Xserver(1), xset(1), Xft(3), xlsfonts(1) and showfont(1). In
+addition, you may want to read the X Logical Font Description document, by
+Jim Flowers, which is provided in the file `xc/doc/xlfd.PS.Z'.
+
+The latest released version of the X11R6.9 documentation (including this doc-
+ument and all manual pages) can be found from current X11R6.9 documentation
+<URL:http://wiki.x.org/>.
+
+The comp.fonts FAQ <URL:http://www.netmeg.net/faq/computers/fonts/>, which is
+unfortunately no longer being maintained, contains a wealth of information
+about digital fonts.
+
+Xft and Fontconfig are described on Keith Packard's Fontconfig site
+<URL:http://www.fontconfig.org>.
+
+The xfsft home page <URL:http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/>
+has been superseded by this document, and is now obsolete; you may however
+still find some of the information that it contains useful. Joerg Pommnitz'
+xfsft page <URL:http://www.joerg-pommnitz.de/TrueType/xfsft.html> is the
+canonical source for the `ttmkfdir' utility, which is the ancestor of
+mkfontscale.
+
+The author's software pages <URL:http://www.pps.jussieu.fr/~jch/software/>
+might or might not contain related scribbles and development versions of
+software.
+
+The documentation of X-TrueType is available from the After X-TT Project page
+<URL:http://x-tt.sourceforge.jp/>.
+
+A number of East-Asian CIDFonts are available from O'Reilly's FTP site
+<URL:ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/adobe/>.
+
+While the Unicode consortium site <URL:http://www.unicode.org> may be of
+interest, you are more likely to find what you need in Markus Kuhn's UTF-8
+and Unicode FAQ <URL:http://www.cl.cam.ac.uk/~mgk25/unicode.html>.
+
+The IANA RFC documents, available from a number of sites throughout the
+world, often provide interesting information about character set issues; see
+for example RFC 373.
+
+
+$XdotOrg$
diff --git a/xorg-server/hw/xfree86/doc/README.rapidaccess b/xorg-server/hw/xfree86/doc/README.rapidaccess
new file mode 100644
index 000000000..39f515ee2
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/README.rapidaccess
@@ -0,0 +1,48 @@
+The IBM Rapid Access keyboard have some extra buttons
+on it to launch programs, control a cd-player and so on.
+
+These buttons is not functional when the computer is turned
+on but have to be activated by sending the codes 0xea 0x71
+to it.
+
+I've written the following hack to send codes to the keyboard:
+
+--------------------------------------------------------------
+/* gcc -O2 -s -Wall -osend_to_keyboard send_to_keyboard.c */
+#include <stdlib.h>
+#include <unistd.h>
+#include <sys/io.h>
+
+int main( int argc, char *argv[] )
+{
+ int i;
+
+ ioperm( 0x60, 3, 1 );
+
+ for( i = 1; i < argc; i++ ) {
+ int x = strtol( argv[i], 0, 16 );
+
+ usleep( 300 );
+ outb( x, 0x60 );
+ }
+
+ return 0;
+}
+--------------------------------------------------------------
+
+As root you can then call this program (in your boot scripts)
+as "send_to_keyboard ea 71" to turn on the extra buttons.
+
+It's not a good idea to run several instances of this program
+at the same time. It is a hack but it works. If you try to
+send other codes to the keyboard it probably will lock up.
+For other codes see:
+
+http://www.win.tue.nl/~aeb/linux/kbd/scancodes-2.html#ss2.22
+
+--
+Dennis Björklund <db@zigo.dhs.org>
+
+
+
+$XFree86$
diff --git a/xorg-server/hw/xfree86/doc/devel/DebuggingHints b/xorg-server/hw/xfree86/doc/devel/DebuggingHints
new file mode 100644
index 000000000..300fe4813
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/devel/DebuggingHints
@@ -0,0 +1,192 @@
+
+ Xserver Debugging
+ =================
+
+This file is intended to collect helpful hints on Xserver debugging.
+I merely outline my experiences here. Somebody else might have better
+methods on doing it. This person is therefore invited to share this
+experience with the rest of the world by adding it here.
+
+Paul Flinders has made some patches to gdb to add support for loadable
+modules. This version of gdb is currently available as binary for
+Linux/x86 on Paul's web site:
+
+ www.dawa.demon.co.uk/xfree-gdb
+
+This web-site also contains the patches to gdb 4.18 so you may port it
+to other platforms.
+
+It loads the module symbols and supports all gdb features like
+breakpointing, disassembling and single stepping. It also shows the
+exact location of a signal 11. Paul has fixed the code so that all of
+this is working even if using modules compiled without -g. You can
+find his latest version on his web site.
+
+If no module aware gdb is available the following hints might help:
+
+1. Use remote login. This can be done thru a network connection or
+ simply by connecting a serial console. This enables you to watch
+ the Xservers output while running set breakpoints with gdb etc.
+ Don't even try to run the Xserver from a system console. Whenever
+ something happens gdb waits for input. However the Xserver has
+ locked the system console including the keyboard, therefore you'll
+ never be able to send any input to gdb. Even if your process
+ doesn't crash or you haven't set any breakpoints a vt switch can be
+ hazardous: When doing vt switching a signal is sent; unless you did
+
+ gdb> handle SIGUSR1 nostop
+
+ gdb waits for you to continue the program which cannot happen as
+ you don't have access to gdb's console.
+
+2. You can compile any source file with debugging symbols to obtain
+ more information about where an error occurred. Simply go to the
+ directory which holds the corresponding object file and do:
+
+ # rm <file>.o
+ # xc/config/util/makeg.sh <file>.o
+
+ After relinking the server or module gdb is able to obtain the
+ necessary debugging information and will show the exact line in the
+ source where the error ccurred. See also:
+ xc/config/util/makeg.man.
+
+3. In some cases it might be useful to have the assembler output of a
+ compiled source file. This can be obtained by doing:
+
+ # make <file>.s
+
+ or
+
+ # xc/config/util/makeg.sh <file>.s
+
+ Make will use exactly the same rules it uses for building *.o files.
+
+4. In some cases it might be useful to set breakpoints in modules. If
+ no module aware gdb is available you should add a call to one of
+ the three dummy breakpoint functions
+
+ xf86Break1(), xf86Break2() and xf86Break3()
+
+ to the source file and recompile the module. You now just have to
+ set a breakpoint onto the appropriate dummy functions. These
+ functions are located in the core part of the server and therefore
+ will be available any time.
+
+5. Without module support gdb is not able to print the function where
+ an error occurred in a module.
+
+ If you get a line like:
+
+ (gdb) bt
+ #0 0x823b4f5 in ?? ()
+ ....
+
+ You may obtain the function the address belongs to by calling
+ LoaderPrintSymbol():
+
+ (gdb) call LoaderPrintSymbol(0x823b4f5)
+
+ The symbol returned might not always be the name of the function
+ which contains the address. In case of static functions the symbol
+ is not known to the loader. However LoaderPrintSymbol() will print
+ the nearest known function and the offset from its start. You may
+ easily find the exact location of the address if you do:
+
+ # objdump --disassemble <file>.o
+
+ <file>.o is the name of the object file containing the symbol printed.
+
+6. Locating static symbols in modules is simpler if the module is a
+ single object file instead of a library. Such a object file can
+ easily be build from a library: # mkdir tmp # cd tmp; ar x
+ module-path/<libname>.a # ld -r *.o -o module-path/<name>.o
+
+ When calling LoaderPrintSymbol() the closes public symbol will be
+ printed together with the offset from the symbol's address. If a
+ static symbol comes before the first public symbol in a module The
+ following trick may help:
+
+ create a file 1-<name>.c in tmp/
+ containing:
+ void Dummy-<name>() {}
+
+ Compile it:
+
+ # gcc -c 1-<name>.c
+
+ and do the link step above.
+
+ This way Dummy-<name>() will be the first public function in the
+ module. All addresses in static function can now be printed
+ relatively to this address if no other public function comes before
+ this static one.
+
+7. In some situations it is quite helpful to add debugging symbols to
+ the binary. This can be done per object file. Simply remove the
+ object file and do
+
+ # makeg
+
+ When looking for a bug in a module these debugging infos can be
+ very helpful: Calling LoaderPrintSymbol() as described above will
+ return a function and an offset giving the exact location of the
+ address with respect to this function entry point. When
+ disassembling an object file with debugging symbols: # objdump -d
+ -l <file>.o one will receive a disassembled output containing line
+ number information. Thus one can locate the exact line of code
+ where the error occurred.
+
+8. To quickly trace the value of a variable declared in a module three
+ dummy variables have been added to the core part:
+
+ CARD32 xf86DummyVar1;
+ CARD32 xf86DummyVar2;
+ CARD32 xf86DummyVar3;
+
+ The variable can be assigned to one of them. One can then use gdb
+ to return the value of this variable:
+
+ gdb> p /x xf86DummyVar1
+
+9. Sometimes it might be useful to check how the preprocessor replaced
+ symbols. One can obtain a preprocessed version of the source file
+ by doing:
+
+ make <filename>.i
+
+ This will generate a preprocessed source in <filename>.i.
+
+10. xfree() can catch if one tries to free a memory range twice. You
+ will get the message:
+
+ Xalloc error: range already freed in Xrealloc() :-(
+
+ To find the location from which xfree() was called one can
+ breakpoint on XfreeTrap(). The backtrace should show the origin of the
+ call this call.
+
+11. To access mapped physical memory the following functions might be
+ useful.
+
+ These may be used to access physical memory that was mapped using
+ the flags VIDMEM_FRAMEBUFFER or VIDMEM_MMIO32:
+
+ CARD8 xf86PeekFb8(CARD8 *p);
+ CARD16 xf86PeekFb16(CARD16 *p);
+ CARD32 xf86PeekFb32(CARD32 *p);
+ void xf86PokeFb8(CARD8 *p, CARD8 v);
+ void xf86PokeFb16(CARD16 *p, CARD16 v);
+ void xf86PokeFb32(CARD16 *p, CARD32 v);
+
+ Physical memory which was mapped by setting VIDMEM_MMIO should be
+ accessed using the following. Here the base address to which the
+ memory is mapped and the offset are required separately.
+
+ CARD8 xf86PeekMmio8(pointer Base, unsigned long Offset);
+ CARD16 xf86PeekMmio16(pointer Base, unsigned long Offset);
+ CARD32 xf86PeekMmio32(pointer Base, unsigned long Offset);
+ void xf86PokeMmio8(pointer Base, unsigned long Offset, CARD8 v);
+ void xf86PokeMmio16(pointer Base, unsigned long Offset, CARD16 v);
+ void xf86PokeMmio32(pointer Base, unsigned long Offset, CARD32 v);
+
diff --git a/xorg-server/hw/xfree86/doc/devel/Domain.note b/xorg-server/hw/xfree86/doc/devel/Domain.note
new file mode 100644
index 000000000..ce0812b22
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/devel/Domain.note
@@ -0,0 +1,159 @@
+The purpose of the changes described here is to implement a more general
+framework for multi-head on systems with more than one host-to-PCI bridge.
+The changes also implement a basic port of XFree86 to SPARC Solaris.
+
+These changes are derived from David S. Miller's submission #4653 to the
+patch list. David Andrew of Sun Microsystems was also kind enough to
+arrange for a hardware loan for development of these changes.
+
+These changes are known to work on several SPARC SunOS and UltraSPARC
+Linux configurations. Linux kernel work is in progress to port these
+changes to Linux/PowerPC.
+
+Several loose ends still need to be addressed before these changes can be
+considered stable. The bulk of this note is devoted to enumerating what
+remains to be done, along with other notes, broken down into various broad
+categories.
+
+SPARC SunOS (aka Solaris)
+-------------------------
+- An overview of this XFree86 port is available in README.Solaris.
+- The keyboard map code in hw/xfree86/os-support/sunos/sun_kbdEv.c needs
+ to be extended to handle more than only the sun5 keyboard I targeted it
+ for. Even for the sun5, the map is incomplete as several keys are not
+ mapped. What is there is just barely usable.
+- On exit, the server will zero out /dev/fb, but that might not be the
+ right thing to do for all primary adapters. This does however
+ appear to emulate the behaviour of Sun's commercial servers. It also
+ eliminates the need for output drivers to save and restore video memory
+ contents. (They still need to save/restore the mode timing however.)
+ This also chimes into a long-standing XFree86 policy to not save/restore
+ video memory contents if the mode on entry is found to be non-VGA, a
+ policy several existing drivers comply with.
+- The SBUS drivers (sunbw2, suncg14, suncg3, suncg6, sunffb, sunleo and
+ suntcx), the common layer's SBUS code and the fbdev driver have all
+ only been compile tested. There are likely to be Linux'isms within
+ them that remain to be dealt with.
+- It still needs to be verified whether or not this work adversely
+ affected support for ix86 Solaris.
+
+UltraSPARC Linux
+----------------
+- Although this code can be compiled using any Linux/SPARC64 kernel, it
+ can only run successfully using 2.4.12 or later.
+- I haven't had time to sufficiently dig into XKB to properly configure it
+ for sun5 keyboards. Given XFree86 on Linux/SPARC has been around for a
+ while, it's likely someone has already done this, and I'd appreciate
+ receiving a copy of a working XF86Config input section.
+
+PowerPC Linux
+-------------
+- As mentioned above, kernel work is in progress to port this PCI scheme
+ to Linux/PowerPC.
+- Aside from kernel work, the inX() and outX() definitions in compiler.h
+ will need to be changed to do something akin to their SPARC definitions,
+ i.e. consider their port argument to be a virtual address.
+
+Other Linux ports to multi-domain architectures
+-----------------------------------------------
+- Comments in os-support/bus/linuxPci.c document the kernel interface
+ required to port these changes. In short, Linux ports, such as Alpha
+ and mips, should follow SPARC and PowerPC's lead in providing support to
+ mmap() PCI devices through their /proc/bus/pci pseudo-files and to treat
+ such requests for host bridges as requests to mmap() space provided by
+ these bridges.
+
+Other OS's
+----------
+- In the right hands, either linuxPci.c or sparcPci.c can be used as a
+ guide for what would need to be done to port this scheme to other OS's.
+ Perhaps the largest difference between the two (in terms of interface to
+ the common layer) is that the SunOS port includes internally generated
+ domain numbers in PCITAG's, whereas the Linux port doesn't need to. The
+ remainder of the PCI code (which is OS-independent) can handle either
+ scheme.
+- Required entry points are xf86GetPciDomain(), xf86MapDomainMemory(),
+ xf86MapDomainIO() and xf86ReadDomainMemory(). Replacements for
+ xf86BusAccWindowsFromOS(), xf86PciBusAccWindowsFromOS() and
+ xf86AccResFromOS() might also be required.
+- Development of these changes has detected the fact that the XFree86 port
+ to the PowerMax OS is broken, and has been for some time, i.e. since
+ shortly after its introduction, back in the 3.9* days.
+
+SPARC PCI (OS-independent)
+--------------------------
+- The "Simba" PCI-to-PCI bridge used in SPARC's does not implement VGA
+ routing, as defined in the PCI specs. Fortunately, OpenPROM seems to
+ always route VGA resources to the bus with PCI connectors, but this also
+ causes the common layer to not mark any PCI adapter as primary.
+
+Multiple PCI domains (architecture- and OS-independent)
+-------------------------------------------------------
+- This implementation assumes every host-to-PCI bridge provides access to
+ a separate PCI domain. Each such domain provides three different
+ "address" spaces: PCI configuration, I/O and memory. The
+ implementation can also deal with situations where more than one PCI
+ domain share (different subsets of) the same PCI configuration space. I
+ have unconfirmed information that suggests it might be necessary to also
+ allow the sharing of PCI memory spaces.
+- This implementation also assumes the CPU's physical address space
+ includes the entirety of each domain's I/O and memory spaces. I know
+ this'll need to be changed to deal with the so-called UniNorth bridge,
+ found on PowerPC's, which allows access to only a subset of the memory
+ space behind it.
+- Ideally, the common layer should mark as primary up to one PCI adapter
+ per domain. This has yet to be done.
+- Something needs to be done about PCI master aborts on primary buses.
+ For details on this, see my long-winded diatribe in sparcPci.c, and
+ related comments in linuxPci.c. Suffice it to say here that I see the
+ eventual implementation of host bridge drivers within XFree86 as
+ unavoidable at this point.
+- DGA is broken on multi-domain platforms. The information passed to the
+ client to locate the framebuffer still needs to be revised. The best way
+ to deal with this is to change all drivers' OpenFramebuffer() function to
+ call a common layer routine to set the device name and displacements to be
+ returned to the DGA client.
+
+Output drivers
+--------------
+Most drivers currently used on ix86 need(ed) source code changes.
+- Calls to xf86ReadBIOS() and xf86MapVidMem() were replaced with calls to
+ xf86ReadDomainMemory() and xf86MapDomainMemory() respectively. Except
+ for the "ati" and "atimisc" modules, this has already been done.
+- All ix86-style I/O port numbers need to be declared as an IOADDRESS, a
+ type defined in xf86Pci.h as "unsigned long". Such port numbers also
+ need to be offset by a displacement which is also defined as an
+ IOADDRESS. Before a driver's PreInit() is called, the common layer
+ makes this displacement available in ScrnInfoRec.domainIOBase. For
+ single-domain architectures, such as ix86, domainIOBase will always be
+ zero. Current use of vgaHWRec.PIOOffset has also been adjusted
+ accordingly. Some drivers have been changed to keep a copy of this
+ displacement in their private structure. Internally, an IOADDRESS is
+ actually a pointer that has been recasted to an unsigned long, but the
+ common layer "hides" this fact from the driver ABI, which means that I/O
+ port numbers, as seen by drivers, remain as integers rather than
+ addresses. Aside from the ati and atimisc modules, s3, sis and tseng
+ are the only modules left whose I/O still needs to be converted (I've
+ temporarily run out of steam).
+- Note that these conversions are not necessarily sufficient to produce
+ drivers that will work on any given multi-domain architecture. A driver
+ that, for example, had endianness problems, still does. But, at least,
+ these conversions, along with the supporting common layer changes, make
+ PCI drivers more widely amenable to porting.
+- rdinx(), wrinx(), modinx(), testrg(), testinx() and testinx2() are not
+ given enough information to allow for the relocation of their I/O. They
+ are consequently being deleted. The apm and ark drivers, the only
+ remaining callers of the first three, have been changed to use local
+ definitions instead. The last three (test*()) were already unused.
+- As a temporary measure, these changes completely disable ISA-style
+ probing on SPARC's and PowerPC's. This means that driver calls to
+ xf86MatchIsaInstances(), while still valid, will always return detection
+ failure on SPARC's and PowerPC's. This will be dealt with when a more
+ general master abort handling scheme is implemented.
+- I need to make a decision about the master abort issues mentionned above
+ before I can convert the "ati" and "atimisc" modules. Consequently,
+ these modules still need to be compiled with -DAVOID_CPIO on
+ multi-domain architectures, and support for Mach64 variants as
+ non-primary heads is not yet available.
+
+$XFree86$
diff --git a/xorg-server/hw/xfree86/doc/devel/Makefile.am b/xorg-server/hw/xfree86/doc/devel/Makefile.am
new file mode 100644
index 000000000..6ca350c38
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/devel/Makefile.am
@@ -0,0 +1,10 @@
+# Documentation for developers that is distributed with the source but
+# not installed on the system for end-users
+
+EXTRA_DIST = \
+ DebuggingHints \
+ Domain.note \
+ RAC.Notes \
+ Registry \
+ exa-driver.txt \
+ README.DRIcomp
diff --git a/xorg-server/hw/xfree86/doc/devel/Makefile.in b/xorg-server/hw/xfree86/doc/devel/Makefile.in
new file mode 100644
index 000000000..7c169aff3
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/devel/Makefile.in
@@ -0,0 +1,542 @@
+# Makefile.in generated by automake 1.10.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+# Documentation for developers that is distributed with the source but
+# not installed on the system for end-users
+VPATH = @srcdir@
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = hw/xfree86/doc/devel
+DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \
+ $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+ $(ACLOCAL_M4)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/include/do-not-use-config.h \
+ $(top_builddir)/include/xorg-server.h \
+ $(top_builddir)/include/dix-config.h \
+ $(top_builddir)/include/xgl-config.h \
+ $(top_builddir)/include/xorg-config.h \
+ $(top_builddir)/include/xkb-config.h \
+ $(top_builddir)/include/xwin-config.h \
+ $(top_builddir)/include/kdrive-config.h
+CONFIG_CLEAN_FILES =
+SOURCES =
+DIST_SOURCES =
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+ACLOCAL = @ACLOCAL@
+ADMIN_MAN_DIR = @ADMIN_MAN_DIR@
+ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@
+ALLOCA = @ALLOCA@
+AMTAR = @AMTAR@
+APPDEFAULTDIR = @APPDEFAULTDIR@
+APPLE_APPLICATIONS_DIR = @APPLE_APPLICATIONS_DIR@
+APP_MAN_DIR = @APP_MAN_DIR@
+APP_MAN_SUFFIX = @APP_MAN_SUFFIX@
+AR = @AR@
+AS = @AS@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BASE_FONT_PATH = @BASE_FONT_PATH@
+BUILD_DATE = @BUILD_DATE@
+BUILD_TIME = @BUILD_TIME@
+CC = @CC@
+CCAS = @CCAS@
+CCASDEPMODE = @CCASDEPMODE@
+CCASFLAGS = @CCASFLAGS@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+COMPILEDDEFAULTFONTPATH = @COMPILEDDEFAULTFONTPATH@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CXX = @CXX@
+CXXCPP = @CXXCPP@
+CXXDEPMODE = @CXXDEPMODE@
+CXXFLAGS = @CXXFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DARWIN_LIBS = @DARWIN_LIBS@
+DBUS_CFLAGS = @DBUS_CFLAGS@
+DBUS_LIBS = @DBUS_LIBS@
+DEFAULT_LIBRARY_PATH = @DEFAULT_LIBRARY_PATH@
+DEFAULT_LOGPREFIX = @DEFAULT_LOGPREFIX@
+DEFAULT_MODULE_PATH = @DEFAULT_MODULE_PATH@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DGA_CFLAGS = @DGA_CFLAGS@
+DGA_LIBS = @DGA_LIBS@
+DIX_CFLAGS = @DIX_CFLAGS@
+DLLTOOL = @DLLTOOL@
+DMXEXAMPLES_DEP_CFLAGS = @DMXEXAMPLES_DEP_CFLAGS@
+DMXEXAMPLES_DEP_LIBS = @DMXEXAMPLES_DEP_LIBS@
+DMXMODULES_CFLAGS = @DMXMODULES_CFLAGS@
+DMXMODULES_LIBS = @DMXMODULES_LIBS@
+DMXXIEXAMPLES_DEP_CFLAGS = @DMXXIEXAMPLES_DEP_CFLAGS@
+DMXXIEXAMPLES_DEP_LIBS = @DMXXIEXAMPLES_DEP_LIBS@
+DMXXMUEXAMPLES_DEP_CFLAGS = @DMXXMUEXAMPLES_DEP_CFLAGS@
+DMXXMUEXAMPLES_DEP_LIBS = @DMXXMUEXAMPLES_DEP_LIBS@
+DRI2PROTO_CFLAGS = @DRI2PROTO_CFLAGS@
+DRI2PROTO_LIBS = @DRI2PROTO_LIBS@
+DRIPROTO_CFLAGS = @DRIPROTO_CFLAGS@
+DRIPROTO_LIBS = @DRIPROTO_LIBS@
+DRIVER_MAN_DIR = @DRIVER_MAN_DIR@
+DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@
+DRI_DRIVER_PATH = @DRI_DRIVER_PATH@
+DSYMUTIL = @DSYMUTIL@
+DTRACE = @DTRACE@
+ECHO = @ECHO@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+EXEEXT = @EXEEXT@
+F77 = @F77@
+FFLAGS = @FFLAGS@
+FILE_MAN_DIR = @FILE_MAN_DIR@
+FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@
+FREETYPE_CFLAGS = @FREETYPE_CFLAGS@
+FREETYPE_LIBS = @FREETYPE_LIBS@
+GLX_ARCH_DEFINES = @GLX_ARCH_DEFINES@
+GLX_DEFINES = @GLX_DEFINES@
+GL_CFLAGS = @GL_CFLAGS@
+GL_LIBS = @GL_LIBS@
+GREP = @GREP@
+HAL_CFLAGS = @HAL_CFLAGS@
+HAL_LIBS = @HAL_LIBS@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+KDRIVE_CFLAGS = @KDRIVE_CFLAGS@
+KDRIVE_INCS = @KDRIVE_INCS@
+KDRIVE_LIBS = @KDRIVE_LIBS@
+KDRIVE_LOCAL_LIBS = @KDRIVE_LOCAL_LIBS@
+KDRIVE_PURE_INCS = @KDRIVE_PURE_INCS@
+KDRIVE_PURE_LIBS = @KDRIVE_PURE_LIBS@
+LAUNCHD = @LAUNCHD@
+LDFLAGS = @LDFLAGS@
+LD_EXPORT_SYMBOLS_FLAG = @LD_EXPORT_SYMBOLS_FLAG@
+LEX = @LEX@
+LEXLIB = @LEXLIB@
+LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@
+LIBDRM_CFLAGS = @LIBDRM_CFLAGS@
+LIBDRM_LIBS = @LIBDRM_LIBS@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIB_MAN_DIR = @LIB_MAN_DIR@
+LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@
+LINUXDOC = @LINUXDOC@
+LN_S = @LN_S@
+LTLIBOBJS = @LTLIBOBJS@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+MAKE_HTML = @MAKE_HTML@
+MAKE_PDF = @MAKE_PDF@
+MAKE_PS = @MAKE_PS@
+MAKE_TEXT = @MAKE_TEXT@
+MESA_SOURCE = @MESA_SOURCE@
+MISC_MAN_DIR = @MISC_MAN_DIR@
+MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@
+MKDIR_P = @MKDIR_P@
+MKFONTDIR = @MKFONTDIR@
+MKFONTSCALE = @MKFONTSCALE@
+NMEDIT = @NMEDIT@
+OBJC = @OBJC@
+OBJCCLD = @OBJCCLD@
+OBJCDEPMODE = @OBJCDEPMODE@
+OBJCFLAGS = @OBJCFLAGS@
+OBJCLINK = @OBJCLINK@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OPENSSL_CFLAGS = @OPENSSL_CFLAGS@
+OPENSSL_LIBS = @OPENSSL_LIBS@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PCIACCESS_CFLAGS = @PCIACCESS_CFLAGS@
+PCIACCESS_LIBS = @PCIACCESS_LIBS@
+PCI_TXT_IDS_PATH = @PCI_TXT_IDS_PATH@
+PERL = @PERL@
+PKG_CONFIG = @PKG_CONFIG@
+PROJECTROOT = @PROJECTROOT@
+PS2PDF = @PS2PDF@
+RANLIB = @RANLIB@
+RAWCPP = @RAWCPP@
+RAWCPPFLAGS = @RAWCPPFLAGS@
+SED = @SED@
+SERVER_MISC_CONFIG_PATH = @SERVER_MISC_CONFIG_PATH@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+SOLARIS_ASM_CFLAGS = @SOLARIS_ASM_CFLAGS@
+SOLARIS_INOUT_ARCH = @SOLARIS_INOUT_ARCH@
+STRIP = @STRIP@
+TSLIB_CFLAGS = @TSLIB_CFLAGS@
+TSLIB_LIBS = @TSLIB_LIBS@
+UTILS_SYS_LIBS = @UTILS_SYS_LIBS@
+VENDOR_MAN_VERSION = @VENDOR_MAN_VERSION@
+VENDOR_NAME = @VENDOR_NAME@
+VENDOR_NAME_SHORT = @VENDOR_NAME_SHORT@
+VENDOR_RELEASE = @VENDOR_RELEASE@
+VERSION = @VERSION@
+X11APP_ARCHS = @X11APP_ARCHS@
+X11EXAMPLES_DEP_CFLAGS = @X11EXAMPLES_DEP_CFLAGS@
+X11EXAMPLES_DEP_LIBS = @X11EXAMPLES_DEP_LIBS@
+XDMCP_CFLAGS = @XDMCP_CFLAGS@
+XDMCP_LIBS = @XDMCP_LIBS@
+XDMXCONFIG_DEP_CFLAGS = @XDMXCONFIG_DEP_CFLAGS@
+XDMXCONFIG_DEP_LIBS = @XDMXCONFIG_DEP_LIBS@
+XDMX_CFLAGS = @XDMX_CFLAGS@
+XDMX_LIBS = @XDMX_LIBS@
+XDMX_SYS_LIBS = @XDMX_SYS_LIBS@
+XEGLMODULES_CFLAGS = @XEGLMODULES_CFLAGS@
+XEGL_LIBS = @XEGL_LIBS@
+XEGL_SYS_LIBS = @XEGL_SYS_LIBS@
+XEPHYR_CFLAGS = @XEPHYR_CFLAGS@
+XEPHYR_DRI_LIBS = @XEPHYR_DRI_LIBS@
+XEPHYR_INCS = @XEPHYR_INCS@
+XEPHYR_LIBS = @XEPHYR_LIBS@
+XF86CONFIGFILE = @XF86CONFIGFILE@
+XF86MISC_CFLAGS = @XF86MISC_CFLAGS@
+XF86MISC_LIBS = @XF86MISC_LIBS@
+XF86VIDMODE_CFLAGS = @XF86VIDMODE_CFLAGS@
+XF86VIDMODE_LIBS = @XF86VIDMODE_LIBS@
+XGLMODULES_CFLAGS = @XGLMODULES_CFLAGS@
+XGLMODULES_LIBS = @XGLMODULES_LIBS@
+XGLXMODULES_CFLAGS = @XGLXMODULES_CFLAGS@
+XGLXMODULES_LIBS = @XGLXMODULES_LIBS@
+XGLX_LIBS = @XGLX_LIBS@
+XGLX_SYS_LIBS = @XGLX_SYS_LIBS@
+XGL_LIBS = @XGL_LIBS@
+XGL_MODULE_PATH = @XGL_MODULE_PATH@
+XGL_SYS_LIBS = @XGL_SYS_LIBS@
+XKB_BASE_DIRECTORY = @XKB_BASE_DIRECTORY@
+XKB_BIN_DIRECTORY = @XKB_BIN_DIRECTORY@
+XKB_COMPILED_DIR = @XKB_COMPILED_DIR@
+XKM_OUTPUT_DIR = @XKM_OUTPUT_DIR@
+XLIB_CFLAGS = @XLIB_CFLAGS@
+XLIB_LIBS = @XLIB_LIBS@
+XNESTMODULES_CFLAGS = @XNESTMODULES_CFLAGS@
+XNESTMODULES_LIBS = @XNESTMODULES_LIBS@
+XNEST_LIBS = @XNEST_LIBS@
+XNEST_SYS_LIBS = @XNEST_SYS_LIBS@
+XORGCFG_DEP_CFLAGS = @XORGCFG_DEP_CFLAGS@
+XORGCFG_DEP_LIBS = @XORGCFG_DEP_LIBS@
+XORGCONFIG_DEP_CFLAGS = @XORGCONFIG_DEP_CFLAGS@
+XORGCONFIG_DEP_LIBS = @XORGCONFIG_DEP_LIBS@
+XORG_CFLAGS = @XORG_CFLAGS@
+XORG_INCS = @XORG_INCS@
+XORG_LIBS = @XORG_LIBS@
+XORG_MODULES_CFLAGS = @XORG_MODULES_CFLAGS@
+XORG_MODULES_LIBS = @XORG_MODULES_LIBS@
+XORG_OS = @XORG_OS@
+XORG_OS_SUBDIR = @XORG_OS_SUBDIR@
+XORG_SYS_LIBS = @XORG_SYS_LIBS@
+XPRINTMODULES_CFLAGS = @XPRINTMODULES_CFLAGS@
+XPRINTMODULES_LIBS = @XPRINTMODULES_LIBS@
+XPRINTPROTO_CFLAGS = @XPRINTPROTO_CFLAGS@
+XPRINTPROTO_LIBS = @XPRINTPROTO_LIBS@
+XPRINT_CFLAGS = @XPRINT_CFLAGS@
+XPRINT_LIBS = @XPRINT_LIBS@
+XPRINT_SYS_LIBS = @XPRINT_SYS_LIBS@
+XRESEXAMPLES_DEP_CFLAGS = @XRESEXAMPLES_DEP_CFLAGS@
+XRESEXAMPLES_DEP_LIBS = @XRESEXAMPLES_DEP_LIBS@
+XSDL_INCS = @XSDL_INCS@
+XSDL_LIBS = @XSDL_LIBS@
+XSERVERCFLAGS_CFLAGS = @XSERVERCFLAGS_CFLAGS@
+XSERVERCFLAGS_LIBS = @XSERVERCFLAGS_LIBS@
+XSERVERLIBS_CFLAGS = @XSERVERLIBS_CFLAGS@
+XSERVERLIBS_LIBS = @XSERVERLIBS_LIBS@
+XSERVER_LIBS = @XSERVER_LIBS@
+XSERVER_SYS_LIBS = @XSERVER_SYS_LIBS@
+XTSTEXAMPLES_DEP_CFLAGS = @XTSTEXAMPLES_DEP_CFLAGS@
+XTSTEXAMPLES_DEP_LIBS = @XTSTEXAMPLES_DEP_LIBS@
+XVFB_LIBS = @XVFB_LIBS@
+XVFB_SYS_LIBS = @XVFB_SYS_LIBS@
+XWINMODULES_CFLAGS = @XWINMODULES_CFLAGS@
+XWINMODULES_LIBS = @XWINMODULES_LIBS@
+XWIN_LIBS = @XWIN_LIBS@
+XWIN_SERVER_NAME = @XWIN_SERVER_NAME@
+XWIN_SYS_LIBS = @XWIN_SYS_LIBS@
+YACC = @YACC@
+YFLAGS = @YFLAGS@
+__XCONFIGFILE__ = @__XCONFIGFILE__@
+abi_ansic = @abi_ansic@
+abi_extension = @abi_extension@
+abi_font = @abi_font@
+abi_videodrv = @abi_videodrv@
+abi_xinput = @abi_xinput@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_CXX = @ac_ct_CXX@
+ac_ct_F77 = @ac_ct_F77@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+driverdir = @driverdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+extdir = @extdir@
+ft_config = @ft_config@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+launchagentsdir = @launchagentsdir@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+logdir = @logdir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+moduledir = @moduledir@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sbindir = @sbindir@
+sdkdir = @sdkdir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+xglmoduledir = @xglmoduledir@
+xpconfigdir = @xpconfigdir@
+EXTRA_DIST = \
+ DebuggingHints \
+ Domain.note \
+ RAC.Notes \
+ Registry \
+ exa-driver.txt \
+ README.DRIcomp
+
+all: all-am
+
+.SUFFIXES:
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps)
+ @for dep in $?; do \
+ case '$(am__configure_deps)' in \
+ *$$dep*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \
+ && exit 0; \
+ exit 1;; \
+ esac; \
+ done; \
+ echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign hw/xfree86/doc/devel/Makefile'; \
+ cd $(top_srcdir) && \
+ $(AUTOMAKE) --foreign hw/xfree86/doc/devel/Makefile
+.PRECIOUS: Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ @case '$?' in \
+ *config.status*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+ *) \
+ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+ esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+tags: TAGS
+TAGS:
+
+ctags: CTAGS
+CTAGS:
+
+
+distdir: $(DISTFILES)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ list='$(DISTFILES)'; \
+ dist_files=`for file in $$list; do echo $$file; done | \
+ sed -e "s|^$$srcdirstrip/||;t" \
+ -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+ case $$dist_files in \
+ */*) $(MKDIR_P) `echo "$$dist_files" | \
+ sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+ sort -u` ;; \
+ esac; \
+ for file in $$dist_files; do \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+ cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
+ fi; \
+ cp -pR $$d/$$file $(distdir)$$dir || exit 1; \
+ else \
+ test -f $(distdir)/$$file \
+ || cp -p $$d/$$file $(distdir)/$$file \
+ || exit 1; \
+ fi; \
+ done
+check-am: all-am
+check: check-am
+all-am: Makefile
+installdirs:
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ `test -z '$(STRIP)' || \
+ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+ -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-am
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am:
+
+html: html-am
+
+info: info-am
+
+info-am:
+
+install-data-am:
+
+install-dvi: install-dvi-am
+
+install-exec-am:
+
+install-html: install-html-am
+
+install-info: install-info-am
+
+install-man:
+
+install-pdf: install-pdf-am
+
+install-ps: install-ps-am
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am:
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-generic clean-libtool \
+ distclean distclean-generic distclean-libtool distdir dvi \
+ dvi-am html html-am info info-am install install-am \
+ install-data install-data-am install-dvi install-dvi-am \
+ install-exec install-exec-am install-html install-html-am \
+ install-info install-info-am install-man install-pdf \
+ install-pdf-am install-ps install-ps-am install-strip \
+ installcheck installcheck-am installdirs maintainer-clean \
+ maintainer-clean-generic mostlyclean mostlyclean-generic \
+ mostlyclean-libtool pdf pdf-am ps ps-am uninstall uninstall-am
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/xorg-server/hw/xfree86/doc/devel/RAC.Notes b/xorg-server/hw/xfree86/doc/devel/RAC.Notes
new file mode 100644
index 000000000..0aec9d795
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/devel/RAC.Notes
@@ -0,0 +1,696 @@
+I. Abstract
+===========
+
+Graphics devices are accessed thru ranges in I/O or memory space. While
+most modern graphics devices allow relocation of such ranges many of
+them still require the use of well established interfaces such as VGA
+memory and IO ranges or 8514/A IO ranges. Up to version 3.3 of
+XFree86 only a single graphics device could be driven. Therfore there
+was no need to address the issue of sharing such memory or I/O ranges
+among several devices. Starting with version 4.0 XFree86 is capable of
+driving more than one graphics interface in a multi-head environment.
+Therefore a mechanism needed to be designed which was capable of
+controlling the sharing the access to memory and I/O ranges. In this
+document we describe to use of the RAC (Resource Access Control)
+system in the XFree86 server which provides the service of controlling
+access to interface resources.
+
+II. Introduction
+================
+
+Terms and definitions:
+
+II.1. Bus
+---------
+
+'Bus' is ambiguous as it is used for different things: It may refer to
+physical incompatible extension connectors in a computer system. The
+RAC system knows two such systems: The ISA bus and the PCI bus. (On
+the software level EISA, MC and VL buses are currently treated like
+ISA buses). 'Bus' may always refer to logically different entities on
+a single bus system which are connected via bridges. A PCI system may
+have several distinct PCI buses connecting each other by PCI-PCI
+bridges or to the host CPU by HOST-PCI bridges.
+
+Systems that host more than one bus system link these together using
+bridges. Bridges are a concern to RAC as they might block or pass
+specific resources. PCI-PCI bridges may be set up to pass VGA
+resources to the secondary bus. PCI-ISA buses pass any resources not
+decoded on the primary PCI bus to the ISA bus. This way VGA resources
+(although exclusive on the ISA bus) can be shared by ISA and PCI
+cards. Currently HOST-PCI bridges are not yet handled by RACY as they
+require specific drivers.
+
+II.2. Entity
+------------
+
+The smallest independently addressable unit on a system bus is
+referred to as an entity. So far we know ISA and PCI entities. PCI
+entities can be located on the PCI bus by an unique ID consisting of
+the bus, card and function number.
+
+II.3. Resource
+--------------
+
+ 'Resource' refers to a range of memory or I/O addresses an entity
+can decode.
+
+If a device is capable of disabling this decoding the resource is
+called sharable. For PCI devices a generic method is provided to
+control resource decoding. Other devices will have to provide a device
+specific function to control decoding.
+
+If the entity is capable of decoding this range at a different
+location this resource is considered relocatable. Resource which start
+at a specific address and occupy a single continuous range are called
+block resources.
+
+Alternatively resource addresses can be decoded in a way that they
+satisfy the condition:
+
+ address & mask == base
+
+with base & mask == base. Resources addressed in such a way are
+considered sparse resources.
+
+
+II.4. Server States
+------------------
+
+The resource access control system knows two server states: the SETUP
+and the OPERATING state. The setup state is entered whenever a mode
+change takes place or the server exits or does VT switching. During
+this state any entity resource is under resource access control.
+During OPERATING state only those entities are controlled which
+actually have shared resources that conflict with others. The
+determination which entity is to be placed under RAC during OPERATING
+state takes place after ScreenInit() during the first server
+generation. This doesn't apply if only one screen is active: in this
+case no RAC is needed and the screen is simply left enabled while the
+server is active.
+
+
+III. Theory of operation
+========================
+
+III.1. General
+--------------
+
+The common level has knowledge of generic access control mechanisms
+for devices on certain bus systems (currently the PCI bus) as well as
+of methods to enable or disable access to the buses
+itself. Furthermore it can access information on resources decoded by
+these devices and if necessary modify it.
+
+When first starting the Xserver collects all this information, saves
+it for restoration checks it for consistency and if necessary corrects
+it. Finally it disables all resources on a generic level prior to
+calling any driver function.
+
+ The user should provide a device section in XF86Config for each
+graphics device installed in his system. Each such entity which is
+never to be used as X display device might be marked as inactive by
+adding the keyword "Inactive" to the device section.
+
+When the Probe() function of each driver is called the device sections
+are matched against the devices found in the system. The driver may
+probe devices at this stage that cannot be identified by using device
+independent methods. Access to all resources that can be controlled in
+a device independent way is disabled. The Probe() function should
+register all non-relocatable resources at this stage. If a resource
+conflict is found between exclusive resources the driver will fail
+immediately. Optionally the driver might specify an EntityInit(),
+EntityLeave() and EntityEnter() function.
+
+EntityInit() can be used to disable any shared resources that are not
+controlled by the generic access control functions. It is called prior
+to the PreInit phase regardless if an entity is active or not. When
+calling the EntityInit(), EntityEnter() and EntityLeave() functions
+the common level will disable access to all other entities on a
+generic level. Since the common level has no knowledge of device
+specific methods to disable access to resources it cannot be
+guaranteed that certain resources are not decoded by any other entity
+until the EntityInit() or EntityEnter() phase is finished. Device
+drivers should therefore register all those resources which they are
+going to disable. If these resources are never to be used by any
+driver function they may be flagged 'ResInit' so that they can be
+removed from the resource list after processing all EntityInit()
+functions. EntityEnter() should disable decoding of all resources
+which are not registered as exclusive and which are not handled by the
+generic access control in the common level. The difference to
+EntityInit() is that the latter one is only called once during
+lifetime of the server. It can therefore be used to set up variables
+prior to disabling resources. EntityLeave() should restore the
+original state when exiting the server or switching to a different vt.
+It also needs to disable device specific access functions if they need
+to be disabled on server exit or VT switch. The default state is to
+enable them before giving up the VT.
+
+In PreInit() phase each driver should check if any sharable resources
+it has registered during Probe() has been denied and take appropriate
+action which could simply be to fail. If it needs to access resources
+it has disabled during EntitySetup() it can do so provided it has
+registered these and will disable them before returning from
+PreInit(). This also applies to all other driver functions. Several
+functions are provided to request resource ranges, register these,
+correct PCI config space and add replacements for the generic access
+functions. Resources may be marked 'disabled' or 'unused' during
+OPERATING stage. Although these steps could also be performed in
+ScreenInit(), this is not desirable.
+
+Following PreInit() phase the common level determines if resource
+access control is needed. This is the case if more than one screen is
+used. If necessary the RAC wrapper module is loaded. In ScreenInit()
+the drivers can decide which operations need to be placed under
+RAC. Available are the frame buffer operations, the pointer operations
+and the colormap operations. Any operation that requires resources
+which might be disabled during OPERATING state should be set to use
+RAC. This can be specified separately for memory and IO resources.
+
+When ScreenInit() phase is done the common level will determine which
+shared resources are requested by more than one driver and set the
+access functions accordingly. This is done following these rules:
+
+a. The sharable resources registered by each entity are compared. if
+ a resource is registered by more than one entity the entity will be
+ marked to need to share this resources type (IO or MEM).
+
+b. A resource marked 'disabled' during OPERATING state will be ignored
+ entirely.
+
+c. A resource marked 'unused' will only conflicts with an overlapping
+ resource of an other entity if the second is actually in use during
+ OPERATING state.
+
+d. If an 'unused' resource was found to conflict however the entity
+ does not use any other resource of this type the entire resource
+ type will be disabled for that entity.
+
+The driver has the choice among different ways to control access to
+certain resources:
+
+a. It can relay on the generic access functions. This is probably the
+ most common case. Here the driver only needs to register any
+ resource it is going to use.
+
+b. It can replace the generic access functions by driver specific
+ ones. This will mostly be used in cases where no generic access
+ functions are available. In this case the driver has to make sure
+ these resources are disabled when entering the PreInit() stage.
+ Since the replacement functions are registered in PreInit() the
+ driver will have to enable these resources itself if it needs to
+ access them during this state. The driver can specify if the
+ replacement functions can control memory and/or I/O resources
+ separately.
+
+c. The driver can enable resources itself when it needs them. Each
+ driver function enabling them needs to disable them before it will
+ return. This should be used if a resource which can be controlled
+ in a device dependent way is only required during SETUP state. This
+ way it can be marked 'unused' during OPERATING state.
+
+A resource which is decoded during OPERATING state however never
+accessed by the driver should be marked unused.
+
+Since access switching latencies are an issue during Xserver
+operation, the common level attempts to minimize the number of
+entities that need to be placed under RAC control. When a wrapped
+operation is called, the EnableAccess() function is called before
+control is passed on. EnableAccess() checks if a screen is under
+access control. If not it just establishes bus routing and returns. If
+the screen needs to be under access control, EnableAccess() determines
+which resource types (MEM,IO) are required. Then it tests if this
+access is already established. If so it simply returns. If not it
+disables the currently established access, fixes bus routing and
+enables access to all entities registered for this screen.
+
+Whenever a mode switch or a vt-switch is performed the common level
+will return to SETUP state.
+
+III.3. Resource Types
+---------------------
+
+Resource have certain properties. When registering resources each
+range is accompanied by a flag consisting of the or'ed flags of the
+different properties the resource has. Each resource range may be
+classified according to
+
+- its physical properties ie. if it addresses
+ memory (ResMem) or
+ I/O space (ResIo),
+- if it addresses a
+ block (ResBlock) or
+ sparse (ResSparse)
+ range,
+- its access properties.
+
+There are two known access properties:
+
+- ResExclusive
+ for resources which may not be shared with any other device and
+- ResShared
+ for resources which can be disabled and therefore can be shared.
+
+If it is desirable to test a resource against any type a generic
+access type 'ResAny' is provided. If this is set the resource will
+conflict with any resource of a different entity intersecting its
+range. Further it can be specified that a resource is decoded however
+never used during any stage (ResUnused) or during OPERATING state
+(ResUnusedOpr). A resource only visible during the init functions (ie.
+EntityInit(), EntityEnter() and EntityLeave() should be registered
+with the flag 'ResInit'. A resource that might conflict with
+background resource ranges may be flagged with 'ResBios'. This might
+be useful when registering resources ranges that were assigned by the
+system Bios.
+
+Several predefined resource lists are available for VGA and 8514/A
+resources in common/sf86Resources.h.
+
+IV. Available Functions
+=======================
+
+The functions provided for resource management will be listed in order
+of use in the driver.
+
+IV.1. Probe phase
+-----------------
+
+In this stage each driver detects those resources it is able to drive,
+creates an entity record for each of them, registers non-relocatable
+resources and allocates screens and adds the resources to screens.
+
+Two helper functions are provided for matching device sections in the
+XF86Config file to the devices:
+
+ int xf86MatchPciInstances(const char *driverName, int vendorID,
+ SymTabPtr chipsets, PciChipsets *PCIchipsets,
+ GDevPtr *devList, int numDevs, DriverPtr drvp,
+ int **foundEntities);
+
+ int xf86MatchIsaInstances(const char *driverName, SymTabPtr chipsets,
+ IsaChipsets *ISAchipsets, DriverPtr drvp,
+ FindIsaDevProc FindIsaDevice, GDevPtr *devList,
+ int numDevs, int **foundEntities);
+
+Both functions return the number of matched entities and their indices
+in foundEntities list.
+
+They make use of several sub functions which are also available on the
+driver level:
+
+ Bool xf86ComparePciBusString(const char *busID, int bus,
+ int device, int func);
+
+and
+
+ Bool xf86ParseIsaBusString(const char *busID);
+
+are called to interpret the busID in the device section. The functions:
+
+ int xf86ClaimPciSlot(int bus, int device, int func, DriverPtr drvp,
+ int chipset, GDevPtr dev, Bool active);
+
+ int xf86ClaimIsaSlot(DriverPtr drvp, int chipset, GDevPtr dev, Bool
+ active);
+
+are used to allocate the entities and initialize their data
+structures. Both functions return the index of the newly allocated
+entity record or (-1) should the function fail. Before probing an ISA
+card
+
+ Bool xf86IsPrimaryIsa();
+
+gets called to determine if the primary card was not detected on the
+PCI bus.
+
+Two helper functions are provided to aid configuring entities:
+
+ Bool xf86ConfigActivePciEntity(ScrnInfoPtr pScrn, int entityIndex,
+ PciChipsets *p_chip, resList res,
+ EntityProc init, EntityProc enter,
+ EntityProc leave, pointer private);
+ Bool xf86ConfigActiveIsaEntity(ScrnInfoPtr pScrn, int entityIndex,
+ IsaChipsets *i_chip, resList res,
+ EntityProc init, EntityProc enter,
+ EntityProc leave, pointer private);
+
+They are used to register the init/enter/leave functions described
+above as well as the non-relocatable resources. Generally the list of
+fixed resources is obtained from the Isa/PciChipsets lists. However
+an additional list of resources may be passed. Generally this is not
+required. The init/enter/leave functions have to be of type
+
+ typedef void (*EntityProc)(int entityIndex,pointer private);
+
+They are passed the entity index and a pointer to a private scratch
+area. This are can be set up during Probe() and its address can be
+passed to xf86ConfigActiveIsaEntity() xf86ConfigActivePciEntity() as
+the last argument.
+
+These helper functions use:
+
+ void xf86ClaimFixedResources(resList list, int entityIndex);
+
+ To register the non relocatable resources which cannot be disabled
+ and which therefore would cause the server to fail immediately if
+ they were found to conflict. It also records non-relocatable but
+ sharable resources for processing after the Probe() phase.
+
+ Bool xf86SetEntityFuncs(int entityIndex, EntityProc init,
+ EntityProc enter, EntityProc leave, pointer);
+
+ This function registers the init/enter/leave() functions along with
+ the pointer to their private area to the entity.
+
+ void xf86AddEntityToScreen(ScrnInfoPtr pScrn, int entityIndex);
+
+ adds the entity to the screen.
+
+These functions are also available on the driver level. A detailed
+Probe() function is listed below. For most drivers this can be used
+with little change.
+
+Please note that VGA resources have to be claimed in Probe()
+phase. Otherwise they are not routed to the bus.
+
+IV.2. PreInit() phase
+---------------------
+
+During this phase the remaining resource should be registered.
+PreInit() should call
+
+ EntityInfoPtr xf86GetEntityInfo(int entityIndex);
+
+To obtain a pointer to an EntityInfoRec for each entity it is able to
+drive and check if any resource are listed in 'resources'. These have
+been rejected in the post-Probe() phase. The driver should decide if
+it can continue without using these or if it should fail. The pointer
+to the EntityInfoRec should be freed if not needed any more.
+
+Several functions are provided to simplify resource registration:
+
+ Bool xf86IsEntityPrimary(int entityIndex);
+
+is used to determine if the entity is the display device that is used
+during boot-up and text mode.
+
+ Bool xf86IsScreenPrimary(int scrnIndex);
+
+finds out if the primary entity is registered for the screen with
+specified index.
+
+ pciVideoPtr xf86GetPciInfoForEntity(int entityIndex);
+
+returns a pointer to the pciVideoRec of the specified entity. If the
+entity is not a PCI device NULL is returned.
+
+The primary function for registration of resources is
+
+ resPtr xf86RegisterResources(int entityIndex, resList list, int access);
+
+it tries to register the resources in 'list'. If list is NULL it tries
+to determine the resources automatically. This only works for entities
+that provide a generic way to read out the resource ranges they
+decode. So far this is only the case for PCI devices. By default the
+PCI resources are registered as shared (ResShared) if the driver wants
+to set a different access type it can do so by specifying the access
+flags in the third argument. A value of 0 means to use the default
+settings. If for any reason the resource broker is not able to
+register some of the requested resources the function will return a
+pointer to a list of the failed ones. In this case the driver may move
+the resource to different locations. In case of PCI bus entities this
+is done by passing the list of failed resources to
+
+ resPtr xf86ReallocatePciResources(int entityIndex, resPtr pRes);
+
+this function returns a list of reallocated resource. This list needs
+to be passed to xf86RegisterResources() again to be registered with
+the broker.
+
+Two functions are provided to obtain a resource range of a given type:
+
+ resRange xf86GetBlock(long type, memType size,
+ memType window_start, memType window_end,
+ memType align_mask, resPtr avoid);
+ resRange xf86GetSparse(long type, unsigned long fixed_bits,
+ unsigned long decode_mask, unsigned long address_mask,
+ resPtr avoid);
+
+The first one tries to find a block range of size 'size' and type
+'type' in a window bound by window_start and window_end with the
+alignment specified in alignment mask. Optionally a list of resource
+ranges which should be avoided inside this window can be passed. On
+failure it will return a zero range of type 'ResEnd'.
+
+The latter function does the same for sparse resources. A spares range
+is determined by to parameters: the mask and the base value. An
+address satisfying
+
+ mask & address == base
+
+belongs to the specific spares range. 'mask' and 'base' themselves
+have to satisfy:
+
+ mask & base == base.
+
+Here three values have to be specified: the address mask which marks
+all bits of the mask part of the address, the decode_mask which masks
+out the bits which are hard coded and are therefore not available for
+relocation and the values of the fixed bits. The function tries to
+find a base that satisfies the given condition. If the function fails
+it will return a zero range of type 'ResEnd'. Optionally it might be
+passed a list of resource ranges to avoid.
+
+Certain PCI devices are broken in the sense that they return invalid
+size information for a certain resource. In this case the driver can
+supply the correct size and make sure that the resource range
+allocated for the card is large enough to hold the address range
+decoded by the card. The function:
+
+ Bool xf86FixPciResource(int entityIndex, unsigned int prt, CARD32 alignment,
+ long type);
+
+is used for that. The parameter prt contains the number of the PCI
+base register that needs to be modified. A value of 6 refers to the
+BIOS base register. The size is specified in the alignment
+register. Since PCI resources need to span an integral range of the
+size 2^n the alignment also specifies the number of addresses that
+will be decoded. If the driver specifies a type mask it can override
+the default type for PCI resources which is 'ResShared'. The resource
+broker needs to know that to find a matching resource range. This
+function should be called before calling xf86RegisterResources().
+
+ Bool xf86CheckPciMemBase(pciVideoPtr pPci, unsigned long base);
+
+checks that the memory base value specified in base matches one of the
+PCI base address register values for the given PCI device.
+
+The driver may replace the generic access control functions for an
+entity by it's own ones.
+
+ void xf86SetAccessFuncs(EntityInfoPtr pEnt, xf86SetAccessFuncPtr funcs,
+ xf86SetAccessFuncPtr oldFuncs);
+
+ with:
+
+ typedef struct {
+ xf86AccessPtr mem;
+ xf86AccessPtr io;
+ xf86AccessPtr io_mem;
+ } xf86SetAccessFuncRec, *xf86SetAccessFuncPtr;
+
+is used for that. The driver can pass three functions: one for I/O
+access, one for memory access and one for combined memory and I/O
+access. If the memory access and combined access functions are
+identical the common level assumes that the memory access cannot be
+controlled independently of I/O access, if the I/O access function and
+the combined access functions are the same it is assumed that I/O can
+not be controlled independently. If memory and I/O have to be
+controlled together all three values should be the same. If a non
+NULL value is passed as third argument it is interpreted as an address
+where to store the old access records. If the third argument is NULL
+it will be assumed that the generic access should be enabled before
+replacing the access functions. Otherwise it will be disabled. The
+driver may enable them itself using the returned values. It should do
+this from his replacement access functions as the generic access may
+be disabled by the common level on certain occasions. If replacement
+functions are specified they must control all resources of the
+specific type registered for the entity.
+
+To find out if specific resource range is conflicting with another
+resource
+
+ memType xf86ChkConflict(resRange *rgp, int entityIndex);
+
+may be called. If a non-zero value is returned a conflict is found.
+
+ resPtr xf86SetOperatingState(resList list, int entityIndex, int mask);
+
+is used to set the state of a resource during OPERATING state. 'list'
+holds a list to which 'mask' is to be applied. The parameter 'mask'
+may have the value 'ResUnusedOpr' and 'ResDisableOpr'. The first one
+should be used if a resource isn't used during OPERATING state however
+decoded by the device while the latter one indicates that the resource
+is not decoded during OPERATING state. Note that the resource ranges
+have to match those specified during registration. If a range has been
+specified starting at A and ending at B and suppose C us a value
+satisfying A < C < B one may not specify the resource range (A,B) by
+splitting it into two ranges (A,C) and (C,B).
+
+Two functions are provided for special cases:
+
+ void xf86RemoveEntityFromScreen(ScrnInfoPtr pScrn, int entityIndex);
+
+may be used to remove an entity from a screen. This only makes sense
+if a screen has more than one entity assigned or the screen is to be
+deleted. No test is made if the screen has any entities left.
+
+ void xf86DeallocateResourcesForEntity(int entityIndex, long type);
+
+deallocates all resources of a given type registered for a certain
+entity from the resource broker list.
+
+IV.3. ScreenInit() phase
+------------------------
+
+Setting up the rac flags is all that remains to do in ScreenInit()
+phase (Note that these flags might also be set up in PreInit() phase).
+The ScrnInfoRec has separate flags for memory and PIO access:
+racIoFlags and racMemFlags. They specifies which graphics operations
+might require the use of resources which might be disabled for some
+reason. Note that even exclusive resources might be disabled if they
+are disabled along with shared resources. For example if a driver has
+registered the VGA PIO resources and lets the common level disable
+these by disabling PIO access in PCI config space (the standard way),
+exclusive PCI PIO ranges will also be disabled. Therefore the driver
+has to flag any operations requiring PCI PIO resources in racIoFlags.
+The avaliable flags are defined in rac/xf86RAC.h. Available are:
+
+ RAC_FB for framebuffer operations (including hw acceleration)
+ RAC_CURSOR for Cursor operations
+ (??? I'm not sure if we need this for SW cursor it depends
+ on which level the sw cursor is drawn)
+ RAC_COLORMAP for colormap operations
+ RAC_VIEWPORT for the call to RACAdjustFrame()
+
+The flags are or'ed.
+
+V. Appendix
+===========
+
+A. Sample Probe() Function
+--------------------------
+
+static Bool
+XXXProbe(DriverPtr drv, int flags)
+{
+ Bool foundScreen = FALSE;
+ int numDevSections, numUsed;
+ GDevPtr *devSections;
+ int *usedChips;
+ int i;
+
+ /*
+ * Find the config file Device sections that match this
+ * driver, and return if there are none.
+ */
+ if ((numDevSections = xf86MatchDevice(CHIPS_DRIVER_NAME,
+ &devSections)) <= 0) {
+ return FALSE;
+ }
+ /* PCI BUS */
+ /* test if PCI bus present */
+ if (xf86GetPciVideoInfo() ) {
+ /* match PCI instances with ones supported by the driver */
+ numUsed = xf86MatchPciInstances(XXX_NAME, PCI_VENDOR_XXX,
+ XXXChipsets, XXXPCIchipsets,
+ devSections,numDevSections, drv,
+ &usedChips);
+ if (numUsed > 0) {
+ for (i = 0; i < numUsed; i++) {
+ /* Allocate a ScrnInfoRec */
+ ScrnInfoPtr pScrn = xf86AllocateScreen(drv,0);
+ pScrn->driverVersion = VERSION;
+ pScrn->driverName = XXX_DRIVER_NAME;
+ pScrn->name = XXX_NAME;
+ pScrn->Probe = XXXProbe;
+ pScrn->PreInit = XXXPreInit;
+ pScrn->ScreenInit = XXXScreenInit;
+ pScrn->SwitchMode = XXXSwitchMode;
+ pScrn->AdjustFrame = XXXAdjustFrame;
+ pScrn->EnterVT = XXXEnterVT;
+ pScrn->LeaveVT = XXXLeaveVT;
+ pScrn->FreeScreen = XXXFreeScreen;
+ pScrn->ValidMode = XXXValidMode;
+ foundScreen = TRUE;
+ /* add screen to entity */
+ xf86ConfigActivePciEntity(pScrn,usedChips[i],XXXPCIchipsets,
+ NULL,NULL,NULL,NULL,NULL);
+ }
+ }
+ }
+
+ /* Isa Bus */
+ numUsed = xf86MatchIsaInstances(XXX_NAME,XXXChipsets,XXXISAchipsets,
+ drv,chipsFindIsaDevice,devSections,
+ numDevSections,&usedChips);
+ if(numUsed >= 0)
+ for (i = 0; i < numUsed; i++) {
+ ScrnInfoPtr pScrn = xf86AllocateScreen(drv,0);
+
+ pScrn->driverVersion = VERSION;
+ pScrn->driverName = XXX_DRIVER_NAME;
+ pScrn->name = XXX_NAME;
+ pScrn->Probe = XXXProbe;
+ pScrn->PreInit = XXXPreInit;
+ pScrn->ScreenInit = XXXScreenInit;
+ pScrn->SwitchMode = XXXSwitchMode;
+ pScrn->AdjustFrame = XXXAdjustFrame;
+ pScrn->EnterVT = XXXEnterVT;
+ pScrn->LeaveVT = XXXLeaveVT;
+ pScrn->FreeScreen = XXXFreeScreen;
+ pScrn->ValidMode = XXXValidMode;
+ foundScreen = TRUE;
+ xf86ConfigActiveIsaEntity(pScrn,usedChips[i],XXXISAchipsets,
+ NULL,NULL,NULL,NULL,NULL);
+ }
+ xfree(devSections);
+ return foundScreen;
+}
+
+B. Porting Issues
+-----------------
+
+Here are some hints on porting code developed for RAC 1 to RAC 2.
+
+1. a. Initialization of RAC is now entirely done on the common level.
+ Therefore the call to xf86RACInit() can be removed.
+
+ b. Also there is no need for the racSymbols list.
+
+ c. LoadSubModule(..,rac) should be removed.
+
+ d. racSymbols should be removed from LoaderRequestSymList(racSymbols,..)
+
+2. a. if the driver uses the predefined resource lists xf86Resources.h
+ needs to be included.
+
+ b. RES_VGA should be changed to RES_EXCLUSIVE_VGA
+
+3. The device list now belongs to the EntityInfoRec.
+ Change pScrn->device to xxx->pEnt->device.
+
+4. Rewrite the Probe() function. The example given above should work
+ as a guideline.
+
+5. Register all necessary resources in PreInit() by calling
+ xf86RegisterResources().
+
+6. If applicable set the operating state of the registered resources
+ by calling xf86SetOperatingState(). This should be done during
+ PreInit(). If necessary it might still be done in ScreenInit()
+
+7. Set up the racIoFlags and racMemFlags.
+
+
+ LocalWords: ISA
diff --git a/xorg-server/hw/xfree86/doc/devel/README.DRIcomp b/xorg-server/hw/xfree86/doc/devel/README.DRIcomp
new file mode 100644
index 000000000..89f40a759
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/devel/README.DRIcomp
@@ -0,0 +1,556 @@
+ DRI Compilation Guide
+
+ VA Linux Systems, Inc. Professional Services - Graphics.
+
+ 21 April 2001
+
+1. Preamble
+
+1.1 Copyright
+
+Copyright 2000-2001 by VA Linux Systems, Inc. All Rights Reserved.
+
+Permission is granted to make and distribute verbatim copies of this document
+provided the copyright notice and this permission notice are preserved on all
+copies.
+
+1.2 Trademarks
+
+OpenGL is a registered trademark and SGI is a trademark of Silicon Graphics,
+Inc. Unix is a registered trademark of The Open Group. The `X' device and X
+Window System are trademarks of The Open Group. XFree86 is a trademark of
+The XFree86 Project. Linux is a registered trademark of Linus Torvalds.
+Intel is a registered trademark of Intel Corporation. 3Dlabs, GLINT, and
+Oxygen are either registered trademarks or trademarks of 3Dlabs Inc. Ltd.
+3dfx, Voodoo3, Voodoo4, and Voodoo5 are registered trademarks of 3dfx Inter-
+active, Incorporated. Matrox is a registered trademark of Matrox Electronic
+Systems Ltd. ATI Rage and Radeon is a registered trademark of ATI Technolo-
+gies, Inc. All other trademarks mentioned are the property of their respec-
+tive owners.
+
+2. Introduction
+
+This document describes how to download, compile and install the DRI. The
+DRI provides 3D graphics hardware acceleration for the XFree86 project. This
+information is intended for experienced Linux developers. Beginners are
+probably better off installing precompiled packages.
+
+Edits, corrections and updates to this document may be mailed to <brian@tung-
+stengraphics.com>.
+
+Last updated on 13 February 2002 by Brian Paul.
+
+3. Prerequisites
+
+You'll need the following:
+
+ o An installation of XFree86 4.1 or later. The DRI tree has been pruned
+ down to minimize its size. But in order to build the DRI tree you need
+ to have recent X header files, etc. already installed. If you don't
+ have XFree86 4.1 (or later) installed you can probably install it from
+ RPMs (or another package format). Or, you can download XFree86 as
+ sources and compile/install it yourself.
+
+ o At least 200MB of free disk space. If you compile for debugging (the -g
+ option) then you'll need about 600MB.
+
+ o GCC compiler and related tools.
+
+ o ssh (secure shell) if you're a DRI developer and don't want to use
+ anonymous CVS download.
+
+ o A 2.4.x Linux Kernel. See below for details.
+
+ o FreeBSD support is not currently being maintained and may not work.
+
+The DRI 3D drivers generally work on systems with Intel or AMD CPUs. How-
+ever, limited support for Alpha and PowerPC support is underway.
+
+For 3dfx Voodoo hardware, you'll also need the Glide3 runtime library
+(libglide3-v3.so for Voodoo3 or libglide3-v5.so for Voodoo4/5). These can be
+downloaded from the DRI website. You can compile them yourself, but it's
+often a painful process.
+
+For Matrox G200/G400, Intel i810/i830 or ATI Rage128/Radeon hardware, you'll
+also need AGP support in your Linux kernel, either built-in or as a loadable
+module.
+
+4. Linux Kernel Preparation
+
+Only the Linux 2.4.x kernels are currently supported by the DRI hardware
+drivers. 2.5.x kernels may work, but aren't tested.
+
+Most of the DRI drivers require AGP support and using Intel Pentium III SSE
+optimizations also requires an up-to-date Linux kernel. Configuring your
+kernel correctly is very important, as features such as SSE optimizations
+will be disabled if your kernel does not support them. Thus, if you have a
+Pentium III processor, you must configure your kernel for the Pentium III
+processor family.
+
+Building a new Linux kernel can be difficult for beginners but there are
+resources on the Internet to help. This document assumes experience with
+configuring, building and installing Linux kernels.
+
+Linux kernels can be downloaded from www.kernel.org
+
+Here are the basic steps for kernel setup.
+
+ o Download the needed kernel and put it in /usr/src. Create a directory
+ for the source and unpack it. For example:
+
+ cd /usr/src
+ rm -f linux
+ mkdir linux-2.4.x
+ ln -s linux-2.4.x linux
+ bzcat linux-2.4.x.tar.bz2 | tar xf -
+
+ It is critical that /usr/src/linux point to your new kernel sources,
+ otherwise the kernel headers will not be used when building the DRI.
+ This will almost certainly cause compilation problems.
+
+ o Read /usr/src/linux/Documentation/Changes. This file lists the minimum
+ requirements for all software packages required to build the kernel.
+ You must upgrade at least gcc, make, binutils and modutils to at least
+ the versions specified in this file. The other packages may not be
+ needed. If you are upgrading from Linux 2.2.x you must upgrade your
+ modutils package for Linux 2.4.x.
+
+ o Configure your kernel. You might, for example, use make menuconfig and
+ do the following:
+
+ o Go to Code maturity level options
+
+ o Enable Prompt for development and/or incomplete code/drivers
+
+ o hit ESC to return to the top-level menu
+
+ o Go to Processor type and features
+
+ o Select your processor type from Processor Family
+
+ o hit ESC to return to the top-level menu
+
+ o Go to Character devices
+
+ o Disable Direct Rendering Manager (XFree86 DRI support) since we'll
+ use the DRI code from the XFree86/DRI tree and will compile it
+ there.
+
+ o Go to /dev/agpgart (AGP Support) (EXPERIMENTAL) (NEW)
+
+ o Hit SPACE twice to build AGP support into the kernel
+
+ o Enable all chipsets' support for AGP
+
+ o It's recommended that you turn on MTRRs under Processor type and
+ Features, but not required.
+
+ o Configure the rest of the kernel as required for your system (i.e. Eth-
+ ernet, SCSI, etc)
+
+ o Exit, saving your kernel configuration.
+
+ o Edit your /etc/lilo.conf file. Make sure you have an image entry as
+ follows (or similar):
+
+ image=/boot/vmlinuz
+ label=linux.2.4.x
+ read-only
+ root=/dev/hda1
+
+ The important part is that you have /boot/vmlinuz without a trailing
+ version number. If this is the first entry in your /etc/lilo.conf AND
+ you haven't set a default, then this will be your default kernel.
+
+ o Compile the new kernel.
+
+ cd /usr/src/linux-2.4.x
+ make dep
+ make bzImage
+ make modules
+ make modules_install
+ make install
+
+ Note that last make command will automatically run lilo for you.
+
+ o Now reboot to use the new kernel.
+
+5. CPU Architectures
+
+In general, nothing special has to be done to use the DRI on different CPU
+architectures. There are, however, a few optimizations that are CPU-depen-
+dent. Mesa will determine at runtime which CPU-dependent optimizations
+should be used and enable them where appropriate.
+
+5.1 Intel Pentium III Features
+
+The Pentium III SSE instructions are used in optimized vertex transformation
+functions in the Mesa-based DRI drivers. On Linux, SSE requires a recent
+kernel (such as 2.4.0-test11 or later) both at compile time and runtime.
+
+5.2 AMD 3DNow! Features
+
+AMD's 3DNow! instructions are used in optimized vertex transformation func-
+tions in the Mesa-based DRI drivers. 3DNow! is supported in most versions of
+Linux.
+
+5.3 Alpha Features
+
+On newer Alpha processors a significant performance increase can be seen with
+the addition of the -mcpu= option to GCC. This option is dependent on the
+architecture of the processor. For example, -mcpu=ev6 will build specifi-
+cally for the EV6 based AXP's, giving both byte and word alignment access to
+the DRI/Mesa drivers.
+
+To enable this optimization edit your xc/config/host.def file and add the
+line:
+
+#define DefaultGcc2AxpOpt -O2 -mcpu=ev6
+
+Additional speed improvements to 3D rendering can be achieved by installing
+Compaq's Math Libraries (CPML) which can be obtained from http://www.sup-
+port.compaq.com/alpha-tools/software/index.html
+
+Once installed, you can add this line to your host.def to build with the CPML
+libraries:
+
+#define UseCompaqMathLibrary YES
+
+The host.def file is explained below.
+
+6. Downloading the XFree86/DRI CVS Sources
+
+The DRI project is hosted by SourceForge. The DRI source code, which is a
+subset of the XFree86 source tree, is kept in a CVS repository there.
+
+The DRI CVS sources may be accessed either anonymously or as a registered
+SourceForge user. It's recommended that you become a registered SourceForge
+user so that you may submit non-anonymous bug reports and can participate in
+the mailing lists.
+
+6.1 Anonymous CVS download:
+
+ 1. Create a directory to store the CVS files:
+
+ cd ~
+ mkdir DRI-CVS
+
+ You could put your CVS directory in a different place but we'll use
+ ~/DRI-CVS/ here.
+
+ 2. Check out the CVS sources:
+
+ cd ~/DRI-CVS
+ cvs -d:pserver:anonymous@cvs.dri.sourceforge.net:/cvsroot/dri login
+ (hit ENTER when prompted for a password)
+ cvs -z3 -d:pserver:anonymous@cvs.dri.sourceforge.net:/cvsroot/dri co xc
+
+ The -z3 flag causes compression to be used in order to reduce the down-
+ load time.
+
+6.2 Registered CVS download:
+
+ 1. Create a directory to store the CVS files:
+
+ cd ~
+ mkdir DRI-CVS
+
+ You could put your CVS directory in a different place but we'll use
+ ~/DRI-CVS/ here.
+
+ 2. Set the CVS_RSH environment variable:
+
+ setenv CVS_RSH ssh // if using csh or tcsh
+ export CVS_RSH=ssh // if using sh or bash
+
+ 3. Check out the CVS sources:
+
+ cd ~/DRI-CVS
+ cvs -z3 -d:ext:YOURID@cvs.dri.sourceforge.net:/cvsroot/dri co xc
+
+ Replace YOURID with your CVS login name. You'll be prompted to enter
+ your sourceforge password.
+
+ The -z3 flag causes compression to be used in order to reduce the down-
+ load time.
+
+6.3 Updating your CVS sources
+
+In the future you'll want to occasionally update your local copy of the DRI
+source code to get the latest changes. This can be done with:
+
+ cd ~/DRI-CVS
+ cvs -z3 update -dA xc
+
+The -d flag causes any new subdirectories to be created and -A causes most
+recent trunk sources to be fetched, not branch sources.
+
+7. Mesa
+
+Most of the DRI 3D drivers are based on Mesa (the free implementation of the
+OpenGL API). The relevant files from Mesa are already included in the
+XFree86/DRI source tree. There is no need to download or install the Mesa
+source files separately.
+
+Sometimes a newer version of Mesa will be available than the version included
+in XFree86/DRI. Upgrading Mesa within XFree86/DRI is not always straightfor-
+ward. It can be an error-prone undertaking, especially for beginners, and is
+not generally recommended. The DRI developers will upgrade Mesa when appro-
+priate.
+
+8. Compiling the XFree86/DRI tree
+
+8.1 Make a build tree
+
+Rather than placing object files and library files right in the source tree,
+they're instead put into a parallel build tree. The build tree is made with
+the lndir command:
+
+ cd ~/DRI-CVS
+ ln -s xc XFree40
+ mkdir build
+ cd build
+ lndir -silent -ignorelinks ../XFree40
+
+The build tree will be populated with symbolic links which point back into
+the CVS source tree.
+
+Advanced users may have several build trees for compiling and testing with
+different options.
+
+8.2 Edit the host.def file
+
+The ~/DRI-CVS/build/xc/config/cf/host.def file is used to configure the
+XFree86 build process. You can change it to customize your build options or
+make adjustments for your particular system configuration
+
+The default host.def file will look something like this:
+
+ #define DefaultCCOptions -Wall
+ (i386) #define DefaultGcc2i386Opt -O2
+ (Alpha) #define DefaultGcc2AxpOpt -O2 -mcpu=ev6 (or similar)
+ #define LibraryCDebugFlags -O2
+ #define BuildServersOnly YES
+ #define XF86CardDrivers vga tdfx mga ati i810
+ #define LinuxDistribution LinuxRedHat
+ #define DefaultCCOptions -ansi GccWarningOptions -pipe
+ #define BuildXF86DRI YES
+ /* Optionally turn these on for debugging */
+ /* #define GlxBuiltInTdfx YES */
+ /* #define GlxBuiltInMga YES */
+ /* #define GlxBuiltInR128 YES */
+ /* #define GlxBuiltInRadeon YES */
+ /* #define DoLoadableServer NO */
+ #define SharedLibFont NO
+
+The ProjectRoot variable specifies where the XFree86 files will be installed.
+We recommend installing the DRI files over your existing XFree86 installation
+- it's generally safe to do and less error-prone. This policy is different
+than what we used to recommend.
+
+If XFree86 4.x is not installed in /usr/X11R6/ you'll have to add the follow-
+ing to the host.def file:
+
+ #define ProjectRoot pathToYourXFree86installation
+
+Note the XF86CardDrivers line to be sure your card's driver is listed.
+
+If you want to enable 3DNow! optimizations in Mesa and the DRI drivers, you
+should add the following:
+
+ #define MesaUse3DNow YES
+
+You don't have to be using an AMD processor in order to enable this option.
+The DRI will look for 3DNow! support and runtime and only enable it if appli-
+cable.
+
+If you want to enable SSE optimizations in Mesa and the DRI drivers, you must
+upgrade to a Linux 2.4.x kernel. Mesa will verify that SSE is supported by
+both your processor and your operating system, but to build Mesa inside the
+DRI you need to have the Linux 2.4.x kernel headers in /usr/src/linux. If
+you enable SSE optimizations with an earlier version of the Linux kernel in
+/usr/src/linux, Mesa will not compile. You have been warned. If you do have
+a 2.4.x kernel, you should add the following:
+
+ #define MesaUseSSE YES
+
+If you want to build the DRM kernel modules as part of the full build pro-
+cess, add the following:
+
+ #define BuildXF86DRM YES
+
+Otherwise, you'll need to build them separately as described below.
+
+8.3 Compilation
+
+To compile the complete DRI tree:
+
+ cd ~/DRI-CVS/build/xc/
+ make World >& world.log
+
+Or if you want to watch the compilation progress:
+
+ cd ~/DRI-CVS/build/xc/
+ make World >& world.log &
+ tail -f world.log
+
+With the default compilation flags it's normal to get a lot of warnings dur-
+ing compilation.
+
+Building will take some time so you may want to go check your email or visit
+slashdot.
+
+WARNING: do not use the -j option with make. It's reported that it does not
+work with XFree86/DRI.
+
+8.4 Check for compilation errors
+
+Using your text editor, examine world.log for errors by searching for the
+pattern ***.
+
+After fixing the errors, run make World again. Later, you might just compile
+parts of the source tree but it's important that the whole tree will build
+first.
+
+If you edited your host.def file to enable automatic building of the DRI ker-
+nel module(s), verify that they were built:
+
+ cd ~/DRI-CVS/build/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel
+ ls
+
+Otherwise, build them now by running
+
+ cd ~/DRI-CVS/build/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel
+ make -f Makefile.linux
+
+For the 3dfx Voodoo, you should see tdfx.o. For the Matrox G200/G400, you
+should see mga.o. For the ATI Rage 128, you should see r128.o. For the ATI
+Radeon, you should see radeon.o. For the Intel i810, you should see i810.o.
+
+If the DRI kernel module(s) failed to build you should verify that you're
+using the right version of the Linux kernel. The most recent kernels are not
+always supported.
+
+If your build machine is running a different version of the kernel than your
+target machine (i.e. 2.2.x vs. 2.4.x), make will select the wrong kernel
+source tree. This can be fixed by explicitly setting the value of LINUXDIR.
+If the path to your kernel source is /usr/src/linux-2.4.x,
+
+ cd ~/DRI-CVS/build/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel
+ make -f Makefile.linux LINUXDIR=/usr/src/linux-2.4.x
+
+or alternatively, edit Makefile.linux to set LINUXDIR before the ifndef LIN-
+UXDIR line.
+
+8.5 DRI kernel module installation
+
+The DRI kernel modules will be in ~/DRI-CVS/build/xc/pro-
+grams/Xserver/hw/xfree86/os-support/linux/drm/kernel/.
+
+To load the appropriate DRM module in your running kernel you can either use
+ismod and restart your X server or copy the kernel module to /lib/mod-
+ules/2.4.x/kernel/drivers/char/drm/ then run depmod and restart your X
+server.
+
+Make sure you first unload any older DRI kernel modules that might be already
+loaded.
+
+Note that some DRM modules require that the agpgart module be loaded first.
+
+9. Normal Installation and Configuration
+
+Most users will want to install the new X server and use it in place of their
+old X server. This section explains how to do that.
+
+Developers, on the other hand, may just want to test the X server without
+actually installing it as their default server. If you want to do that, skip
+to the next section.
+
+9.1 Installation
+
+Here are the installation commands:
+
+ su
+ cd ~/DRI-CVS/build/xc
+ make install
+
+9.2 Update the XF86Config File
+
+You may need to edit your XF86Config file to enable the DRI. The config file
+is usually installed as /etc/X11/XF86Config-4. See the DRI User Guide for
+details, but basically, you need to load the "glx" and "dri" modules and add
+a "DRI" section.
+
+On the DRI web site, in the resources section, you'll find example XF86Config
+files for a number of graphics cards. These configuration files also setup
+DRI options so it's highly recommended that you look at these examples.
+
+The XFree86 4.x server can generate a basic configuration file itself. Sim-
+ply do this:
+
+ cd /usr/X11R6/bin
+ ./XFree86 -configure
+
+A file named /root/XF86Config.new will be created. It should allow you to
+try your X server but you'll almost certainly have to edit it. For example,
+you should add HorizSync and VertRefresh options to the Monitor section and
+Modes options to the Screen section. Also, the ModulePath option in the
+Files section should be set to /usr/X11R6/lib/modules.
+
+9.3 Start the New X Server
+
+The new X server should be ready to use now. Start your X server in your
+usual manner. Often times the startx command is used:
+
+ startx
+
+10. Testing the Server Without Installing It
+
+As mentioned at the start of section 9, developers may want to simply run the
+X server without installing it. This can save some time and allow you to
+keep a number of X servers available for testing.
+
+10.1 Configuration
+
+As described in the preceding section, you'll need to create a configuration
+file for the new server. Put the XF86Config file in your ~/DRI-
+CVS/build/xc/programs/Xserver directory.
+
+Be sure the ModulePath option in your XF86Config file is set correctly.
+
+10.2 A Startup Script
+
+A simple shell script can be used to start the X server. Here's an example.
+
+ #!/bin/sh
+ export DISPLAY=:0
+ ./XFree86 -xf86config XF86Config & \
+ sleep 2
+ fvwm2 &
+ xset b off
+ xmodmap -e "clear mod4"
+ xsetroot -solid "#00306f"
+ xterm -geometry 80x40+0+0
+
+You might name this script start-dri. Put it in your ~/DRI-CVS/build/xc/pro-
+grams/Xserver directory.
+
+To test the server run the script:
+
+ cd ~/DRI-CVS/build/xc/programs/Xserver
+ ./start-dri
+
+For debugging, you may also want to capture the log messages printed by the
+server in a file. If you're using the C-shell:
+
+ ./start-dri >& log
+
+11. Where To Go From Here
+
+At this point your X server should be up and running with hardware-acceler-
+ated direct rendering. Please read the DRI User Guide for information about
+trouble shooting and how to use the DRI-enabled X server for 3D applications.
+
+ Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DRIcomp.sgml,v 1.19 dawes Exp $
+
+
diff --git a/xorg-server/hw/xfree86/doc/devel/Registry b/xorg-server/hw/xfree86/doc/devel/Registry
new file mode 100644
index 000000000..1fec230e8
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/devel/Registry
@@ -0,0 +1,409 @@
+This is the XFree86 driver/module registry. To avoid name space clashes and
+to maintain some consistency between drivers the important name spaces are
+maintained here.
+
+1. Module Names.
+
+Each module is required to have a unique name. Registered names are:
+
+GLcore
+acecad
+afb
+apm
+ark
+ati
+atimisc
+bitmap
+bt8xx
+calcomp
+cfb
+cfb16
+cfb24
+cfb32
+chips
+cirrus
+citron
+cyrix
+dbe
+ddc
+digitaledge
+dmc
+dri
+drm
+dynapro
+elo2300
+elographics
+extmod
+fb
+fbdev
+fbdevhw
+fi12x6
+freetype
+glide
+glint
+glx
+hyperpen
+i128
+i2c
+i740
+i810
+imstt
+int10
+joystick
+keyboard
+layer
+magellan
+magictouch
+mfb
+mga
+microtouch
+mouse
+msp34xx
+mutouch
+neomagic
+newport
+nv
+pcidata
+penmount
+pex5
+r128
+radeon
+rac
+ramdac
+record
+rendition
+s3
+s3virge
+savage
+shadow
+shadowfb
+siliconmotion
+sis
+spaceorb
+speedo
+summa
+sunbw2
+suncg14
+suncg3
+suncg6
+sunffb
+sunleo
+suntcx
+tdfx
+tga
+trident
+tseng
+type1
+v4l
+vbe
+vesa
+vga
+vgahw
+vmware
+void
+wacom
+xaa
+xf1bpp
+xf24_32bpp
+xf4bpp
+xf8_16bpp
+xf8_32bpp
+xf8_32wid
+xie
+xtrap
+xtt
+
+2. External Module Object Symbols.
+
+Each module is required to use a unique prefix or prefixes for all of
+its externally visible symbols. They should be unique without regard to
+case. Registered prefixes are:
+
+ati
+bt8xx
+cfb
+chips
+fi12x6
+glide
+glint
+mfb
+mga
+msp34xx
+neo
+permedia
+tseng
+vga
+vgahw
+vmware
+xaa
+xf1bpp
+xf4bpp
+
+3. Chipset Names.
+
+Each video driver is required to use a unique set of chipset names. Case,
+white space and underscore characters are ignored when comparing chipset
+names. All names listed here are in lower case with all white space and
+underscores removed. Registered chipset names are:
+
+ati
+ativga
+ct64200
+ct64300
+ct65520
+ct65525
+ct65530
+ct65535
+ct65540
+ct65545
+ct65546
+ct65548
+ct65550
+ct65554
+ct65555
+ct68554
+ct69000
+et4000
+et4000w32
+et4000w32i
+et4000w32p
+et6000
+et6100
+generic
+ibmvga
+ibm8514
+mach32
+mach64
+mach8
+mga2064w
+mga1064sg
+mga2164w
+mga2164wagp
+neo2070
+neo2090
+neo2093
+neo2097
+neo2160
+neo2200
+tipm2
+vgawonder
+voodoo
+
+4. Option Names.
+
+Option names and their usage should be consistent between drivers.
+Case, white space and underscore characters are ignored when comparing
+option names. The prefix "no" may be added or removed from boolean
+option names. All names listed here are in their preferred user-visible
+form. Some registered option names are:
+
+Types are: B = boolean, O = set/unset (no value), I = integer, S = string,
+ A = optional string, F = floating point number Q = frequency
+
+Scopes are: F = global flags, V = video driver, C = common (per screen),
+ I = input drivers, X = XAA, Xv = Xv extension, M = misc.
+
+Names currently in use:
+
+Name Type Scope Description
+----------------------------------------------------------------------------
+AllowMouseOpenFail B F ignore mouse dev open failure
+AllowNonLocalModInDev B F allow non-local mod of input devs
+AllowNonLocalXvidtune B F allow non-local VidMode connections
+BlankTime I F Screen saver timeout (min)
+DisableModInDev B F disallow changing input devs
+DisableVidModeExtension B F disable VidMode extension
+DontVTSwitch B F disable Ctrl-Alt-Fn
+DontZap B F disable Ctrl-Alt-BS sequence
+DontZoom B F disable Ctrl-Alt-+/-
+NoTrapSignals B F don't trap signals
+OffTime I F Time before DPMS off mode active (min)
+PciProbe1 O F use PCI probe algorithm 1
+PciProbe2 O F use PCI probe algorithm 2
+PciForceConfig1 O F force PCI config type 1
+PciForceConfig2 O F force PCI config type 2
+Pixmap I F depth 24 pixmap size (24 or 32)
+StandbyTime I F Time before DPMS standby active (min)
+SuspendTime I F Time before DPMS suspend mode active (min)
+
+BackingStore B C Enable backing store
+DDC B C Enable/disable DDC
+DDC1 B C Enable/disable DDC1
+DDC2 B C Enable/disable DDC2
+DPMS O C Enable DPMS
+MTRR B C Enable/disable setting MTRRs
+
+BaudRate I I Serial port baud rate
+ButtonNumber I I Button number (for touch screen?)
+ButtonThreshold I I ??
+ClearDTR O I Clear serial port DTR
+ClearRTS O I Clear serial port RTS
+DataBits I I Serial port data bits
+DemandLoad O I ??
+Device S I Device file name
+DeviceName S I Input device name
+FlowControl S I Serial flow control ("xon", "none")
+HistorySize I I ??
+MaxX I I Maximum X coordinate
+MaxY I I Maximum Y coordinate
+MinX I I Minimum X coordinate
+MinY I I Minimum Y coordinate
+Parity S I Serial port parity ("odd", "even", "none")
+ReportDelay I I ??
+ReportingMode S I may be "raw" or "scaled"
+ScreenNumber I I Screen number (for touch screen)
+SendCoreEvents B I Send core events
+SendDragEvents B I Send drag events
+StopBits I I Serial port stop bits
+SwapXY B I Swap the X and Y axes
+UntouchDelay I I ??
+Vmin I I Tty VMIN
+Vtime I I Tty VTIME
+
+
+18BitBus B V ??
+8Plus16 B V Enable depth 8 + depth 16 with overlay
+8Plus24 B V Enable depth 8 + depth 24 with overlay
+BlockWrite B V Enable/disable block write
+ColorKey I V Set the color key for overlay modes
+CompositeSync B V Composite sync
+CRTDisplay B V Force display on CRT, not LCD
+CRTScreen B V Display on CRT, not LCD (Obsolete)
+EarlyRasPrecharge O V Early RAS pre-charge
+FastDRAM O V Fast DRAM
+FifoAggressive O V Aggressive FIFO setting
+FifoConservative O V Conservative FIFO setting
+FifoModerate O V Moderate FIFO setting
+FireGL3000 B V Card is Diamond FireGL3000
+FixPanelSize B V ??
+FPClock8 Q V Flat panel clock for 8bpp fb (MHz)
+FPClock16 Q V Flat panel clock for 16bpp fb (MHz)
+FPClock24 Q V Flat panel clock for 24bpp fb (MHz)
+FPClock32 Q V Flat panel clock for 32bpp fb (MHz)
+FPMVRAM O V Fast page mode VRAM
+FramebufferWC B V Enable/disable WC for the framebuffer
+GlideDevice I V Selects which Voodoo board to use
+HiBitHigh O V High clock bit default to set
+HiBitLow O V High clock bit default to cleared
+HWClocks B V Enable/disable HW clocks
+HWCursor B V Enable/disable HW cursor
+LateRasPrecharge O V Late RAS pre-charge
+Legend O V Card is Legend ET4000
+LCDCenter B V Enable/disable centering for LCD displays
+Linear B V Enable/disable linear framebuffer
+MCLK Q V Specify the current MCLK value (MHz)
+MedDRAM B V Medium speed DRAM
+MemCfg1 I V ??
+MemCfg2 I V ??
+MGASDRAM B V Mga card has SDRAM
+MMIO B V Enable/disable memory mapped I/O
+MMIOCache B V Enable/Disable MMIO cache
+MuxThreshold I V Multiplexing threshold (kHz)
+NoAccel B V Disable/enable acceleration
+NoClockChip B V ??
+NoStretch B V Disable/enable stretching for LCD displays
+OnAtExit B V Leave video signal on when exiting server
+OverclockMem B V Enable memory overclocking
+Overlay A V Enable multi-depth/overlay. An optional
+ string "M,N" may be specified, where
+ M, N are the depths.
+PanelDisplay B V Force display on LCD
+PciBurst B V Enable/disable PCI burst mode
+PciRetry B V Enable/disable PCI retries
+ProbeClocks B V Force probe for non-programmable clocks
+ReferenceClock Q V Clock generator reference frequency
+RGBbits I V Number of significant bits per rgb
+Rotate S V Rotate the virtual display (CW or CCW)
+SetLCDClk Q V Set LCD clock (MHz)
+SetMclk Q V Set Memory Clock (MHz)
+ShadowFB B V Enable shadow framebuffer layer
+ShowCache B V Enable viewing of offscreen memory
+ShowOverscan O V Set the overscan area to a visible colour
+SlowDRAM O V Slow DRAM
+SlowEDODRAM O V Slow EDO DRAM
+STN B V STN screen type (??)
+SWCursor B V Enable/disable SW cursor
+SuspendHack B V ??
+SyncOnGreen B V Enable/disable sync on green
+TurboQueue B V Enable/disable turbo queue
+UseFBDev B V Use the fbdev driver interface
+UseModeLine B V Use Modeline (??)
+W32Interleave B V ??
+
+Buffers I Xv Number of buffers
+Device S Xv Device file name
+Expose B Xv Disable occlusion clipping (see DESIGN)
+FramesPerSec I Xv Max. refresh frequency
+
+XAA options. All are of type "O" and scope "X", and are self-explanatory
+
+XaaNoColor8x8PatternFillRect
+XaaNoColor8x8PatternFillTrap
+XaaNoCPUToScreenColorExpandFill
+XaaNoDashedBresenhamLine
+XaaNoDashedTwoPointLine
+XaaNoScreenToScreenCopy
+XaaNoImageReadRect
+XaaNoImageWriteRect
+XaaNoMono8x8PatternFillRect
+XaaNoMono8x8PatternFillTrap
+XaaNoOffscreenPixmaps
+XaaNoPixmapCache
+XaaNoScanlineCPUToScreenColorExpandFill
+XaaNoScanlineImageWriteRect
+XaaNoScreenToScreenColorExpandFill
+XaaNoSolidBresenhamLine
+XaaNoSolidFillRect
+XaaNoSolidFillTrap
+XaaNoSolidHorVertLine
+XaaNoSolidTwoPointLine
+
+
+Names used in previous versions:
+
+16Clocks
+8Clocks
+ClkDiv2
+EDO VRAM
+ExternDisp
+ExtFramBuf
+FastVRAM
+FavorBitBlt
+InternDisp
+NoBitBlt
+NoFontCache
+NoImageBlt
+NoMemAccess
+NoPciDisconnect
+NoPixmapCache
+NoProgramClocks
+NoSplitXfer
+OverrideBIOS
+OverrideValidateMode
+ProgLcdModeRegs
+ProgLcdModeStretch
+SlowDRAMrefresh
+SlowVRAM
+SwapHiBit
+
+
+5. Ramdac Names.
+
+Ramdac names should be consistent between drivers. Case, white space
+and underscore characters are ignored when comparing ramdac names. All
+names listed here are in lower case with all white space and underscores
+removed.
+
+
+6. Clock Chip Names.
+
+Clock chip names should be consistent between drivers. Case, white
+space and underscore characters are ignored when comparing clock chip
+names. All names listed here are in lower case with all white space
+and underscores removed.
+
+
+
+
+
+$XFree86: xc/programs/Xserver/hw/xfree86/Registry,v 1.18 2002/04/06 18:31:09 tsi Exp $
diff --git a/xorg-server/hw/xfree86/doc/devel/exa-driver.txt b/xorg-server/hw/xfree86/doc/devel/exa-driver.txt
new file mode 100644
index 000000000..048307ee7
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/devel/exa-driver.txt
@@ -0,0 +1,94 @@
+Adding EXA support to your X.Org video driver
+---------------------------------------------
+EXA (for EXcellent Architecture or Ex-kaa aXeleration Architecture or
+whatever) aims to extend the life of the venerable XFree86 video drivers by
+introducing a new set of acceleration hooks that efficiently accelerate the X
+Render extension, including solid fills, blits within screen memory and to and
+from system memory, and Porter-Duff compositing and transform operations.
+
+Configuration
+-------------
+A new config file option, AccelMethod, should be added to your driver, to allow
+the user to select between the EXA and XAA acceleration APIs.
+
+Some drivers implement a per-instance useEXA flag to track whether EXA is
+active or not. It can be helpful to also conditionalize XAA support with an
+ifdef so that it can easily be turned off/removed in the future.
+
+Setting the flag and checking for AccelMethod can be done in the driver's
+Options parsing routine.
+
+Loading EXA
+------------
+EXA drivers in the XFree86 DDX should use the loadable module loader to load
+the EXA core. Careful versioning allows the EXA API to be extended without
+breaking the ABI for older versions of drivers. Example code for loading EXA:
+
+static const char *exaSymbols[] = {
+ "exaDriverAlloc",
+ "exaDriverInit",
+ "exaDriverFini",
+ "exaOffscreenAlloc",
+ "exaOffscreenFree",
+ "exaGetPixmapOffset",
+ "exaGetPixmapPitch",
+ "exaGetPixmapSize",
+ "exaMarkSync",
+ "exaWaitSync",
+ NULL
+};
+
+ if (info->useEXA) {
+ info->exaReq.majorversion = 2;
+ info->exaReq.minorversion = 0;
+
+ if (!LoadSubModule(pScrn->module, "exa", NULL, NULL, NULL,
+ &info->exaReq, &errmaj, &errmin)) {
+ LoaderErrorMsg(NULL, "exa", errmaj, errmin);
+ return FALSE;
+ }
+ xf86LoaderReqSymLists(exaSymbols, NULL);
+ }
+
+EXA is then initialized using exaDriverAlloc and exaDriverInit. See doxygen
+documentation for getting started there.
+
+Further documentation
+------------
+The EXA driver interface and public API is documented using doxygen in
+xserver/xorg/exa/. To build the documentation, run:
+ doxygen -g
+ doxygen Doxyfile
+The resulting documentation will appear an html/index.html under the current
+directory.
+
+EXA initialization
+------------------
+Your driver's AccelInit routine must initialize an ExaDriverRec structure if
+EXA support is enabled, with appropriate error handling (i.e. NoAccel and
+NoXvideo should be set to true if EXA fails to initialize for whatever
+reason).
+
+The AccelInit routine also needs to make sure that there's enough offscreen
+memory for certain operations to function, like Xvideo, which should advertise
+a maximum size no larger than can be dealt with given the amount of offscreen
+memory available.
+
+EXA and Xv
+----------
+Video support becomes easier with EXA since AllocateFBMemory can use
+exaOffscreenAlloc directly, freeing a previous area if necessary and
+allocating a new one. Likewise, FreeFBMemory can call exaOffscreenFree.
+
+EXA teardown
+------------
+At screen close time, EXA drivers should call exaDriverFini with their screen
+pointer, free their EXADriver structure, and do any other necessary teardown.
+
+EXA misc.
+---------
+In many drivers, DGA support will need to be changed to be aware of the new
+EXA support.
+
+Send updates and corrections to Jesse Barnes <jbarnes@virtuousgeek.org> or
+just check them in if you have permission.
diff --git a/xorg-server/hw/xfree86/doc/man/Makefile.am b/xorg-server/hw/xfree86/doc/man/Makefile.am
new file mode 100644
index 000000000..d8b2aa73d
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/man/Makefile.am
@@ -0,0 +1,24 @@
+# Xserver.man covers options generic to all X servers built in this tree
+MAN_SRCS = Xorg.man.pre xorg.conf.man.pre
+
+appmandir = $(APP_MAN_DIR)
+appman_DATA = Xorg.$(APP_MAN_SUFFIX)
+
+filemandir = $(FILE_MAN_DIR)
+fileman_DATA = xorg.conf.$(FILE_MAN_SUFFIX)
+
+Xorg.$(APP_MAN_SUFFIX): Xorg.man
+ -rm -f Xorg.$(APP_MAN_SUFFIX)
+ $(LN_S) Xorg.man Xorg.$(APP_MAN_SUFFIX)
+
+xorg.conf.$(FILE_MAN_SUFFIX): xorg.conf.man
+ -rm -f xorg.conf.$(FILE_MAN_SUFFIX)
+ $(LN_S) xorg.conf.man xorg.conf.$(FILE_MAN_SUFFIX)
+
+include $(top_srcdir)/cpprules.in
+
+EXTRAMANDEFS = -D__logdir__=$(logdir)
+
+CLEANFILES = $(appman_DATA) $(fileman_DATA) xorg.conf.man Xorg.man
+
+EXTRA_DIST = $(MAN_SRCS)
diff --git a/xorg-server/hw/xfree86/doc/man/Makefile.in b/xorg-server/hw/xfree86/doc/man/Makefile.in
new file mode 100644
index 000000000..09fbe07f1
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/man/Makefile.in
@@ -0,0 +1,646 @@
+# Makefile.in generated by automake 1.10.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+# -*- Makefile -*-
+# Rules for generating files using the C pre-processor
+# (Replaces CppFileTarget from Imake)
+
+VPATH = @srcdir@
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in \
+ $(top_srcdir)/cpprules.in
+subdir = hw/xfree86/doc/man
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \
+ $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+ $(ACLOCAL_M4)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/include/do-not-use-config.h \
+ $(top_builddir)/include/xorg-server.h \
+ $(top_builddir)/include/dix-config.h \
+ $(top_builddir)/include/xgl-config.h \
+ $(top_builddir)/include/xorg-config.h \
+ $(top_builddir)/include/xkb-config.h \
+ $(top_builddir)/include/xwin-config.h \
+ $(top_builddir)/include/kdrive-config.h
+CONFIG_CLEAN_FILES =
+SOURCES =
+DIST_SOURCES =
+am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
+am__vpath_adj = case $$p in \
+ $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
+ *) f=$$p;; \
+ esac;
+am__strip_dir = `echo $$p | sed -e 's|^.*/||'`;
+am__installdirs = "$(DESTDIR)$(appmandir)" "$(DESTDIR)$(filemandir)"
+appmanDATA_INSTALL = $(INSTALL_DATA)
+filemanDATA_INSTALL = $(INSTALL_DATA)
+DATA = $(appman_DATA) $(fileman_DATA)
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+ACLOCAL = @ACLOCAL@
+ADMIN_MAN_DIR = @ADMIN_MAN_DIR@
+ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@
+ALLOCA = @ALLOCA@
+AMTAR = @AMTAR@
+APPDEFAULTDIR = @APPDEFAULTDIR@
+APPLE_APPLICATIONS_DIR = @APPLE_APPLICATIONS_DIR@
+APP_MAN_DIR = @APP_MAN_DIR@
+APP_MAN_SUFFIX = @APP_MAN_SUFFIX@
+AR = @AR@
+AS = @AS@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BASE_FONT_PATH = @BASE_FONT_PATH@
+BUILD_DATE = @BUILD_DATE@
+BUILD_TIME = @BUILD_TIME@
+CC = @CC@
+CCAS = @CCAS@
+CCASDEPMODE = @CCASDEPMODE@
+CCASFLAGS = @CCASFLAGS@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+COMPILEDDEFAULTFONTPATH = @COMPILEDDEFAULTFONTPATH@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CXX = @CXX@
+CXXCPP = @CXXCPP@
+CXXDEPMODE = @CXXDEPMODE@
+CXXFLAGS = @CXXFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DARWIN_LIBS = @DARWIN_LIBS@
+DBUS_CFLAGS = @DBUS_CFLAGS@
+DBUS_LIBS = @DBUS_LIBS@
+DEFAULT_LIBRARY_PATH = @DEFAULT_LIBRARY_PATH@
+DEFAULT_LOGPREFIX = @DEFAULT_LOGPREFIX@
+DEFAULT_MODULE_PATH = @DEFAULT_MODULE_PATH@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DGA_CFLAGS = @DGA_CFLAGS@
+DGA_LIBS = @DGA_LIBS@
+DIX_CFLAGS = @DIX_CFLAGS@
+DLLTOOL = @DLLTOOL@
+DMXEXAMPLES_DEP_CFLAGS = @DMXEXAMPLES_DEP_CFLAGS@
+DMXEXAMPLES_DEP_LIBS = @DMXEXAMPLES_DEP_LIBS@
+DMXMODULES_CFLAGS = @DMXMODULES_CFLAGS@
+DMXMODULES_LIBS = @DMXMODULES_LIBS@
+DMXXIEXAMPLES_DEP_CFLAGS = @DMXXIEXAMPLES_DEP_CFLAGS@
+DMXXIEXAMPLES_DEP_LIBS = @DMXXIEXAMPLES_DEP_LIBS@
+DMXXMUEXAMPLES_DEP_CFLAGS = @DMXXMUEXAMPLES_DEP_CFLAGS@
+DMXXMUEXAMPLES_DEP_LIBS = @DMXXMUEXAMPLES_DEP_LIBS@
+DRI2PROTO_CFLAGS = @DRI2PROTO_CFLAGS@
+DRI2PROTO_LIBS = @DRI2PROTO_LIBS@
+DRIPROTO_CFLAGS = @DRIPROTO_CFLAGS@
+DRIPROTO_LIBS = @DRIPROTO_LIBS@
+DRIVER_MAN_DIR = @DRIVER_MAN_DIR@
+DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@
+DRI_DRIVER_PATH = @DRI_DRIVER_PATH@
+DSYMUTIL = @DSYMUTIL@
+DTRACE = @DTRACE@
+ECHO = @ECHO@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+EXEEXT = @EXEEXT@
+F77 = @F77@
+FFLAGS = @FFLAGS@
+FILE_MAN_DIR = @FILE_MAN_DIR@
+FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@
+FREETYPE_CFLAGS = @FREETYPE_CFLAGS@
+FREETYPE_LIBS = @FREETYPE_LIBS@
+GLX_ARCH_DEFINES = @GLX_ARCH_DEFINES@
+GLX_DEFINES = @GLX_DEFINES@
+GL_CFLAGS = @GL_CFLAGS@
+GL_LIBS = @GL_LIBS@
+GREP = @GREP@
+HAL_CFLAGS = @HAL_CFLAGS@
+HAL_LIBS = @HAL_LIBS@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+KDRIVE_CFLAGS = @KDRIVE_CFLAGS@
+KDRIVE_INCS = @KDRIVE_INCS@
+KDRIVE_LIBS = @KDRIVE_LIBS@
+KDRIVE_LOCAL_LIBS = @KDRIVE_LOCAL_LIBS@
+KDRIVE_PURE_INCS = @KDRIVE_PURE_INCS@
+KDRIVE_PURE_LIBS = @KDRIVE_PURE_LIBS@
+LAUNCHD = @LAUNCHD@
+LDFLAGS = @LDFLAGS@
+LD_EXPORT_SYMBOLS_FLAG = @LD_EXPORT_SYMBOLS_FLAG@
+LEX = @LEX@
+LEXLIB = @LEXLIB@
+LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@
+LIBDRM_CFLAGS = @LIBDRM_CFLAGS@
+LIBDRM_LIBS = @LIBDRM_LIBS@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIB_MAN_DIR = @LIB_MAN_DIR@
+LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@
+LINUXDOC = @LINUXDOC@
+LN_S = @LN_S@
+LTLIBOBJS = @LTLIBOBJS@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+MAKE_HTML = @MAKE_HTML@
+MAKE_PDF = @MAKE_PDF@
+MAKE_PS = @MAKE_PS@
+MAKE_TEXT = @MAKE_TEXT@
+MESA_SOURCE = @MESA_SOURCE@
+MISC_MAN_DIR = @MISC_MAN_DIR@
+MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@
+MKDIR_P = @MKDIR_P@
+MKFONTDIR = @MKFONTDIR@
+MKFONTSCALE = @MKFONTSCALE@
+NMEDIT = @NMEDIT@
+OBJC = @OBJC@
+OBJCCLD = @OBJCCLD@
+OBJCDEPMODE = @OBJCDEPMODE@
+OBJCFLAGS = @OBJCFLAGS@
+OBJCLINK = @OBJCLINK@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OPENSSL_CFLAGS = @OPENSSL_CFLAGS@
+OPENSSL_LIBS = @OPENSSL_LIBS@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PCIACCESS_CFLAGS = @PCIACCESS_CFLAGS@
+PCIACCESS_LIBS = @PCIACCESS_LIBS@
+PCI_TXT_IDS_PATH = @PCI_TXT_IDS_PATH@
+PERL = @PERL@
+PKG_CONFIG = @PKG_CONFIG@
+PROJECTROOT = @PROJECTROOT@
+PS2PDF = @PS2PDF@
+RANLIB = @RANLIB@
+RAWCPP = @RAWCPP@
+RAWCPPFLAGS = @RAWCPPFLAGS@
+SED = sed
+SERVER_MISC_CONFIG_PATH = @SERVER_MISC_CONFIG_PATH@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+SOLARIS_ASM_CFLAGS = @SOLARIS_ASM_CFLAGS@
+SOLARIS_INOUT_ARCH = @SOLARIS_INOUT_ARCH@
+STRIP = @STRIP@
+TSLIB_CFLAGS = @TSLIB_CFLAGS@
+TSLIB_LIBS = @TSLIB_LIBS@
+UTILS_SYS_LIBS = @UTILS_SYS_LIBS@
+VENDOR_MAN_VERSION = @VENDOR_MAN_VERSION@
+VENDOR_NAME = @VENDOR_NAME@
+VENDOR_NAME_SHORT = @VENDOR_NAME_SHORT@
+VENDOR_RELEASE = @VENDOR_RELEASE@
+VERSION = @VERSION@
+X11APP_ARCHS = @X11APP_ARCHS@
+X11EXAMPLES_DEP_CFLAGS = @X11EXAMPLES_DEP_CFLAGS@
+X11EXAMPLES_DEP_LIBS = @X11EXAMPLES_DEP_LIBS@
+XDMCP_CFLAGS = @XDMCP_CFLAGS@
+XDMCP_LIBS = @XDMCP_LIBS@
+XDMXCONFIG_DEP_CFLAGS = @XDMXCONFIG_DEP_CFLAGS@
+XDMXCONFIG_DEP_LIBS = @XDMXCONFIG_DEP_LIBS@
+XDMX_CFLAGS = @XDMX_CFLAGS@
+XDMX_LIBS = @XDMX_LIBS@
+XDMX_SYS_LIBS = @XDMX_SYS_LIBS@
+XEGLMODULES_CFLAGS = @XEGLMODULES_CFLAGS@
+XEGL_LIBS = @XEGL_LIBS@
+XEGL_SYS_LIBS = @XEGL_SYS_LIBS@
+XEPHYR_CFLAGS = @XEPHYR_CFLAGS@
+XEPHYR_DRI_LIBS = @XEPHYR_DRI_LIBS@
+XEPHYR_INCS = @XEPHYR_INCS@
+XEPHYR_LIBS = @XEPHYR_LIBS@
+XF86CONFIGFILE = @XF86CONFIGFILE@
+XF86MISC_CFLAGS = @XF86MISC_CFLAGS@
+XF86MISC_LIBS = @XF86MISC_LIBS@
+XF86VIDMODE_CFLAGS = @XF86VIDMODE_CFLAGS@
+XF86VIDMODE_LIBS = @XF86VIDMODE_LIBS@
+XGLMODULES_CFLAGS = @XGLMODULES_CFLAGS@
+XGLMODULES_LIBS = @XGLMODULES_LIBS@
+XGLXMODULES_CFLAGS = @XGLXMODULES_CFLAGS@
+XGLXMODULES_LIBS = @XGLXMODULES_LIBS@
+XGLX_LIBS = @XGLX_LIBS@
+XGLX_SYS_LIBS = @XGLX_SYS_LIBS@
+XGL_LIBS = @XGL_LIBS@
+XGL_MODULE_PATH = @XGL_MODULE_PATH@
+XGL_SYS_LIBS = @XGL_SYS_LIBS@
+XKB_BASE_DIRECTORY = @XKB_BASE_DIRECTORY@
+XKB_BIN_DIRECTORY = @XKB_BIN_DIRECTORY@
+XKB_COMPILED_DIR = @XKB_COMPILED_DIR@
+XKM_OUTPUT_DIR = @XKM_OUTPUT_DIR@
+XLIB_CFLAGS = @XLIB_CFLAGS@
+XLIB_LIBS = @XLIB_LIBS@
+XNESTMODULES_CFLAGS = @XNESTMODULES_CFLAGS@
+XNESTMODULES_LIBS = @XNESTMODULES_LIBS@
+XNEST_LIBS = @XNEST_LIBS@
+XNEST_SYS_LIBS = @XNEST_SYS_LIBS@
+XORGCFG_DEP_CFLAGS = @XORGCFG_DEP_CFLAGS@
+XORGCFG_DEP_LIBS = @XORGCFG_DEP_LIBS@
+XORGCONFIG_DEP_CFLAGS = @XORGCONFIG_DEP_CFLAGS@
+XORGCONFIG_DEP_LIBS = @XORGCONFIG_DEP_LIBS@
+XORG_CFLAGS = @XORG_CFLAGS@
+XORG_INCS = @XORG_INCS@
+XORG_LIBS = @XORG_LIBS@
+XORG_MODULES_CFLAGS = @XORG_MODULES_CFLAGS@
+XORG_MODULES_LIBS = @XORG_MODULES_LIBS@
+XORG_OS = @XORG_OS@
+XORG_OS_SUBDIR = @XORG_OS_SUBDIR@
+XORG_SYS_LIBS = @XORG_SYS_LIBS@
+XPRINTMODULES_CFLAGS = @XPRINTMODULES_CFLAGS@
+XPRINTMODULES_LIBS = @XPRINTMODULES_LIBS@
+XPRINTPROTO_CFLAGS = @XPRINTPROTO_CFLAGS@
+XPRINTPROTO_LIBS = @XPRINTPROTO_LIBS@
+XPRINT_CFLAGS = @XPRINT_CFLAGS@
+XPRINT_LIBS = @XPRINT_LIBS@
+XPRINT_SYS_LIBS = @XPRINT_SYS_LIBS@
+XRESEXAMPLES_DEP_CFLAGS = @XRESEXAMPLES_DEP_CFLAGS@
+XRESEXAMPLES_DEP_LIBS = @XRESEXAMPLES_DEP_LIBS@
+XSDL_INCS = @XSDL_INCS@
+XSDL_LIBS = @XSDL_LIBS@
+XSERVERCFLAGS_CFLAGS = @XSERVERCFLAGS_CFLAGS@
+XSERVERCFLAGS_LIBS = @XSERVERCFLAGS_LIBS@
+XSERVERLIBS_CFLAGS = @XSERVERLIBS_CFLAGS@
+XSERVERLIBS_LIBS = @XSERVERLIBS_LIBS@
+XSERVER_LIBS = @XSERVER_LIBS@
+XSERVER_SYS_LIBS = @XSERVER_SYS_LIBS@
+XTSTEXAMPLES_DEP_CFLAGS = @XTSTEXAMPLES_DEP_CFLAGS@
+XTSTEXAMPLES_DEP_LIBS = @XTSTEXAMPLES_DEP_LIBS@
+XVFB_LIBS = @XVFB_LIBS@
+XVFB_SYS_LIBS = @XVFB_SYS_LIBS@
+XWINMODULES_CFLAGS = @XWINMODULES_CFLAGS@
+XWINMODULES_LIBS = @XWINMODULES_LIBS@
+XWIN_LIBS = @XWIN_LIBS@
+XWIN_SERVER_NAME = @XWIN_SERVER_NAME@
+XWIN_SYS_LIBS = @XWIN_SYS_LIBS@
+YACC = @YACC@
+YFLAGS = @YFLAGS@
+__XCONFIGFILE__ = @__XCONFIGFILE__@
+abi_ansic = @abi_ansic@
+abi_extension = @abi_extension@
+abi_font = @abi_font@
+abi_videodrv = @abi_videodrv@
+abi_xinput = @abi_xinput@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_CXX = @ac_ct_CXX@
+ac_ct_F77 = @ac_ct_F77@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+driverdir = @driverdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+extdir = @extdir@
+ft_config = @ft_config@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+launchagentsdir = @launchagentsdir@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+logdir = @logdir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+moduledir = @moduledir@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sbindir = @sbindir@
+sdkdir = @sdkdir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+xglmoduledir = @xglmoduledir@
+xpconfigdir = @xpconfigdir@
+
+# Xserver.man covers options generic to all X servers built in this tree
+MAN_SRCS = Xorg.man.pre xorg.conf.man.pre
+appmandir = $(APP_MAN_DIR)
+appman_DATA = Xorg.$(APP_MAN_SUFFIX)
+filemandir = $(FILE_MAN_DIR)
+fileman_DATA = xorg.conf.$(FILE_MAN_SUFFIX)
+SUFFIXES = .pre .man .man.pre
+
+# Translate XCOMM into pound sign with sed, rather than passing -DXCOMM=XCOMM
+# to cpp, because that trick does not work on all ANSI C preprocessors.
+# Delete line numbers from the cpp output (-P is not portable, I guess).
+# Allow XCOMM to be preceded by whitespace and provide a means of generating
+# output lines with trailing backslashes.
+# Allow XHASH to always be substituted, even in cases where XCOMM isn't.
+CPP_SED_MAGIC = $(SED) -e '/^\# *[0-9][0-9]* *.*$$/d' \
+ -e '/^\#line *[0-9][0-9]* *.*$$/d' \
+ -e '/^[ ]*XCOMM$$/s/XCOMM/\#/' \
+ -e '/^[ ]*XCOMM[^a-zA-Z0-9_]/s/XCOMM/\#/' \
+ -e '/^[ ]*XHASH/s/XHASH/\#/' \
+ -e '/\@\@$$/s/\@\@$$/\\/'
+
+
+# Strings to replace in man pages
+XORGRELSTRING = @PACKAGE_STRING@
+XORGMANNAME = X Version 11
+XSERVERNAME = Xorg
+MANDEFS = \
+ -D__vendorversion__="\"$(XORGRELSTRING)\" \"$(XORGMANNAME)\"" \
+ -D__xorgversion__="\"$(XORGRELSTRING)\" \"$(XORGMANNAME)\"" \
+ -D__appmansuffix__=$(APP_MAN_SUFFIX) \
+ -D__filemansuffix__=$(FILE_MAN_SUFFIX) \
+ -D__libmansuffix__=$(LIB_MAN_SUFFIX) \
+ -D__miscmansuffix__=$(MISC_MAN_SUFFIX) \
+ -D__drivermansuffix__=$(DRIVER_MAN_SUFFIX) \
+ -D__adminmansuffix__=$(ADMIN_MAN_SUFFIX) \
+ -D__mandir__=$(mandir) \
+ -D__projectroot__=$(prefix) \
+ -D__xconfigfile__=$(__XCONFIGFILE__) -D__xconfigdir__=$(XCONFIGDIR) \
+ -D__xlogfile__=$(XLOGFILE) -D__xservername__=$(XSERVERNAME)
+
+EXTRAMANDEFS = -D__logdir__=$(logdir)
+CLEANFILES = $(appman_DATA) $(fileman_DATA) xorg.conf.man Xorg.man
+EXTRA_DIST = $(MAN_SRCS)
+all: all-am
+
+.SUFFIXES:
+.SUFFIXES: .pre .man .man.pre
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/cpprules.in $(am__configure_deps)
+ @for dep in $?; do \
+ case '$(am__configure_deps)' in \
+ *$$dep*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \
+ && exit 0; \
+ exit 1;; \
+ esac; \
+ done; \
+ echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign hw/xfree86/doc/man/Makefile'; \
+ cd $(top_srcdir) && \
+ $(AUTOMAKE) --foreign hw/xfree86/doc/man/Makefile
+.PRECIOUS: Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ @case '$?' in \
+ *config.status*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+ *) \
+ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+ esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+install-appmanDATA: $(appman_DATA)
+ @$(NORMAL_INSTALL)
+ test -z "$(appmandir)" || $(MKDIR_P) "$(DESTDIR)$(appmandir)"
+ @list='$(appman_DATA)'; for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ f=$(am__strip_dir) \
+ echo " $(appmanDATA_INSTALL) '$$d$$p' '$(DESTDIR)$(appmandir)/$$f'"; \
+ $(appmanDATA_INSTALL) "$$d$$p" "$(DESTDIR)$(appmandir)/$$f"; \
+ done
+
+uninstall-appmanDATA:
+ @$(NORMAL_UNINSTALL)
+ @list='$(appman_DATA)'; for p in $$list; do \
+ f=$(am__strip_dir) \
+ echo " rm -f '$(DESTDIR)$(appmandir)/$$f'"; \
+ rm -f "$(DESTDIR)$(appmandir)/$$f"; \
+ done
+install-filemanDATA: $(fileman_DATA)
+ @$(NORMAL_INSTALL)
+ test -z "$(filemandir)" || $(MKDIR_P) "$(DESTDIR)$(filemandir)"
+ @list='$(fileman_DATA)'; for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ f=$(am__strip_dir) \
+ echo " $(filemanDATA_INSTALL) '$$d$$p' '$(DESTDIR)$(filemandir)/$$f'"; \
+ $(filemanDATA_INSTALL) "$$d$$p" "$(DESTDIR)$(filemandir)/$$f"; \
+ done
+
+uninstall-filemanDATA:
+ @$(NORMAL_UNINSTALL)
+ @list='$(fileman_DATA)'; for p in $$list; do \
+ f=$(am__strip_dir) \
+ echo " rm -f '$(DESTDIR)$(filemandir)/$$f'"; \
+ rm -f "$(DESTDIR)$(filemandir)/$$f"; \
+ done
+tags: TAGS
+TAGS:
+
+ctags: CTAGS
+CTAGS:
+
+
+distdir: $(DISTFILES)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ list='$(DISTFILES)'; \
+ dist_files=`for file in $$list; do echo $$file; done | \
+ sed -e "s|^$$srcdirstrip/||;t" \
+ -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+ case $$dist_files in \
+ */*) $(MKDIR_P) `echo "$$dist_files" | \
+ sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+ sort -u` ;; \
+ esac; \
+ for file in $$dist_files; do \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+ cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
+ fi; \
+ cp -pR $$d/$$file $(distdir)$$dir || exit 1; \
+ else \
+ test -f $(distdir)/$$file \
+ || cp -p $$d/$$file $(distdir)/$$file \
+ || exit 1; \
+ fi; \
+ done
+check-am: all-am
+check: check-am
+all-am: Makefile $(DATA)
+installdirs:
+ for dir in "$(DESTDIR)$(appmandir)" "$(DESTDIR)$(filemandir)"; do \
+ test -z "$$dir" || $(MKDIR_P) "$$dir"; \
+ done
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ `test -z '$(STRIP)' || \
+ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+ -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+ -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-am
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am:
+
+html: html-am
+
+info: info-am
+
+info-am:
+
+install-data-am: install-appmanDATA install-filemanDATA
+
+install-dvi: install-dvi-am
+
+install-exec-am:
+
+install-html: install-html-am
+
+install-info: install-info-am
+
+install-man:
+
+install-pdf: install-pdf-am
+
+install-ps: install-ps-am
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am: uninstall-appmanDATA uninstall-filemanDATA
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-generic clean-libtool \
+ distclean distclean-generic distclean-libtool distdir dvi \
+ dvi-am html html-am info info-am install install-am \
+ install-appmanDATA install-data install-data-am install-dvi \
+ install-dvi-am install-exec install-exec-am \
+ install-filemanDATA install-html install-html-am install-info \
+ install-info-am install-man install-pdf install-pdf-am \
+ install-ps install-ps-am install-strip installcheck \
+ installcheck-am installdirs maintainer-clean \
+ maintainer-clean-generic mostlyclean mostlyclean-generic \
+ mostlyclean-libtool pdf pdf-am ps ps-am uninstall uninstall-am \
+ uninstall-appmanDATA uninstall-filemanDATA
+
+
+Xorg.$(APP_MAN_SUFFIX): Xorg.man
+ -rm -f Xorg.$(APP_MAN_SUFFIX)
+ $(LN_S) Xorg.man Xorg.$(APP_MAN_SUFFIX)
+
+xorg.conf.$(FILE_MAN_SUFFIX): xorg.conf.man
+ -rm -f xorg.conf.$(FILE_MAN_SUFFIX)
+ $(LN_S) xorg.conf.man xorg.conf.$(FILE_MAN_SUFFIX)
+
+.pre:
+ $(RAWCPP) $(RAWCPPFLAGS) $(CPP_FILES_FLAGS) < $< | $(CPP_SED_MAGIC) > $@
+
+.man.pre.man:
+ $(RAWCPP) $(RAWCPPFLAGS) $(MANDEFS) $(EXTRAMANDEFS) < $< | $(CPP_SED_MAGIC) > $@
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/xorg-server/hw/xfree86/doc/man/Xorg.man.pre b/xorg-server/hw/xfree86/doc/man/Xorg.man.pre
new file mode 100644
index 000000000..8b48951e7
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/man/Xorg.man.pre
@@ -0,0 +1,693 @@
+.\" $XdotOrg: xserver/xorg/hw/xfree86/doc/man/Xorg.man.pre,v 1.3 2005/07/04 18:41:01 ajax Exp $
+.TH __xservername__ __appmansuffix__ __vendorversion__
+.SH NAME
+__xservername__ - X11R7 X server
+.SH SYNOPSIS
+.B __xservername__
+.RI [\fB:\fP display ]
+.RI [ option
+.IR ... ]
+.SH DESCRIPTION
+.B __xservername__
+is a full featured X server that was originally designed for UNIX and
+UNIX-like operating systems running on Intel x86 hardware. It now runs
+on a wider range of hardware and OS platforms.
+.PP
+This work was derived by the X.Org Foundation from the XFree86 Project's
+.I "XFree86\ 4.4rc2"
+release.
+The XFree86 release was originally derived from
+.I "X386\ 1.2"
+by Thomas Roell which was contributed to X11R5 by Snitily Graphics
+Consulting Service.
+.SH PLATFORMS
+.PP
+.B __xservername__
+operates under a wide range of operating systems and hardware platforms.
+The Intel x86 (IA32) architecture is the most widely supported hardware
+platform. Other hardware platforms include Compaq Alpha, Intel IA64, AMD64,
+SPARC and PowerPC. The most widely supported operating systems are the
+free/OpenSource UNIX-like systems such as Linux, FreeBSD, NetBSD,
+OpenBSD, and Solaris. Commercial UNIX operating systems such as
+UnixWare are also supported. Other supported operating systems include
+LynxOS, and GNU Hurd. Darwin and Mac OS X are supported with the
+XDarwin(__appmansuffix__) X server. Win32/Cygwin is supported with the
+XWin(__appmansuffix__) X server.
+.PP
+.SH "NETWORK CONNECTIONS"
+.B __xservername__
+supports connections made using the following reliable
+byte-streams:
+.TP 4
+.I "Local"
+On most platforms, the "Local" connection type is a UNIX-domain socket.
+On some System V platforms, the "local" connection types also include
+STREAMS pipes, named pipes, and some other mechanisms.
+.TP 4
+.I TCP\/IP
+.B __xservername__
+listens on port
+.RI 6000+ n ,
+where
+.I n
+is the display number. This connection type can be disabled with the
+.B \-nolisten
+option (see the Xserver(1) man page for details).
+.SH "ENVIRONMENT VARIABLES"
+For operating systems that support local connections other than Unix
+Domain sockets (SVR3 and SVR4), there is a compiled-in list specifying
+the order in which local connections should be attempted. This list
+can be overridden by the
+.I XLOCAL
+environment variable described below. If the display name indicates a
+best-choice connection should be made (e.g.
+.BR :0.0 ),
+each connection mechanism is tried until a connection succeeds or no
+more mechanisms are available. Note: for these OSs, the Unix Domain
+socket connection is treated differently from the other local connection
+types. To use it the connection must be made to
+.BR unix:0.0 .
+.PP
+The
+.I XLOCAL
+environment variable should contain a list of one more
+more of the following:
+.PP
+.RS 8
+.nf
+NAMED
+PTS
+SCO
+ISC
+.fi
+.RE
+.PP
+which represent SVR4 Named Streams pipe, Old-style USL Streams pipe,
+SCO XSight Streams pipe, and ISC Streams pipe, respectively. You can
+select a single mechanism (e.g.
+.IR XLOCAL=NAMED ),
+or an ordered list (e.g. \fIXLOCAL="NAMED:PTS:SCO"\fP).
+his variable overrides the compiled-in defaults. For SVR4 it is
+recommended that
+.I NAMED
+be the first preference connection. The default setting is
+.IR PTS:NAMED:ISC:SCO .
+.PP
+To globally override the compiled-in defaults, you should define (and
+export if using
+.B sh
+or
+.BR ksh )
+.I XLOCAL
+globally. If you use startx(1) or xinit(1), the definition should be
+at the top of your
+.I .xinitrc
+file. If you use xdm(1), the definitions should be early on in the
+.I __projectroot__/lib/X11/xdm/Xsession
+script.
+.SH OPTIONS
+.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
+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 here and in
+the Xserver(__appmansuffix__) manual page. Most configuration file
+parameters, with their defaults, are described in the
+__xconfigfile__(__filemansuffix__) manual page. Driver and module specific
+configuration parameters are described in the relevant driver or module
+manual page.
+.PP
+In addition to the normal server options described in the
+Xserver(__appmansuffix__) manual page,
+.B __xservername__
+accepts the following command line switches:
+.TP 8
+.BI vt XX
+.I XX
+specifies the Virtual Terminal device number which
+.B __xservername__
+will use. Without this option,
+.B __xservername__
+will pick the first available Virtual Terminal that it can locate. This
+option applies only to platforms such as Linux, BSD, SVR3 and SVR4, that
+have virtual terminal support.
+.TP
+.B \-allowMouseOpenFail
+Allow the server to start up even if the mouse device can't be opened
+or initialised. This is equivalent to the
+.B AllowMouseOpenFail
+__xconfigfile__(__filemansuffix__) file option.
+.TP 8
+.B \-allowNonLocalModInDev
+Allow changes to keyboard and mouse settings from non-local clients.
+By default, connections from non-local clients are not allowed to do
+this. This is equivalent to the
+.B AllowNonLocalModInDev
+__xconfigfile__(__filemansuffix__) file option.
+.TP 8
+.B \-allowNonLocalXvidtune
+Make the VidMode extension available to remote clients. This allows
+the xvidtune client to connect from another host. This is equivalent
+to the
+.B AllowNonLocalXvidtune
+__xconfigfile__(__filemansuffix__) file option. By default non-local
+connections are not allowed.
+.TP 8
+.BI \-bgamma " value"
+Set the blue gamma correction.
+.I value
+must be between 0.1 and 10.
+The default is 1.0. Not all drivers support this. See also the
+.BR \-gamma ,
+.BR \-rgamma ,
+and
+.B \-ggamma
+options.
+.TP 8
+.BI \-bpp " n"
+No longer supported. Use
+.B \-depth
+to set the color depth, and use
+.B \-fbbpp
+if you really need to force a non-default framebuffer (hardware) pixel
+format.
+.TP
+.B \-configure
+When this option is specified, the
+.B __xservername__
+server loads all video driver modules, probes for available hardware,
+and writes out an initial __xconfigfile__(__filemansuffix__) file based on
+what was detected. This option currently has some problems on some
+platforms, but in most cases it is a good way to bootstrap the
+configuration process. This option is only available when the server
+is run as root (i.e, with real-uid 0).
+.TP 8
+.BI "\-crt /dev/tty" XX
+SCO only. This is the same as the
+.B vt
+option, and is provided for compatibility with the native SCO X server.
+.TP 8
+.BI \-depth " n"
+Sets the default color depth. Legal values are 1, 4, 8, 15, 16, and
+24. Not all drivers support all values.
+.TP 8
+.B \-disableModInDev
+Disable dynamic modification of input device settings. This is equivalent
+to the
+.B DisableModInDev
+__xconfigfile__(__filemansuffix__) file option.
+.TP 8
+.B \-disableVidMode
+Disable the parts of the VidMode extension (used by the xvidtune
+client) that can be used to change the video modes. This is equivalent
+to the
+.B DisableVidModeExtension
+__xconfigfile__(__filemansuffix__) file option.
+.TP 8
+.B \-fbbpp \fIn\fP
+Sets the number of framebuffer bits per pixel. You should only set this
+if you're sure it's necessary; normally the server can deduce the correct
+value from
+.B \-depth
+above. Useful if you want to run a depth 24 configuration with a 24
+bpp framebuffer rather than the (possibly default) 32 bpp framebuffer
+(or vice versa). Legal values are 1, 8, 16, 24, 32. Not all drivers
+support all values.
+.TP 8
+.B \-flipPixels
+Swap the default values for the black and white pixels.
+.TP 8
+.BI \-gamma " value"
+Set the gamma correction.
+.I value
+must be between 0.1 and 10. The default is 1.0. This value is applied
+equally to the R, G and B values. Those values can be set independently
+with the
+.BR \-rgamma ,
+.BR \-bgamma ,
+and
+.B \-ggamma
+options. Not all drivers support this.
+.TP 8
+.BI \-ggamma " value"
+Set the green gamma correction.
+.I value
+must be between 0.1 and 10. The default is 1.0. Not all drivers support
+this. See also the
+.BR \-gamma ,
+.BR \-rgamma ,
+and
+.B \-bgamma
+options.
+.TP 8
+.B \-ignoreABI
+The
+.B __xservername__
+server checks the ABI revision levels of each module that it loads. It
+will normally refuse to load modules with ABI revisions that are newer
+than the server's. This is because such modules might use interfaces
+that the server does not have. When this option is specified, mismatches
+like this are downgraded from fatal errors to warnings. This option
+should be used with care.
+.TP 8
+.B \-isolateDevice \fIbus\-id\fP
+Restrict device resets to the device at
+.IR bus\-id .
+The
+.I bus\-id
+string has the form
+.IB bustype : bus : device : function
+(e.g., \(oqPCI:1:0:0\(cq).
+At present, only isolation of PCI devices is supported; i.e., this option
+is ignored if
+.I bustype
+is anything other than \(oqPCI\(cq.
+.TP 8
+.B \-keeptty
+Prevent the server from detaching its initial controlling terminal.
+This option is only useful when debugging the server. Not all platforms
+support (or can use) this option.
+.TP 8
+.BI \-keyboard " keyboard-name"
+Use the __xconfigfile__(__filemansuffix__) file
+.B InputDevice
+section called
+.I keyboard-name
+as the core keyboard. This option is ignored when the
+.B Layout
+section specifies a core keyboard. In the absence of both a Layout
+section and this option, the first relevant
+.B InputDevice
+section is used for the core keyboard.
+.TP 8
+.BI \-layout " layout-name"
+Use the __xconfigfile__(__filemansuffix__) file
+.B Layout
+section called
+.IR layout-name .
+By default the first
+.B Layout
+section is used.
+.TP 8
+.BI \-logfile " filename"
+Use the file called
+.I filename
+as the
+.B __xservername__
+server log file. The default log file is
+.BI __logdir__/__xservername__. n .log
+on most platforms, where
+.I n
+is the display number of the
+.B __xservername__
+server. The default may be in a different directory on some platforms.
+This option is only available when the server is run as root (i.e, with
+real-uid 0).
+.TP 8
+.BR \-logverbose " [\fIn\fP]"
+Sets the verbosity level for information printed to the
+.B __xservername__
+server log file. If the
+.I n
+value isn't supplied, each occurrence of this option increments the log
+file verbosity level. When the
+.I n
+value is supplied, the log file verbosity level is set to that value.
+The default log file verbosity level is 3.
+.TP 8
+.BI \-modulepath " searchpath"
+Set the module search path to
+.IR searchpath .
+.I searchpath
+is a comma separated list of directories to search for
+.B __xservername__
+server modules. This option is only available when the server is run
+as root (i.e, with real-uid 0).
+.TP 8
+.B \-nosilk
+Disable Silken Mouse support.
+.TP 8
+.B \-pixmap24
+Set the internal pixmap format for depth 24 pixmaps to 24 bits per pixel.
+The default is usually 32 bits per pixel. There is normally little
+reason to use this option. Some client applications don't like this
+pixmap format, even though it is a perfectly legal format. This is
+equivalent to the
+.B Pixmap
+__xconfigfile__(__filemansuffix__) file option.
+.TP 8
+.B \-pixmap32
+Set the internal pixmap format for depth 24 pixmaps to 32 bits per pixel.
+This is usually the default. This is equivalent to the
+.B Pixmap
+__xconfigfile__(__filemansuffix__) file option.
+.TP 8
+.BI \-pointer " pointer-name"
+Use the __xconfigfile__(__filemansuffix__) file
+.B InputDevice
+section called
+.I pointer-name
+as the core pointer. This option is ignored when the
+.B Layout
+section specifies a core pointer. In the absence of both a Layout
+section and this option, the first relevant
+.B InputDevice
+section is used for the core pointer.
+.TP 8
+.B \-probeonly
+Causes the server to exit after the device probing stage. The
+__xconfigfile__(__filemansuffix__) file is still used when this option is
+given, so information that can be auto-detected should be commented out.
+.TP 8
+.B \-quiet
+Suppress most informational messages at startup. The verbosity level
+is set to zero.
+.TP 8
+.BI \-rgamma " value"
+Set the red gamma correction.
+.I value
+must be between 0.1 and 10. The default is 1.0. Not all drivers support
+this. See also the
+.BR \-gamma ,
+.BR \-bgamma ,
+and
+.B \-ggamma
+options.
+.TP 8
+.BI \-screen " screen-name"
+Use the __xconfigfile__(__filemansuffix__) file
+.B Screen
+section called
+.IR screen-name .
+By default the screens referenced by the default
+.B Layout
+section are used, or the first
+.B Screen
+section when there are no
+.B Layout
+sections.
+.TP 8
+.B \-showconfig
+This is the same as the
+.B \-version
+option, and is included for compatibility reasons. It may be removed
+in a future release, so the
+.B \-version
+option should be used instead.
+.TP 8
+.BI \-weight " nnn"
+Set RGB weighting at 16 bpp. The default is 565. This applies only to
+those drivers which support 16 bpp.
+.TP 8
+.BR \-verbose " [\fIn\fP]"
+Sets the verbosity level for information printed on stderr. If the
+.I n
+value isn't supplied, each occurrence of this option increments the
+verbosity level. When the
+.I n
+value is supplied, the verbosity level is set to that value. The default
+verbosity level is 0.
+.TP 8
+.B \-version
+Print out the server version, patchlevel, release date, the operating
+system/platform it was built on, and whether it includes module loader
+support.
+.TP 8
+.B \-showDefaultModulePath
+Print out the default module path the server was compiled with.
+.TP 8
+.B \-showDefaultLibPath
+Print out the path libraries should be installed to.
+.TP 8
+.BI \-config " file"
+Read the server configuration from
+.IR file .
+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.
+.SH "KEYBOARD"
+.PP
+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 server 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.
+.PP
+For more information about when the builtin event handler
+is used to recognize the special key combinations, see
+the documentation on the
+.B HandleSpecialKeys
+option in the __xconfigfile__(__filemansuffix__) man page.
+.PP
+The special combinations of key presses recognized directly
+by
+.B __xservername__
+are:
+.TP 8
+.B Ctrl+Alt+Backspace
+Immediately kills the server -- no questions asked. This can be disabled
+with the
+.B DontZap
+__xconfigfile__(__filemansuffix__) file option.
+.TP 8
+.B Ctrl+Alt+Keypad-Plus
+Change video mode to next one specified in the configuration file.
+This can be disabled with the
+.B DontZoom
+__xconfigfile__(__filemansuffix__) file option.
+.TP 8
+.B Ctrl+Alt+Keypad-Minus
+Change video mode to previous one specified in the configuration file.
+This can be disabled with the
+.B DontZoom
+__xconfigfile__(__filemansuffix__) file option.
+.TP 8
+.B Ctrl+Alt+Keypad-Multiply
+Not treated specially by default. If the
+.B AllowClosedownGrabs
+__xconfigfile__(__filemansuffix__) file option is specified, this key sequence
+kills clients with an active keyboard or mouse grab as well as killing any
+application that may have locked the server, normally using the
+XGrabServer(__libmansuffix__) Xlib function.
+.TP 8
+.B Ctrl+Alt+Keypad-Divide
+Not treated specially by default. If the
+.B AllowDeactivateGrabs
+__xconfigfile__(__filemansuffix__) file option is specified, this key sequence
+deactivates any active keyboard and mouse grabs.
+.TP 8
+.B Ctrl+Alt+F1...F12
+For BSD and Linux systems with virtual terminal support, these keystroke
+combinations are used to switch to virtual terminals 1 through 12,
+respectively. This can be disabled with the
+.B DontVTSwitch
+__xconfigfile__(__filemansuffix__) file option.
+.SH CONFIGURATION
+.B __xservername__
+typically uses a configuration file called
+.B __xconfigfile__
+for its initial setup.
+Refer to the __xconfigfile__(__filemansuffix__) manual page for information
+about the format of this file.
+.PP
+.B __xservername__
+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
+mechanism works in two ways.
+.PP
+The first is via enhancements that have made many components of the
+.B __xconfigfile__
+file optional. This means that information that can be probed or
+reasonably deduced doesn't need to be specified explicitly, greatly
+reducing the amount of built-in configuration information that needs to
+be generated at run-time.
+.PP
+The second is to have "safe" fallbacks for most configuration information.
+This maximises the likelihood that the
+.B __xservername__
+server will start up in some usable configuration even when information
+about the specific hardware is not available.
+.PP
+The automatic configuration support for __xservername__ is work in progress.
+It is currently aimed at the most popular hardware and software platforms
+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
+documented fully in the __xconfigfile__(__filemansuffix__) manual page. The
+most commonly used locations are shown here.
+.TP 30
+.B /etc/X11/__xconfigfile__
+Server configuration file.
+.TP 30
+.B /etc/X11/__xconfigfile__-4
+Server configuration file.
+.TP 30
+.B /etc/__xconfigfile__
+Server configuration file.
+.TP 30
+.B __projectroot__/etc/__xconfigfile__
+Server configuration file.
+.TP 30
+.B __projectroot__/lib/X11/__xconfigfile__
+Server configuration file.
+.TP 30
+.BI __logdir__/__xservername__. n .log
+Server log file for display
+.IR n .
+.TP 30
+.B __projectroot__/bin/\(**
+Client binaries.
+.TP 30
+.B __projectroot__/include/\(**
+Header files.
+.TP 30
+.B __projectroot__/lib/\(**
+Libraries.
+.TP 30
+.B __projectroot__/lib/X11/fonts/\(**
+Fonts.
+.TP 30
+.B __projectroot__/share/X11/rgb.txt
+Color names to RGB mapping.
+.TP 30
+.B __projectroot__/share/X11/XErrorDB
+Client error message database.
+.TP 30
+.B __projectroot__/lib/X11/app-defaults/\(**
+Client resource specifications.
+.TP 30
+.B __mandir__/man?/\(**
+Manual pages.
+.TP 30
+.BI /etc/X n .hosts
+Initial access control list for display
+.IR n .
+.SH "SEE ALSO"
+X(__miscmansuffix__), Xserver(__appmansuffix__), xdm(__appmansuffix__), xinit(__appmansuffix__),
+__xconfigfile__(__filemansuffix__), xorgconfig(__appmansuffix__), xorgcfg(__appmansuffix__), xvidtune(__appmansuffix__),
+apm(__drivermansuffix__),
+ati(__drivermansuffix__),
+chips(__drivermansuffix__),
+cirrus(__drivermansuffix__),
+cyrix(__drivermansuffix__),
+fbdev(__drivermansuffix__),
+glide(__drivermansuffix__),
+glint(__drivermansuffix__),
+i128(__drivermansuffix__),
+i740(__drivermansuffix__),
+i810(__drivermansuffix__),
+imstt(__drivermansuffix__),
+mga(__drivermansuffix__),
+neomagic(__drivermansuffix__),
+nsc(__drivermansuffix__),
+nv(__drivermansuffix__),
+r128(__drivermansuffix__),
+rendition(__drivermansuffix__),
+s3virge(__drivermansuffix__),
+siliconmotion(__drivermansuffix__),
+sis(__drivermansuffix__),
+sunbw2(__drivermansuffix__),
+suncg14(__drivermansuffix__),
+suncg3(__drivermansuffix__),
+suncg6(__drivermansuffix__),
+sunffb(__drivermansuffix__),
+sunleo(__drivermansuffix__),
+suntcx(__drivermansuffix__),
+tdfx(__drivermansuffix__),
+tga(__drivermansuffix__),
+trident(__drivermansuffix__),
+tseng(__drivermansuffix__),
+v4l(__drivermansuffix__),
+vesa(__drivermansuffix__),
+vga(__drivermansuffix__),
+vmware(__drivermansuffix__),
+.br
+Web site
+.IR <http://www.x.org> .
+
+.SH AUTHORS
+__xservername__ has many contributors world wide. The names of most of them
+can be found in the documentation, CHANGELOG files in the source tree,
+and in the actual source code.
+.PP
+__xservername__ was originally based on XFree86 4.4rc2.
+That was originally based on \fIX386 1.2\fP by Thomas Roell, which
+was contributed to the then X Consortium's X11R5 distribution by SGCS.
+.PP
+__xservername__ is released by the X.Org Foundation.
+.PP
+The project that became XFree86 was originally founded in 1992 by
+David Dawes, Glenn Lai, Jim Tsillas and David Wexelblat.
+.PP
+XFree86 was later integrated in the then X Consortium's X11R6 release
+by a group of dedicated XFree86 developers, including the following:
+.PP
+.RS 4
+.nf
+Stuart Anderson \fIanderson@metrolink.com\fP
+Doug Anson \fIdanson@lgc.com\fP
+Gertjan Akkerman \fIakkerman@dutiba.twi.tudelft.nl\fP
+Mike Bernson \fImike@mbsun.mlb.org\fP
+Robin Cutshaw \fIrobin@XFree86.org\fP
+David Dawes \fIdawes@XFree86.org\fP
+Marc Evans \fImarc@XFree86.org\fP
+Pascal Haible \fIhaible@izfm.uni-stuttgart.de\fP
+Matthieu Herrb \fIMatthieu.Herrb@laas.fr\fP
+Dirk Hohndel \fIhohndel@XFree86.org\fP
+David Holland \fIdavidh@use.com\fP
+Alan Hourihane \fIalanh@fairlite.demon.co.uk\fP
+Jeffrey Hsu \fIhsu@soda.berkeley.edu\fP
+Glenn Lai \fIglenn@cs.utexas.edu\fP
+Ted Lemon \fImellon@ncd.com\fP
+Rich Murphey \fIrich@XFree86.org\fP
+Hans Nasten \fInasten@everyware.se\fP
+Mark Snitily \fImark@sgcs.com\fP
+Randy Terbush \fIrandyt@cse.unl.edu\fP
+Jon Tombs \fItombs@XFree86.org\fP
+Kees Verstoep \fIversto@cs.vu.nl\fP
+Paul Vixie \fIpaul@vix.com\fP
+Mark Weaver \fIMark_Weaver@brown.edu\fP
+David Wexelblat \fIdwex@XFree86.org\fP
+Philip Wheatley \fIPhilip.Wheatley@ColumbiaSC.NCR.COM\fP
+Thomas Wolfram \fIwolf@prz.tu-berlin.de\fP
+Orest Zborowski \fIorestz@eskimo.com\fP
+.fi
+.RE
+.PP
+__xservername__ source is available from the FTP server
+\fI<ftp://ftp.x.org/>\fP, and from the X.Org
+server \fI<http://gitweb.freedesktop.org/>\fP. Documentation and other
+information can be found from the X.Org web site
+\fI<http://www.x.org/>\fP.
+
+.SH LEGAL
+.PP
+.B __xservername__
+is copyright software, provided under licenses that permit modification
+and redistribution in source and binary form without fee.
+.B __xservername__ is copyright by numerous authors and
+contributors from around the world. Licensing information can be found
+at
+.IR <http://www.x.org> .
+Refer to the source code for specific copyright notices.
+.PP
+.B XFree86(TM)
+is a trademark of The XFree86 Project, Inc.
+.PP
+.B X11(TM)
+and
+.B X Window System(TM)
+are trademarks of The Open Group.
diff --git a/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre b/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre
new file mode 100644
index 000000000..de93aaf36
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre
@@ -0,0 +1,2223 @@
+.\" $XdotOrg: xserver/xorg/hw/xfree86/doc/man/xorg.conf.man.pre,v 1.7 2006/05/26 00:12:18 reed Exp $
+.\" shorthand for double quote that works everywhere.
+.ds q \N'34'
+.TH __xconfigfile__ __filemansuffix__ __vendorversion__
+.SH NAME
+__xconfigfile__ \- configuration File 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.
+.SH DESCRIPTION
+.B __xservername__
+uses a configuration file called
+.I __xconfigfile__
+for its initial setup.
+This configuration file is searched for in the following places when the
+server is started as a normal user:
+.PP
+.RS 4
+.nf
+.IR /etc/X11/ <cmdline>
+.IR __projectroot__/etc/X11/ <cmdline>
+.IB /etc/X11/ $XORGCONFIG
+.IB __projectroot__/etc/X11/ $XORGCONFIG
+.I /etc/X11/__xconfigfile__\-4
+.I /etc/X11/__xconfigfile__
+.I /etc/__xconfigfile__
+.IR __projectroot__/etc/X11/__xconfigfile__. <hostname>
+.I __projectroot__/etc/X11/__xconfigfile__\-4
+.I __projectroot__/etc/X11/__xconfigfile__
+.IR __projectroot__/lib/X11/__xconfigfile__. <hostname>
+.I __projectroot__/lib/X11/__xconfigfile__\-4
+.I __projectroot__/lib/X11/__xconfigfile__
+.fi
+.RE
+.PP
+where
+.I <cmdline>
+is a relative path (with no \(lq..\(rq components) specified with the
+.B \-config
+command line option,
+.B $XORGCONFIG
+is the relative path (with no \(lq..\(rq components) specified by that
+environment variable, and
+.I <hostname>
+is the machine's hostname as reported by
+.BR gethostname (__oslibmansuffix__).
+.PP
+When the __xservername__ server is started by the \(lqroot\(rq user, the config file
+search locations are as follows:
+.PP
+.RS 4
+.nf
+<cmdline>
+.IR /etc/X11/ <cmdline>
+.IR __projectroot__/etc/X11/ <cmdline>
+.B $XORGCONFIG
+.IB /etc/X11/ $XORGCONFIG
+.IB __projectroot__/etc/X11/ $XORGCONFIG
+.BI $HOME /__xconfigfile__
+.I /etc/X11/__xconfigfile__\-4
+.I /etc/X11/__xconfigfile__
+.I /etc/__xconfigfile__
+.IR __projectroot__/etc/X11/__xconfigfile__. <hostname>
+.I __projectroot__/etc/X11/__xconfigfile__\-4
+.I __projectroot__/etc/X11/__xconfigfile__
+.IR __projectroot__/lib/X11/__xconfigfile__. <hostname>
+.I __projectroot__/lib/X11/__xconfigfile__\-4
+.I __projectroot__/lib/X11/__xconfigfile__
+.fi
+.RE
+.PP
+where
+.I <cmdline>
+is the path specified with the
+.B \-config
+command line option (which may be absolute or relative),
+.B $XORGCONFIG
+is the path specified by that
+environment variable (absolute or relative),
+.B $HOME
+is the path specified by that environment variable (usually the home
+directory), and
+.I <hostname>
+is the machine's hostname as reported by
+.BR gethostname (__oslibmansuffix__).
+.PP
+The
+.I __xconfigfile__
+file is composed of a number of sections which may be present in any order.
+Each section has the form:
+.PP
+.RS 4
+.nf
+.BI "Section \*q" SectionName \*q
+.RI " " SectionEntry
+ ...
+.B EndSection
+.fi
+.RE
+.PP
+The section names are:
+.PP
+.RS 4
+.nf
+.BR "Files " "File pathnames"
+.BR "ServerFlags " "Server flags"
+.BR "Module " "Dynamic module loading"
+.BR "InputDevice " "Input device description"
+.BR "Device " "Graphics device description"
+.BR "VideoAdaptor " "Xv video adaptor description"
+.BR "Monitor " "Monitor description"
+.BR "Modes " "Video modes descriptions"
+.BR "Screen " "Screen configuration"
+.BR "ServerLayout " "Overall layout"
+.BR "DRI " "DRI\-specific configuration"
+.BR "Vendor " "Vendor\-specific configuration"
+.fi
+.RE
+.PP
+The following obsolete section names are still recognised for compatibility
+purposes.
+In new config files, the
+.B InputDevice
+section should be used instead.
+.PP
+.RS 4
+.nf
+.BR "Keyboard " "Keyboard configuration"
+.BR "Pointer " "Pointer/mouse configuration"
+.fi
+.RE
+.PP
+The old
+.B XInput
+section is no longer recognised.
+.PP
+The
+.B ServerLayout
+sections are at the highest level.
+They bind together the input and output devices that will be used in a session.
+The input devices are described in the
+.B InputDevice
+sections.
+Output devices usually consist of multiple independent components (e.g.,
+a graphics board and a monitor).
+These multiple components are bound together in the
+.B Screen
+sections, and it is these that are referenced by the
+.B ServerLayout
+section.
+Each
+.B Screen
+section binds together a graphics board and a monitor.
+The graphics boards are described in the
+.B Device
+sections, and the monitors are described in the
+.B Monitor
+sections.
+.PP
+Config file keywords are case\-insensitive, and \(lq_\(rq characters are
+ignored.
+Most strings (including
+.B Option
+names) are also case-insensitive, and insensitive to white space and
+\(lq_\(rq characters.
+.PP
+Each config file entry usually takes up a single line in the file. They
+consist of a keyword, which is possibly followed by one or more arguments,
+with the number and types of the arguments depending on the keyword.
+The argument types are:
+.PP
+.RS 4
+.nf
+.BR "Integer " "an integer number in decimal, hex or octal"
+.BR "Real " "a floating point number"
+.BR "String " "a string enclosed in double quote marks (\*q)"
+.fi
+.RE
+.PP
+Note: hex integer values must be prefixed with \(lq0x\(rq, and octal values
+with \(lq0\(rq.
+.PP
+A special keyword called
+.B Option
+may be used to provide free\-form data to various components of the server.
+The
+.B Option
+keyword takes either one or two string arguments.
+The first is the option name, and the optional second argument is the
+option value.
+Some commonly used option value types include:
+.PP
+.RS 4
+.nf
+.BR "Integer " "an integer number in decimal, hex or octal"
+.BR "Real " "a floating point number"
+.BR "String " "a sequence of characters"
+.BR "Boolean " "a boolean value (see below)"
+.BR "Frequency " "a frequency value (see below)"
+.fi
+.RE
+.PP
+Note that
+.I all
+.B Option
+values, not just strings, must be enclosed in quotes.
+.PP
+Boolean options may optionally have a value specified.
+When no value is specified, the option's value is
+.BR TRUE .
+The following boolean option values are recognised as
+.BR TRUE :
+.PP
+.RS 4
+.BR 1 ,
+.BR on ,
+.BR true ,
+.B yes
+.RE
+.PP
+and the following boolean option values are recognised as
+.BR FALSE :
+.PP
+.RS 4
+.BR 0 ,
+.BR off ,
+.BR false ,
+.B no
+.RE
+.PP
+If an option name is prefixed with
+.RB \*q No \*q,
+then the option value is negated.
+.PP
+Example: the following option entries are equivalent:
+.PP
+.RS 4
+.nf
+.B "Option \*qAccel\*q \*qOff\*q"
+.B "Option \*qNoAccel\*q"
+.B "Option \*qNoAccel\*q \*qOn\*q"
+.B "Option \*qAccel\*q \*qfalse\*q"
+.B "Option \*qAccel\*q \*qno\*q"
+.fi
+.RE
+.PP
+Frequency option values consist of a real number that is optionally
+followed by one of the following frequency units:
+.PP
+.RS 4
+.BR Hz ,
+.BR k ,
+.BR kHz ,
+.BR M ,
+.B MHz
+.RE
+.PP
+When the unit name is omitted, the correct units will be determined from
+the value and the expectations of the appropriate range of the value.
+It is recommended that the units always be specified when using frequency
+option values to avoid any errors in determining the value.
+.SH "FILES SECTION"
+The
+.B Files
+section is used to specify some path names required by the server.
+Some of these paths can also be set from the command line (see
+.BR Xserver (__appmansuffix__)
+and
+.BR __xservername__ (__appmansuffix__)).
+The command line settings override the values specified in the config
+file.
+The
+.B Files
+section is optional, as are all of the entries that may appear in it.
+.PP
+The entries that can appear in this section are:
+.TP 7
+.BI "FontPath \*q" path \*q
+sets the search path for fonts.
+This path is a comma separated list of font path elements which the __xservername__
+server searches for font databases.
+Multiple
+.B FontPath
+entries may be specified, and they will be concatenated to build up the
+fontpath used by the server. Font path elements can be absolute
+directory paths, catalogue directories or a font server identifier. The
+formats of the later two are explained below:
+.PP
+.RS 7
+Catalogue directories:
+.PP
+.RS 4
+Catalogue directories can be specified using the prefix \fBcatalogue:\fR
+before the directory name. The directory can then be populated with
+symlinks pointing to the real font directories, using the following
+syntax in the symlink name:
+.PP
+.RS 4
+.IR <identifier> : [attribute]: pri= <priority>
+.RE
+.PP
+where
+.I <identifier>
+is an alphanumeric identifier,
+.I [attribute]
+is an attribute wich will be passed to the underlying FPE and
+.I <priority>
+is a number used to order the fontfile FPEs. Examples:
+.PP
+.RS 4
+.nf
+.I 75dpi:unscaled:pri=20 -> /usr/share/X11/fonts/75dpi
+.I gscript:pri=60 -> /usr/share/fonts/default/ghostscript
+.I misc:unscaled:pri=10 \-> /usr/share/X11/fonts/misc
+.fi
+.PP
+.RE .RE .RE
+.PP
+.RS 7
+Font server identifiers:
+.PP
+.RS 4
+Font server identifiers have the form:
+.RS 4
+.PP
+.IR <trans> / <hostname> : <port\-number>
+.RE
+.PP
+where
+.I <trans>
+is the transport type to use to connect to the font server (e.g.,
+.B unix
+for UNIX\-domain sockets or
+.B tcp
+for a TCP/IP connection),
+.I <hostname>
+is the hostname of the machine running the font server, and
+.I <port\-number>
+is the port number that the font server is listening on (usually 7100).
+.RE
+.PP
+When this entry is not specified in the config file, the server falls back
+to the compiled\-in default font path, which contains the following
+font path elements (which can be set inside a catalogue directory):
+.PP
+.RS 4
+.nf
+.I __projectroot__/lib/X11/fonts/misc/
+.I __projectroot__/lib/X11/fonts/TTF/
+.I __projectroot__/lib/X11/fonts/Type1/
+.I __projectroot__/lib/X11/fonts/75dpi/
+.I __projectroot__/lib/X11/fonts/100dpi/
+.fi
+.RE
+.PP
+The recommended font path contains the following font path elements:
+.PP
+.RS 4
+.nf
+.I __projectroot__/lib/X11/fonts/local/
+.I __projectroot__/lib/X11/fonts/misc/
+.I __projectroot__/lib/X11/fonts/75dpi/:unscaled
+.I __projectroot__/lib/X11/fonts/100dpi/:unscaled
+.I __projectroot__/lib/X11/fonts/Type1/
+.I __projectroot__/lib/X11/fonts/75dpi/
+.I __projectroot__/lib/X11/fonts/100dpi/
+.fi
+.RE
+.PP
+Font path elements that are found to be invalid are removed from the
+font path when the server starts up.
+.RE
+.TP 7
+.BI "ModulePath \*q" path \*q
+sets the search path for loadable __xservername__ server modules.
+This path is a comma separated list of directories which the __xservername__ server
+searches for loadable modules loading in the order specified.
+Multiple
+.B ModulePath
+entries may be specified, and they will be concatenated to build the
+module search path used by the server.
+.\" The LogFile keyword is not currently implemented
+.ig
+.TP 7
+.BI "LogFile \*q" path \*q
+sets the name of the __xservername__ server log file.
+The default log file name is
+.PP
+.RS 11
+.RI __logdir__/__xservername__. <n> .log
+.RE
+.PP
+.RS 7
+where
+.I <n>
+is the display number for the __xservername__ server.
+..
+.SH "SERVERFLAGS SECTION"
+In addition to options specific to this section (described below), the
+.B ServerFlags
+section is used to specify some global
+__xservername__ server options.
+All of the entries in this section are
+.BR Options ,
+although for compatibility purposes some of the old style entries are
+still recognised.
+Those old style entries are not documented here, and using them is
+discouraged.
+The
+.B ServerFlags
+section is optional, as are the entries that may be specified in it.
+.PP
+.B Options
+specified in this section (with the exception of the
+.B \*qDefaultServerLayout\*q
+.BR Option )
+may be overridden by
+.B Options
+specified in the active
+.B ServerLayout
+section.
+Options with command line equivalents are overridden when their command
+line equivalent is used.
+The options recognised by this section are:
+.TP 7
+.BI "Option \*qDefaultServerLayout\*q \*q" layout\-id \*q
+This specifies the default
+.B ServerLayout
+section to use in the absence of the
+.B \-layout
+command line option.
+.TP 7
+.BI "Option \*qNoTrapSignals\*q \*q" boolean \*q
+This prevents the __xservername__ server from trapping a range of unexpected fatal
+signals and exiting cleanly.
+Instead, the __xservername__ server will die and drop core where the fault occurred.
+The default behaviour is for the __xservername__ server to exit cleanly, but still drop a
+core file.
+In general you never want to use this option unless you are debugging an __xservername__
+server problem and know how to deal with the consequences.
+.TP 7
+.BI "Option \*qDontVTSwitch\*q \*q" boolean \*q
+This disallows the use of the
+.BI Ctrl+Alt+F n
+sequence (where
+.RI F n
+refers to one of the numbered function keys).
+That sequence is normally used to switch to another \*qvirtual terminal\*q
+on operating systems that have this feature.
+When this option is enabled, that key sequence has no special meaning and
+is passed to clients.
+Default: off.
+.TP 7
+.BI "Option \*qDontZap\*q \*q" boolean \*q
+This disallows the use of the
+.B Ctrl+Alt+Backspace
+sequence.
+That sequence is normally used to terminate the __xservername__ server.
+When this option is enabled, that key sequence has no special meaning and
+is passed to clients.
+Default: off.
+.TP 7
+.BI "Option \*qDontZoom\*q \*q" boolean \*q
+This disallows the use of the
+.B Ctrl+Alt+Keypad\-Plus
+and
+.B Ctrl+Alt+Keypad\-Minus
+sequences.
+These sequences allows you to switch between video modes.
+When this option is enabled, those key sequences have no special meaning
+and are passed to clients.
+Default: off.
+.TP 7
+.BI "Option \*qDisableVidModeExtension\*q \*q" boolean \*q
+This disables the parts of the VidMode extension used by the xvidtune client
+that can be used to change the video modes.
+Default: the VidMode extension is enabled.
+.TP 7
+.BI "Option \*qAllowNonLocalXvidtune\*q \*q" boolean \*q
+This allows the xvidtune client (and other clients that use the VidMode
+extension) to connect from another host.
+Default: off.
+.TP 7
+.BI "Option \*qDisableModInDev\*q \*q" boolean \*q
+This disables the parts of the XFree86\-Misc extension that can be used to
+modify the input device settings dynamically.
+Default: that functionality is enabled.
+.TP 7
+.BI "Option \*qAllowNonLocalModInDev\*q \*q" boolean \*q
+This allows a client to connect from another host and change keyboard
+and mouse settings in the running server.
+Default: off.
+.TP 7
+.BI "Option \*qAllowMouseOpenFail\*q \*q" boolean \*q
+This allows the server to start up even if the mouse device can't be
+opened/initialised.
+Default: false.
+.TP 7
+.BI "Option \*qVTSysReq\*q \*q" boolean \*q
+enables the SYSV\-style VT switch sequence for non\-SYSV systems
+which support VT switching.
+This sequence is
+.B Alt\-SysRq
+followed by a function key
+.RB ( Fn ).
+This prevents the __xservername__ server trapping the
+keys used for the default VT switch sequence, which means that clients can
+access them.
+Default: off.
+.TP 7
+.BI "Option \*qXkbDisable\*q \*q" boolean \*q
+disable/enable the XKEYBOARD extension.
+The \-kb command line option overrides this config file option.
+Default: XKB is enabled.
+.\" The following four options are "undocumented".
+.ig
+.TP 7
+.BI "Option \*qPciProbe1\*q"
+Use PCI probe method 1.
+Default: set.
+.TP 7
+.BI "Option \*qPciProbe2\*q"
+Use PCI probe method 2.
+Default: not set.
+.TP 7
+.BI "Option \*qPciForceConfig1\*q"
+Force the use PCI config type 1.
+Default: not set.
+.TP 7
+.BI "Option \*qPciForceConfig2\*q"
+Force the use PCI config type 2.
+Default: not set.
+..
+.TP 7
+.BI "Option \*qBlankTime\*q \*q" time \*q
+sets the inactivity timeout for the
+.B blank
+phase of the screensaver.
+.I time
+is in minutes.
+This is equivalent to the __xservername__ server's
+.B \-s
+flag, and the value can be changed at run\-time with
+.BR xset(__appmansuffix__).
+Default: 10 minutes.
+.TP 7
+.BI "Option \*qStandbyTime\*q \*q" time \*q
+sets the inactivity timeout for the
+.B standby
+phase of DPMS mode.
+.I time
+is in minutes, and the value can be changed at run\-time with
+.BR xset(__appmansuffix__).
+Default: 20 minutes.
+This is only suitable for VESA DPMS compatible monitors, and may not be
+supported by all video drivers.
+It is only enabled for screens that have the
+.B \*qDPMS\*q
+option set (see the MONITOR section below).
+.TP 7
+.BI "Option \*qSuspendTime\*q \*q" time \*q
+sets the inactivity timeout for the
+.B suspend
+phase of DPMS mode.
+.I time
+is in minutes, and the value can be changed at run\-time with
+.BR xset(__appmansuffix__).
+Default: 30 minutes.
+This is only suitable for VESA DPMS compatible monitors, and may not be
+supported by all video drivers.
+It is only enabled for screens that have the
+.B \*qDPMS\*q
+option set (see the MONITOR section below).
+.TP 7
+.BI "Option \*qOffTime\*q \*q" time \*q
+sets the inactivity timeout for the
+.B off
+phase of DPMS mode.
+.I time
+is in minutes, and the value can be changed at run\-time with
+.BR xset(__appmansuffix__).
+Default: 40 minutes.
+This is only suitable for VESA DPMS compatible monitors, and may not be
+supported by all video drivers.
+It is only enabled for screens that have the
+.B \*qDPMS\*q
+option set (see the MONITOR section below).
+.TP 7
+.BI "Option \*qPixmap\*q \*q" bpp \*q
+This sets the pixmap format to use for depth 24.
+Allowed values for
+.I bpp
+are 24 and 32.
+Default: 32 unless driver constraints don't allow this (which is rare).
+Note: some clients don't behave well when this value is set to 24.
+.TP 7
+.BI "Option \*qPC98\*q \*q" boolean \*q
+Specify that the machine is a Japanese PC\-98 machine.
+This should not be enabled for anything other than the Japanese\-specific
+PC\-98 architecture.
+Default: auto\-detected.
+.\" Doubt this should be documented.
+.ig
+.TP 7
+.BI "Option \*qEstimateSizesAggressively\*q \*q" value \*q
+This option affects the way that bus resource sizes are estimated.
+Default: 0.
+..
+.TP 7
+.BI "Option \*qNoPM\*q \*q" boolean \*q
+Disables something to do with power management events.
+Default: PM enabled on platforms that support it.
+.TP 7
+.BI "Option \*qXinerama\*q \*q" boolean \*q
+enable or disable XINERAMA extension.
+Default is disabled.
+.TP 7
+.BI "Option \*qAllowDeactivateGrabs\*q \*q" boolean \*q
+This option enables the use of the
+.B Ctrl+Alt+Keypad\-Divide
+key sequence to deactivate any active keyboard and mouse grabs.
+Default: off.
+.TP 7
+.BI "Option \*qAllowClosedownGrabs\*q \*q" boolean \*q
+This option enables the use of the
+.B Ctrl+Alt+Keypad\-Multiply
+key sequence to kill clients with an active keyboard or mouse grab as well
+as killing any application that may have locked the server, normally using
+the
+.BR XGrabServer(__libmansuffix__)
+Xlib function.
+Default: off.
+.br
+Note that the options
+.B AllowDeactivateGrabs
+and
+.B AllowClosedownGrabs
+will allow users to remove the grab used by screen saver/locker programs.
+An API was written to such cases.
+If you enable this option, make sure your screen saver/locker is updated.
+Default: off.
+.TP 7
+.BI "Option \*qHandleSpecialKeys\*q \*q" when \*q
+This option controls when the server uses the builtin handler to process
+special key combinations (such as
+.BR Ctrl+Alt+Backspace ).
+Normally the XKEYBOARD extension keymaps will provide mappings for each of
+the special key combinations, so the builtin handler is not needed unless
+the XKEYBOARD extension is disabled.
+The value of
+.I when
+can be
+.BR Always ,
+.BR Never ,
+or
+.BR WhenNeeded .
+Default: Use the builtin handler only if needed.
+The server will scan the keymap for a mapping to the
+.B Terminate
+action and, if found, use XKEYBOARD for processing actions, otherwise
+the builtin handler will be used.
+.TP 7
+.BI "Option \*qAIGLX\*q \*q" boolean \*q
+enable or disable AIGLX. AIGLX is enabled by default.
+.TP 7
+.BI "Option \*qGlxVisuals\*q \*q" string \*q
+This option controls how many GLX visuals the GLX modules sets up.
+The default value is
+.BR "typical" ,
+which will setup up a typical subset of
+the GLXFBConfigs provided by the driver as GLX visuals. Other options are
+.BR "minimal" ,
+which will set up the minimal set allowed by the GLX specification and
+.BR "all"
+which will setup GLX visuals for all GLXFBConfigs.
+.TP 7
+.BI "Option \*qUseDefaultFontPath\*q \*q" boolean \*q
+Include the default font path even if other paths are specified in
+xorg.conf. If enabled, other font paths are included as well. Enabled by
+default.
+.TP 7
+.BI "Option \*qIgnoreABI\*q \*q" boolean \*q
+Allow modules built for a different, potentially incompatible version of
+the X server to load. Disabled by default.
+.TP 7
+.BI "Option \*qAllowEmptyInput\*q \*q" boolean \*q
+If enabled, don't add the standard keyboard and mouse drivers, if there are no
+input devices in the config file. Enabled by default if AutoAddDevices and
+AutoEnableDevices is enabled, otherwise disabled.
+If AllowEmptyInput is on, devices using the kbd or mouse driver are ignored.
+.TP 7
+.BI "Option \*qAutoAddDevices\*q \*q" boolean \*q
+If this option is disabled, then no devices will be added from HAL events.
+Enabled by default.
+.TP 7
+.BI "Option \*qAutoEnableDevices\*q \*q" boolean \*q
+If this option is disabled, then the devices will be added (and the
+DevicePresenceNotify event sent), but not enabled, thus leaving policy up
+to the client.
+Enabled by default.
+.SH "MODULE SECTION"
+The
+.B Module
+section is used to specify which __xservername__ server modules should be loaded.
+This section is ignored when the __xservername__ server is built in static form.
+The types of modules normally loaded in this section are __xservername__ server
+extension modules, and font rasteriser modules.
+Most other module types are loaded automatically when they are needed via
+other mechanisms.
+The
+.B Module
+section is optional, as are all of the entries that may be specified in
+it.
+.PP
+Entries in this section may be in two forms.
+The first and most commonly used form is an entry that uses the
+.B Load
+keyword, as described here:
+.TP 7
+.BI "Load \*q" modulename \*q
+This instructs the server to load the module called
+.IR modulename .
+The module name given should be the module's standard name, not the
+module file name.
+The standard name is case\-sensitive, and does not include the \(lqlib\(rq
+prefix, or the \(lq.a\(rq, \(lq.o\(rq, or \(lq.so\(rq suffixes.
+.PP
+.RS 7
+Example: the FreeType font rasteriser can be loaded with the following entry:
+.PP
+.RS 4
+.B "Load \*qfreetype\*q"
+.RE
+.RE
+.TP 7
+.BI "Disable \*q" modulename \*q
+This instructs the server to not load the module called
+.IR modulename .
+Some modules are loaded by default in the server, and this overrides that
+default. If a
+.B Load
+instruction is given for the same module, it overrides the
+.B Disable
+instruction and the module is loaded. The module name given should be the
+module's standard name, not the module file name. As with the
+.B Load
+instruction, the standard name is case-sensitive, and does not include the
+"lib" prefix, or the ".a", ".o", or ".so" suffixes.
+.PP
+The second form of entry is a
+.BR SubSection,
+with the subsection name being the module name, and the contents of the
+.B SubSection
+being
+.B Options
+that are passed to the module when it is loaded.
+.PP
+Example: the extmod module (which contains a miscellaneous group of
+server extensions) can be loaded, with the XFree86\-DGA extension
+disabled by using the following entry:
+.PP
+.RS 4
+.nf
+.B "SubSection \*qextmod\*q"
+.B " Option \*qomit XFree86\-DGA\*q"
+.B EndSubSection
+.fi
+.RE
+.PP
+Modules are searched for in each directory specified in the
+.B ModulePath
+search path, and in the drivers, input, extensions, fonts, and
+internal subdirectories of each of those directories.
+In addition to this, operating system specific subdirectories of all
+the above are searched first if they exist.
+.PP
+To see what font and extension modules are available, check the contents
+of the following directories:
+.PP
+.RS 4
+.nf
+__projectroot__/lib/modules/fonts
+__projectroot__/lib/modules/extensions
+.fi
+.RE
+.PP
+The \(lqbitmap\(rq font module is loaded automatically.
+It is recommended
+that at very least the \(lqextmod\(rq extension module be loaded.
+If it isn't, some commonly used server extensions (like the SHAPE
+extension) will not be available.
+.SH "INPUTDEVICE SECTION"
+The config file may have multiple
+.B InputDevice
+sections.
+There will normally be at least two: one for the core (primary) keyboard,
+and one of the core pointer.
+If either of these two is missing, a default configuration for the missing
+ones will be used.
+Currently the default configuration may not work as expected on all platforms.
+.PP
+.B InputDevice
+sections have the following format:
+.PP
+.RS 4
+.nf
+.B "Section \*qInputDevice\*q"
+.BI " Identifier \*q" name \*q
+.BI " Driver \*q" inputdriver \*q
+.I " options"
+.I " ..."
+.B "EndSection"
+.fi
+.RE
+.PP
+The
+.B Identifier
+and
+.B Driver
+entries are required in all
+.B InputDevice
+sections.
+All other entries are optional.
+.PP
+The
+.B Identifier
+entry specifies the unique name for this input device.
+The
+.B Driver
+entry specifies the name of the driver to use for this input device.
+When using the loadable server, the input driver module
+.RI \*q inputdriver \*q
+will be loaded for each active
+.B InputDevice
+section.
+An
+.B InputDevice
+section is considered active if it is referenced by an active
+.B ServerLayout
+section, if it is referenced by the
+.B \-keyboard
+or
+.B \-pointer
+command line options, or if it is selected implicitly as the core pointer
+or keyboard device in the absence of such explicit references.
+The most commonly used input drivers are
+.BR keyboard (__drivermansuffix__)
+and
+.BR mouse (__drivermansuffix__).
+.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 \(lqkeyboard\(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
+.BR Options ,
+which are described here.
+See the individual input driver manual pages for a description of the
+device\-specific options.
+.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.
+.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.
+.TP 7
+.BI "Option \*qAlwaysCore\*q \*q" boolean \*q
+.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.
+.TP 7
+.BI "Option \*qSendDragEvents\*q \*q" boolean \*q
+???
+.SH "DEVICE SECTION"
+The config file may have multiple
+.B Device
+sections.
+There must be at least one, for the video card being used.
+.PP
+.B Device
+sections have the following format:
+.PP
+.RS 4
+.nf
+.B "Section \*qDevice\*q"
+.BI " Identifier \*q" name \*q
+.BI " Driver \*q" driver \*q
+.I " entries"
+.I " ..."
+.B "EndSection"
+.fi
+.RE
+.PP
+The
+.B Identifier
+and
+.B Driver
+entries are required in all
+.B Device
+sections. All other entries are optional.
+.PP
+The
+.B Identifier
+entry specifies the unique name for this graphics device.
+The
+.B Driver
+entry specifies the name of the driver to use for this graphics device.
+When using the loadable server, the driver module
+.RI \*q driver \*q
+will be loaded for each active
+.B Device
+section.
+A
+.B Device
+section is considered active if it is referenced by an active
+.B Screen
+section.
+.PP
+.B Device
+sections recognise some driver\-independent entries and
+.BR Options ,
+which are described here.
+Not all drivers make use of these
+driver\-independent entries, and many of those that do don't require them
+to be specified because the information is auto\-detected.
+See the individual graphics driver manual pages for further information
+about this, and for a description of the device\-specific options.
+Note that most of the
+.B Options
+listed here (but not the other entries) may be specified in the
+.B Screen
+section instead of here in the
+.B Device
+section.
+.TP 7
+.BI "BusID \*q" bus\-id \*q
+This specifies the bus location of the graphics card.
+For PCI/AGP cards,
+the
+.I bus\-id
+string has the form
+.BI PCI: bus : device : function
+(e.g., \(lqPCI:1:0:0\(rq might be appropriate for an AGP card).
+This field is usually optional in single-head configurations when using
+the primary graphics card.
+In multi-head configurations, or when using a secondary graphics card in a
+single-head configuration, this entry is mandatory.
+Its main purpose is to make an unambiguous connection between the device
+section and the hardware it is representing.
+This information can usually be found by running the pciaccess tool
+scanpci.
+.TP 7
+.BI "Screen " number
+This option is mandatory for cards where a single PCI entity can drive more
+than one display (i.e., multiple CRTCs sharing a single graphics accelerator
+and video memory).
+One
+.B Device
+section is required for each head, and this
+parameter determines which head each of the
+.B Device
+sections applies to.
+The legal values of
+.I number
+range from 0 to one less than the total number of heads per entity.
+Most drivers require that the primary screen (0) be present.
+.TP 7
+.BI "Chipset \*q" chipset \*q
+This usually optional entry specifies the chipset used on the graphics
+board.
+In most cases this entry is not required because the drivers will probe the
+hardware to determine the chipset type.
+Don't specify it unless the driver-specific documentation recommends that you
+do.
+.TP 7
+.BI "Ramdac \*q" ramdac\-type \*q
+This optional entry specifies the type of RAMDAC used on the graphics
+board.
+This is only used by a few of the drivers, and in most cases it is not
+required because the drivers will probe the hardware to determine the
+RAMDAC type where possible.
+Don't specify it unless the driver-specific documentation recommends that you
+do.
+.TP 7
+.BI "DacSpeed " speed
+.TP 7
+.BI "DacSpeed " "speed\-8 speed\-16 speed\-24 speed\-32"
+This optional entry specifies the RAMDAC speed rating (which is usually
+printed on the RAMDAC chip).
+The speed is in MHz.
+When one value is given, it applies to all framebuffer pixel sizes.
+When multiple values are given, they apply to the framebuffer pixel sizes
+8, 16, 24 and 32 respectively.
+This is not used by many drivers, and only needs to be specified when the
+speed rating of the RAMDAC is different from the defaults built in to
+driver, or when the driver can't auto-detect the correct defaults.
+Don't specify it unless the driver-specific documentation recommends that you
+do.
+.TP 7
+.BI "Clocks " "clock ..."
+specifies the pixel that are on your graphics board.
+The clocks are in MHz, and may be specified as a floating point number.
+The value is stored internally to the nearest kHz.
+The ordering of the clocks is important.
+It must match the order in which they are selected on the graphics board.
+Multiple
+.B Clocks
+lines may be specified, and each is concatenated to form the list.
+Most drivers do not use this entry, and it is only required for some older
+boards with non-programmable clocks.
+Don't specify this entry unless the driver-specific documentation explicitly
+recommends that you do.
+.TP
+.BI "ClockChip \*q" clockchip\-type \*q
+This optional entry is used to specify the clock chip type on graphics
+boards which have a programmable clock generator.
+Only a few __xservername__ drivers support programmable clock chips.
+For details, see the appropriate driver manual page.
+.TP 7
+.BI "VideoRam " "mem"
+This optional entry specifies the amount of video ram that is installed
+on the graphics board.
+This is measured in kBytes.
+In most cases this is not required because the __xservername__ server probes
+the graphics board to determine this quantity.
+The driver-specific documentation should indicate when it might be needed.
+.TP 7
+.BI "BiosBase " "baseaddress"
+This optional entry specifies the base address of the video BIOS for
+the VGA board.
+This address is normally auto-detected, and should only be specified if the
+driver-specific documentation recommends it.
+.TP 7
+.BI "MemBase " "baseaddress"
+This optional entry specifies the memory base address of a graphics
+board's linear frame buffer.
+This entry is not used by many drivers, and it should only be specified if
+the driver-specific documentation recommends it.
+.TP 7
+.BI "IOBase " "baseaddress"
+This optional entry specifies the IO base address.
+This entry is not used by many drivers, and it should only be specified if
+the driver-specific documentation recommends it.
+.TP 7
+.BI "ChipID " "id"
+This optional entry specifies a numerical ID representing the chip type.
+For PCI cards, it is usually the device ID.
+This can be used to override the auto-detection, but that should only be done
+when the driver-specific documentation recommends it.
+.TP 7
+.BI "ChipRev " "rev"
+This optional entry specifies the chip revision number.
+This can be used to override the auto-detection, but that should only be done
+when the driver-specific documentation recommends it.
+.TP 7
+.BI "TextClockFreq " "freq"
+This optional entry specifies the pixel clock frequency that is used
+for the regular text mode.
+The frequency is specified in MHz.
+This is rarely used.
+.TP 7
+.BI "Option \*qModeDebug\*q \*q" boolean \*q
+Enable printing of additional debugging information about modesetting to
+the server log.
+.ig
+.TP 7
+This optional entry allows an IRQ number to be specified.
+..
+.TP 7
+.B Options
+Option flags may be specified in the
+.B Device
+sections.
+These include driver\-specific options and driver\-independent options.
+The former are described in the driver\-specific documentation.
+Some of the latter are described below in the section about the
+.B Screen
+section, and they may also be included here.
+
+.SH "VIDEOADAPTOR SECTION"
+Nobody wants to say how this works.
+Maybe nobody knows ...
+
+.SH "MONITOR SECTION"
+The config file may have multiple
+.B Monitor
+sections.
+There should normally be at least one, for the monitor being used,
+but a default configuration will be created when one isn't specified.
+.PP
+.B Monitor
+sections have the following format:
+.PP
+.RS 4
+.nf
+.B "Section \*qMonitor\*q"
+.BI " Identifier \*q" name \*q
+.I " entries"
+.I " ..."
+.B "EndSection"
+.fi
+.RE
+.PP
+The only mandatory entry in a
+.B Monitor
+section is the
+.B Identifier
+entry.
+.PP
+The
+.B Identifier
+entry specifies the unique name for this monitor.
+The
+.B Monitor
+section may be used to provide information about the specifications of the
+monitor, monitor-specific
+.BR Options ,
+and information about the video modes to use with the monitor.
+.PP
+With RandR 1.2-enabled drivers, monitor sections may be tied to specific
+outputs of the video card. Using the name of the output defined by the video
+driver plus the identifier of a monitor section, one associates a monitor
+section with an output by adding an option to the Device section in the
+following format:
+
+.B Option \*qMonitor-outputname\*q \*qmonitorsection\*q
+
+(for example,
+.B Option \*qMonitor-VGA\*q \*qVGA monitor\*q
+for a VGA output)
+.PP
+In the absence of specific association of monitor sections to outputs, if a
+monitor section is present the server will associate it with an output to
+preserve compatibility for previous single-head configurations.
+.PP
+Specifying video modes is optional because the server will use the DDC or other
+information provided by the monitor to automatically configure the list of
+modes available.
+When modes are specified explicitly in the
+.B Monitor
+section (with the
+.BR Modes ,
+.BR ModeLine ,
+or
+.B UseModes
+keywords), built-in modes with the same names are not included.
+Built-in modes with different names are, however, still implicitly included,
+when they meet the requirements of the monitor.
+.PP
+The entries that may be used in
+.B Monitor
+sections are described below.
+.TP 7
+.BI "VendorName \*q" vendor \*q
+This optional entry specifies the monitor's manufacturer.
+.TP 7
+.BI "ModelName \*q" model \*q
+This optional entry specifies the monitor's model.
+.TP 7
+.BI "HorizSync " "horizsync\-range"
+gives the range(s) of horizontal sync frequencies supported by the
+monitor.
+.I horizsync\-range
+may be a comma separated list of either discrete values or ranges of
+values.
+A range of values is two values separated by a dash.
+By default the values are in units of kHz.
+They may be specified in MHz or Hz
+if
+.B MHz
+or
+.B Hz
+is added to the end of the line.
+The data given here is used by the __xservername__ server to determine if video
+modes are within the specifications of the monitor.
+This information should be available in the monitor's handbook.
+If this entry is omitted, a default range of 28\-33kHz is used.
+.TP 7
+.BI "VertRefresh " "vertrefresh\-range"
+gives the range(s) of vertical refresh frequencies supported by the
+monitor.
+.I vertrefresh\-range
+may be a comma separated list of either discrete values or ranges of
+values.
+A range of values is two values separated by a dash.
+By default the values are in units of Hz.
+They may be specified in MHz or kHz
+if
+.B MHz
+or
+.B kHz
+is added to the end of the line.
+The data given here is used by the __xservername__ server to determine if video
+modes are within the specifications of the monitor.
+This information should be available in the monitor's handbook.
+If this entry is omitted, a default range of 43\-72Hz is used.
+.TP 7
+.BI "DisplaySize " "width height"
+This optional entry gives the width and height, in millimetres, of the
+picture area of the monitor.
+If given this is used to calculate the horizontal and vertical pitch (DPI) of
+the screen.
+.TP 7
+.BI "Gamma " "gamma\-value"
+.TP 7
+.BI "Gamma " "red\-gamma green\-gamma blue\-gamma"
+This is an optional entry that can be used to specify the gamma correction
+for the monitor.
+It may be specified as either a single value or as three separate RGB values.
+The values should be in the range 0.1 to 10.0, and the default is 1.0.
+Not all drivers are capable of using this information.
+.TP 7
+.BI "UseModes \*q" modesection\-id \*q
+Include the set of modes listed in the
+.B Modes
+section called
+.IR modesection\-id.
+This makes all of the modes defined in that section available for use by
+this monitor.
+.TP 7
+.BI "Mode \*q" name \*q
+This is an optional multi-line entry that can be used to provide
+definitions for video modes for the monitor.
+In most cases this isn't necessary because the built-in set of VESA standard
+modes will be sufficient.
+The
+.B Mode
+keyword indicates the start of a multi-line video mode description.
+The mode description is terminated with the
+.B EndMode
+keyword.
+The mode description consists of the following entries:
+.RS 7
+.TP 4
+.BI "DotClock " clock
+is the dot (pixel) clock rate to be used for the mode.
+.TP 4
+.BI "HTimings " "hdisp hsyncstart hsyncend htotal"
+specifies the horizontal timings for the mode.
+.TP 4
+.BI "VTimings " "vdisp vsyncstart vsyncend vtotal"
+specifies the vertical timings for the mode.
+.TP 4
+.BI "Flags \*q" flag \*q " ..."
+specifies an optional set of mode flags, each of which is a separate
+string in double quotes.
+.B \*qInterlace\*q
+indicates that the mode is interlaced.
+.B \*qDoubleScan\*q
+indicates a mode where each scanline is doubled.
+.B \*q+HSync\*q
+and
+.B \*q\-HSync\*q
+can be used to select the polarity of the HSync signal.
+.B \*q+VSync\*q
+and
+.B \*q\-VSync\*q
+can be used to select the polarity of the VSync signal.
+.B \*qComposite\*q
+can be used to specify composite sync on hardware where this is supported.
+Additionally, on some hardware,
+.B \*q+CSync\*q
+and
+.B \*q\-CSync\*q
+may be used to select the composite sync polarity.
+.TP 4
+.BI "HSkew " hskew
+specifies the number of pixels (towards the right edge of the screen) by
+which the display enable signal is to be skewed.
+Not all drivers use this information.
+This option might become necessary to override the default value supplied
+by the server (if any).
+\(lqRoving\(rq horizontal lines indicate this value needs to be increased.
+If the last few pixels on a scan line appear on the left of the screen,
+this value should be decreased.
+.TP 4
+.BI "VScan " vscan
+specifies the number of times each scanline is painted on the screen.
+Not all drivers use this information.
+Values less than 1 are treated as 1, which is the default.
+Generally, the
+.B \*qDoubleScan\*q
+.B Flag
+mentioned above doubles this value.
+.RE
+.TP 7
+.BI "ModeLine \*q" name \*q " mode\-description"
+This entry is a more compact version of the
+.B Mode
+entry, and it also can be used to specify video modes for the monitor.
+is a single line format for specifying video modes.
+In most cases this isn't necessary because the built\-in set of VESA
+standard modes will be sufficient.
+.PP
+.RS 7
+The
+.I mode\-description
+is in four sections, the first three of which are mandatory.
+The first is the dot (pixel) clock.
+This is a single number specifying the pixel clock rate for the mode in
+MHz.
+The second section is a list of four numbers specifying the horizontal
+timings.
+These numbers are the
+.IR hdisp ,
+.IR hsyncstart ,
+.IR hsyncend ,
+and
+.I htotal
+values.
+The third section is a list of four numbers specifying the vertical
+timings.
+These numbers are the
+.IR vdisp ,
+.IR vsyncstart ,
+.IR vsyncend ,
+and
+.I vtotal
+values.
+The final section is a list of flags specifying other characteristics of
+the mode.
+.B Interlace
+indicates that the mode is interlaced.
+.B DoubleScan
+indicates a mode where each scanline is doubled.
+.B +HSync
+and
+.B \-HSync
+can be used to select the polarity of the HSync signal.
+.B +VSync
+and
+.B \-VSync
+can be used to select the polarity of the VSync signal.
+.B Composite
+can be used to specify composite sync on hardware where this is supported.
+Additionally, on some hardware,
+.B +CSync
+and
+.B \-CSync
+may be used to select the composite sync polarity.
+The
+.B HSkew
+and
+.B VScan
+options mentioned above in the
+.B Modes
+entry description can also be used here.
+.RE
+.TP 7
+.BI "Option " "\*qDPMS\*q " \*qbool\*q
+This option controls whether the server should enable the DPMS extension
+for power management for this screen. The default is to enable the
+extension.
+.TP 7
+.BI "Option " "\*qSyncOnGreen\*q " \*qbool\*q
+This option controls whether the video card should drive the sync signal
+on the green color pin. Not all cards support this option, and most
+monitors do not require it. The default is off.
+.TP 7
+.BI "Option " "\*qTargetRefresh\*q " \*qrate\*q
+This optional entry specifies the vertical refresh rate that the server
+should aim for when selecting video modes. Without this option, the
+default is to prefer modes with higher refresh rates.
+.TP 7
+.BI "Option " "\*qPreferredMode\*q " \*qstring\*q
+This optional entry specifies a mode to be marked as the preferred initial mode
+of the monitor.
+(RandR 1.2-supporting drivers only)
+.TP 7
+.BI "Option " "\*qPosition\*q " "\*qx y\*q"
+This optional entry specifies the position of the monitor within the X
+screen.
+(RandR 1.2-supporting drivers only)
+.TP 7
+.BI "Option " "\*qLeftOf\*q " \*qoutput\*q
+This optional entry specifies that the monitor should be positioned to the
+left of the output (not monitor) of the given name.
+(RandR 1.2-supporting drivers only)
+.TP 7
+.BI "Option " "\*qRightOf\*q " \*qoutput\*q
+This optional entry specifies that the monitor should be positioned to the
+right of the output (not monitor) of the given name.
+(RandR 1.2-supporting drivers only)
+.TP 7
+.BI "Option " "\*qAbove\*q " \*qoutput\*q
+This optional entry specifies that the monitor should be positioned above the
+output (not monitor) of the given name.
+(RandR 1.2-supporting drivers only)
+.TP 7
+.BI "Option " "\*qBelow\*q " \*qoutput\*q
+This optional entry specifies that the monitor should be positioned below the
+output (not monitor) of the given name.
+(RandR 1.2-supporting drivers only)
+.TP 7
+.BI "Option " "\*qEnable\*q " \*qbool\*q
+This optional entry specifies whether the monitor should be turned on
+at startup. By default, the server will attempt to enable all connected
+monitors.
+(RandR 1.2-supporting drivers only)
+.TP 7
+.BI "Option " "\*qMinClock\*q " \*qfrequency\*q
+This optional entry specifies the minimum dot clock, in kHz, that is supported
+by the monitor.
+.TP 7
+.BI "Option " "\*qMaxClock\*q " \*qfrequency\*q
+This optional entry specifies the maximum dot clock, in kHz, that is supported
+by the monitor.
+.TP 7
+.BI "Option " "\*qIgnore\*q " \*qbool\*q
+This optional entry specifies that the monitor should be ignored entirely,
+and not reported through RandR. This is useful if the hardware reports the
+presence of outputs that don't exist.
+(RandR 1.2-supporting drivers only)
+.TP 7
+.BI "Option " "\*qRotate\*q " \*qrotation\*q
+This optional entry specifies the initial rotation of the given monitor.
+Valid values for rotation are \*qnormal\*q, \*qleft\*q, \*qright\*q, and
+\*qinverted\*q.
+(RandR 1.2-supporting drivers only)
+
+.SH "MODES SECTION"
+The config file may have multiple
+.B Modes
+sections, or none.
+These sections provide a way of defining sets of video modes independently
+of the
+.B Monitor
+sections.
+.B Monitor
+sections may include the definitions provided in these sections by
+using the
+.B UseModes
+keyword.
+In most cases the
+.B Modes
+sections are not necessary because the built\-in set of VESA standard modes
+will be sufficient.
+.PP
+.B Modes
+sections have the following format:
+.PP
+.RS 4
+.nf
+.B "Section \*qModes\*q"
+.BI " Identifier \*q" name \*q
+.I " entries"
+.I " ..."
+.B "EndSection"
+.fi
+.RE
+.PP
+The
+.B Identifier
+entry specifies the unique name for this set of mode descriptions.
+The other entries permitted in
+.B Modes
+sections are the
+.B Mode
+and
+.B ModeLine
+entries that are described above in the
+.B Monitor
+section.
+.SH "SCREEN SECTION"
+The config file may have multiple
+.B Screen
+sections.
+There must be at least one, for the \(lqscreen\(rq being used.
+A \(lqscreen\(rq represents the binding of a graphics device
+.RB ( Device
+section) and a monitor
+.RB ( Monitor
+section).
+A
+.B Screen
+section is considered \(lqactive\(rq if it is referenced by an active
+.B ServerLayout
+section or by the
+.B \-screen
+command line option.
+If neither of those is present, the first
+.B Screen
+section found in the config file is considered the active one.
+.PP
+.B Screen
+sections have the following format:
+.PP
+.RS 4
+.nf
+.B "Section \*qScreen\*q"
+.BI " Identifier \*q" name \*q
+.BI " Device \*q" devid \*q
+.BI " Monitor \*q" monid \*q
+.I " entries"
+.I " ..."
+.BI " SubSection \*qDisplay\*q"
+.I " entries"
+.I " ...
+.B " EndSubSection"
+.I " ..."
+.B "EndSection"
+.fi
+.RE
+.PP
+The
+.B Identifier
+and
+.B Device
+entries are mandatory.
+All others are optional.
+.PP
+The
+.B Identifier
+entry specifies the unique name for this screen.
+The
+.B Screen
+section provides information specific to the whole screen, including
+screen\-specific
+.BR Options .
+In multi\-head configurations, there will be multiple active
+.B Screen
+sections, one for each head.
+The entries available
+for this section are:
+.TP 7
+.BI "Device \*q" device\-id \*q
+This mandatory entry specifies the
+.B Device
+section to be used for this screen.
+This is what ties a specific graphics card to a screen.
+The
+.I device\-id
+must match the
+.B Identifier
+of a
+.B Device
+section in the config file.
+.TP 7
+.BI "Monitor \*q" monitor\-id \*q
+specifies which monitor description is to be used for this screen.
+If a
+.B Monitor
+name is not specified, a default configuration is used.
+Currently the default configuration may not function as expected on all
+platforms.
+.TP 7
+.BI "VideoAdaptor \*q" xv\-id \*q
+specifies an optional Xv video adaptor description to be used with this
+screen.
+.TP 7
+.BI "DefaultDepth " depth
+specifies which color depth the server should use by default.
+The
+.B \-depth
+command line option can be used to override this.
+If neither is specified, the default depth is driver\-specific, but in most
+cases is 8.
+.TP 7
+.BI "DefaultFbBpp " bpp
+specifies which framebuffer layout to use by default.
+The
+.B \-fbbpp
+command line option can be used to override this.
+In most cases the driver will chose the best default value for this.
+The only case where there is even a choice in this value is for depth 24,
+where some hardware supports both a packed 24 bit framebuffer layout and a
+sparse 32 bit framebuffer layout.
+.TP 7
+.B Options
+Various
+.B Option
+flags may be specified in the
+.B Screen
+section.
+Some are driver\-specific and are described in the driver documentation.
+Others are driver\-independent, and will eventually be described here.
+.\" XXX These should really be in an xaa man page.
+.TP 7
+.BI "Option \*qAccel\*q"
+Enables XAA (X Acceleration Architecture), a mechanism that makes video
+cards' 2D hardware acceleration available to the __xservername__ server.
+This option is on by default, but it may be necessary to turn it off if
+there are bugs in the driver.
+There are many options to disable specific accelerated operations, listed
+below.
+Note that disabling an operation will have no effect if the operation is
+not accelerated (whether due to lack of support in the hardware or in the
+driver).
+.TP 7
+.BI "Option \*qInitPrimary\*q \*q" boolean \*q
+Use the Int10 module to initialize the primary graphics card.
+Normally, only secondary cards are soft-booted using the Int10 module, as the
+primary card has already been initialized by the BIOS at boot time.
+Default: false.
+.TP 7
+.BI "Option \*qNoInt10\*q \*q" boolean \*q
+Disables the Int10 module, a module that uses the int10 call to the BIOS
+of the graphics card to initialize it.
+Default: false.
+.TP 7
+.BI "Option \*qNoMTRR\*q"
+Disables MTRR (Memory Type Range Register) support, a feature of modern
+processors which can improve video performance by a factor of up to 2.5.
+Some hardware has buggy MTRR support, and some video drivers have been
+known to exhibit problems when MTRR's are used.
+.TP 7
+.BI "Option \*qXaaNoCPUToScreenColorExpandFill\*q"
+Disables accelerated rectangular expansion blits from source patterns
+stored in system memory (using a memory\-mapped aperture).
+.TP 7
+.BI "Option \*qXaaNoColor8x8PatternFillRect\*q"
+Disables accelerated fills of a rectangular region with a full\-color
+pattern.
+.TP 7
+.BI "Option \*qXaaNoColor8x8PatternFillTrap\*q"
+Disables accelerated fills of a trapezoidal region with a full\-color
+pattern.
+.TP 7
+.BI "Option \*qXaaNoDashedBresenhamLine\*q"
+Disables accelerated dashed Bresenham line draws.
+.TP 7
+.BI "Option \*qXaaNoDashedTwoPointLine\*q"
+Disables accelerated dashed line draws between two arbitrary points.
+.TP 7
+.BI "Option \*qXaaNoImageWriteRect\*q"
+Disables accelerated transfers of full\-color rectangular patterns from
+system memory to video memory (using a memory\-mapped aperture).
+.TP 7
+.BI "Option \*qXaaNoMono8x8PatternFillRect\*q"
+Disables accelerated fills of a rectangular region with a monochrome
+pattern.
+.TP 7
+.BI "Option \*qXaaNoMono8x8PatternFillTrap\*q"
+Disables accelerated fills of a trapezoidal region with a monochrome
+pattern.
+.TP 7
+.BI "Option \*qXaaNoOffscreenPixmaps\*q"
+Disables accelerated draws into pixmaps stored in offscreen video memory.
+.TP 7
+.BI "Option \*qXaaNoPixmapCache\*q"
+Disables caching of patterns in offscreen video memory.
+.TP 7
+.BI "Option \*qXaaNoScanlineCPUToScreenColorExpandFill\*q"
+Disables accelerated rectangular expansion blits from source patterns
+stored in system memory (one scan line at a time).
+.TP 7
+.BI "Option \*qXaaNoScanlineImageWriteRect\*q"
+Disables accelerated transfers of full\-color rectangular patterns from
+system memory to video memory (one scan line at a time).
+.TP 7
+.BI "Option \*qXaaNoScreenToScreenColorExpandFill\*q"
+Disables accelerated rectangular expansion blits from source patterns
+stored in offscreen video memory.
+.TP 7
+.BI "Option \*qXaaNoScreenToScreenCopy\*q"
+Disables accelerated copies of rectangular regions from one part of
+video memory to another part of video memory.
+.TP 7
+.BI "Option \*qXaaNoSolidBresenhamLine\*q"
+Disables accelerated solid Bresenham line draws.
+.TP 7
+.BI "Option \*qXaaNoSolidFillRect\*q"
+Disables accelerated solid\-color fills of rectangles.
+.TP 7
+.BI "Option \*qXaaNoSolidFillTrap\*q"
+Disables accelerated solid\-color fills of Bresenham trapezoids.
+.TP 7
+.BI "Option \*qXaaNoSolidHorVertLine\*q"
+Disables accelerated solid horizontal and vertical line draws.
+.TP 7
+.BI "Option \*qXaaNoSolidTwoPointLine\*q"
+Disables accelerated solid line draws between two arbitrary points.
+.PP
+Each
+.B Screen
+section may optionally contain one or more
+.B Display
+subsections.
+Those subsections provide depth/fbbpp specific configuration information,
+and the one chosen depends on the depth and/or fbbpp that is being used for
+the screen.
+The
+.B Display
+subsection format is described in the section below.
+
+.SH "DISPLAY SUBSECTION"
+Each
+.B Screen
+section may have multiple
+.B Display
+subsections.
+The \(lqactive\(rq
+.B Display
+subsection is the first that matches the depth and/or fbbpp values being
+used, or failing that, the first that has neither a depth or fbbpp value
+specified.
+The
+.B Display
+subsections are optional.
+When there isn't one that matches the depth and/or fbbpp values being used,
+all the parameters that can be specified here fall back to their defaults.
+.PP
+.B Display
+subsections have the following format:
+.PP
+.RS 4
+.nf
+.B " SubSection \*qDisplay\*q"
+.BI " Depth " depth
+.I " entries"
+.I " ..."
+.B " EndSubSection"
+.fi
+.RE
+.TP 7
+.BI "Depth " depth
+This entry specifies what colour depth the
+.B Display
+subsection is to be used for.
+This entry is usually specified, but it may be omitted to create a match\-all
+.B Display
+subsection or when wishing to match only against the
+.B FbBpp
+parameter.
+The range of
+.I depth
+values that are allowed depends on the driver.
+Most drivers support 8, 15, 16 and 24.
+Some also support 1 and/or 4, and some may support other values (like 30).
+Note:
+.I depth
+means the number of bits in a pixel that are actually used to determine
+the pixel colour.
+32 is not a valid
+.I depth
+value.
+Most hardware that uses 32 bits per pixel only uses 24 of them to hold the
+colour information, which means that the colour depth is 24, not 32.
+.TP 7
+.BI "FbBpp " bpp
+This entry specifies the framebuffer format this
+.B Display
+subsection is to be used for.
+This entry is only needed when providing depth 24 configurations that allow
+a choice between a 24 bpp packed framebuffer format and a 32bpp sparse
+framebuffer format.
+In most cases this entry should not be used.
+.TP 7
+.BI "Weight " "red\-weight green\-weight blue\-weight"
+This optional entry specifies the relative RGB weighting to be used
+for a screen is being used at depth 16 for drivers that allow multiple
+formats.
+This may also be specified from the command line with the
+.B \-weight
+option (see
+.BR __xservername__(__appmansuffix__)).
+.TP 7
+.BI "Virtual " "xdim ydim"
+This optional entry specifies the virtual screen resolution to be used.
+.I xdim
+must be a multiple of either 8 or 16 for most drivers, and a multiple
+of 32 when running in monochrome mode.
+The given value will be rounded down if this is not the case.
+Video modes which are too large for the specified virtual size will be
+rejected.
+If this entry is not present, the virtual screen resolution will be set to
+accommodate all the valid video modes given in the
+.B Modes
+entry.
+Some drivers/hardware combinations do not support virtual screens.
+Refer to the appropriate driver\-specific documentation for details.
+.TP 7
+.BI "ViewPort " "x0 y0"
+This optional entry sets the upper left corner of the initial display.
+This is only relevant when the virtual screen resolution is different
+from the resolution of the initial video mode.
+If this entry is not given, then the initial display will be centered in
+the virtual display area.
+.TP 7
+.BI "Modes \*q" mode\-name \*q " ..."
+This optional entry specifies the list of video modes to use.
+Each
+.I mode\-name
+specified must be in double quotes.
+They must correspond to those specified or referenced in the appropriate
+.B Monitor
+section (including implicitly referenced built\-in VESA standard modes).
+The server will delete modes from this list which don't satisfy various
+requirements.
+The first valid mode in this list will be the default display mode for
+startup.
+The list of valid modes is converted internally into a circular list.
+It is possible to switch to the next mode with
+.B Ctrl+Alt+Keypad\-Plus
+and to the previous mode with
+.BR Ctrl+Alt+Keypad\-Minus .
+When this entry is omitted, the valid modes referenced by the appropriate
+.B Monitor
+section will be used. If the
+.B Monitor
+section contains no modes, then the selection will be taken from the
+built-in VESA standard modes.
+.TP 7
+.BI "Visual \*q" visual\-name \*q
+This optional entry sets the default root visual type.
+This may also be specified from the command line (see the
+.BR Xserver(__appmansuffix__)
+man page).
+The visual types available for depth 8 are (default is
+.BR PseudoColor ):
+.PP
+.RS 11
+.nf
+.B StaticGray
+.B GrayScale
+.B StaticColor
+.B PseudoColor
+.B TrueColor
+.B DirectColor
+.fi
+.RE
+.PP
+.RS 7
+The visual type available for the depths 15, 16 and 24 are (default is
+.BR TrueColor ):
+.PP
+.RS 4
+.nf
+.B TrueColor
+.B DirectColor
+.fi
+.RE
+.PP
+Not all drivers support
+.B DirectColor
+at these depths.
+.PP
+The visual types available for the depth 4 are (default is
+.BR StaticColor ):
+.PP
+.RS 4
+.nf
+.B StaticGray
+.B GrayScale
+.B StaticColor
+.B PseudoColor
+.fi
+.RE
+.PP
+The visual type available for the depth 1 (monochrome) is
+.BR StaticGray .
+.RE
+.TP 7
+.BI "Black " "red green blue"
+This optional entry allows the \(lqblack\(rq colour to be specified.
+This is only supported at depth 1.
+The default is black.
+.TP 7
+.BI "White " "red green blue"
+This optional entry allows the \(lqwhite\(rq colour to be specified.
+This is only supported at depth 1.
+The default is white.
+.TP 7
+.B Options
+Option flags may be specified in the
+.B Display
+subsections.
+These may include driver\-specific options and driver\-independent options.
+The former are described in the driver\-specific documentation.
+Some of the latter are described above in the section about the
+.B Screen
+section, and they may also be included here.
+.SH "SERVERLAYOUT SECTION"
+The config file may have multiple
+.B ServerLayout
+sections.
+A \(lqserver layout\(rq represents the binding of one or more screens
+.RB ( Screen
+sections) and one or more input devices
+.RB ( InputDevice
+sections) to form a complete configuration.
+In multi\-head configurations, it also specifies the relative layout of the
+heads.
+A
+.B ServerLayout
+section is considered \(lqactive\(rq if it is referenced by the
+.B \-layout
+command line option or by an
+.B "Option \*qDefaultServerLayout\*q"
+entry in the
+.B ServerFlags
+section (the former takes precedence over the latter).
+If those options are not used, the first
+.B ServerLayout
+section found in the config file is considered the active one.
+If no
+.B ServerLayout
+sections are present, the single active screen and two active (core)
+input devices are selected as described in the relevant sections above.
+.PP
+.B ServerLayout
+sections have the following format:
+.PP
+.RS 4
+.nf
+.B "Section \*qServerLayout\*q"
+.BI " Identifier \*q" name \*q
+.BI " Screen \*q" screen\-id \*q
+.I " ..."
+.BI " InputDevice \*q" idev\-id \*q
+.I " ..."
+.I " options"
+.I " ..."
+.B "EndSection"
+.fi
+.RE
+.PP
+Each
+.B ServerLayout
+section must have an
+.B Identifier
+entry and at least one
+.B Screen
+entry.
+.PP
+The
+.B Identifier
+entry specifies the unique name for this server layout.
+The
+.B ServerLayout
+section provides information specific to the whole session, including
+session\-specific
+.BR Options .
+The
+.B ServerFlags
+options (described above) may be specified here, and ones given here
+override those given in the
+.B ServerFlags
+section.
+.PP
+The entries that may be used in this section are described here.
+.TP 7
+.BI "Screen " "screen\-num" " \*qscreen\-id\*q " "position\-information"
+One of these entries must be given for each screen being used in
+a session.
+The
+.I screen\-id
+field is mandatory, and specifies the
+.B Screen
+section being referenced.
+The
+.I screen\-num
+field is optional, and may be used to specify the screen number
+in multi\-head configurations.
+When this field is omitted, the screens will be numbered in the order that
+they are listed in.
+The numbering starts from 0, and must be consecutive.
+The
+.I position\-information
+field describes the way multiple screens are positioned.
+There are a number of different ways that this information can be provided:
+.RS 7
+.TP 4
+.I "x y"
+.TP 4
+.BI "Absolute " "x y"
+These both specify that the upper left corner's coordinates are
+.RI ( x , y ).
+The
+.B Absolute
+keyword is optional.
+Some older versions of XFree86 (4.2 and earlier) don't recognise the
+.B Absolute
+keyword, so it's safest to just specify the coordinates without it.
+.TP 4
+.BI "RightOf \*q" screen\-id \*q
+.TP 4
+.BI "LeftOf \*q" screen\-id \*q
+.TP 4
+.BI "Above \*q" screen\-id \*q
+.TP 4
+.BI "Below \*q" screen\-id \*q
+.TP 4
+.BI "Relative \*q" screen\-id \*q " x y"
+These give the screen's location relative to another screen.
+The first four position the screen immediately to the right, left, above or
+below the other screen.
+When positioning to the right or left, the top edges are aligned.
+When positioning above or below, the left edges are aligned.
+The
+.B Relative
+form specifies the offset of the screen's origin (upper left corner)
+relative to the origin of another screen.
+.RE
+.TP 7
+.BI "InputDevice \*q" idev\-id "\*q \*q" option \*q " ..."
+One of these entries should be given for each input device being used in
+a session.
+Normally at least two are required, one each for the core pointer and
+keyboard devices.
+If either of those is missing, suitable
+.B InputDevice
+entries are searched for using the method described above in the
+.B INPUTDEVICE
+section. The
+.I idev\-id
+field is mandatory, and specifies the name of the
+.B InputDevice
+section being referenced.
+Multiple
+.I option
+fields may be specified, each in double quotes.
+The options permitted here are any that may also be given in the
+.B InputDevice
+sections.
+Normally only session\-specific input device options would be used here.
+The most commonly used options are:
+.PP
+.RS 11
+.nf
+.B \*qCorePointer\*q
+.B \*qCoreKeyboard\*q
+.B \*qSendCoreEvents\*q
+.fi
+.RE
+.PP
+.RS 7
+and the first two should normally be used to indicate the core pointer
+and core keyboard devices respectively.
+.RE
+.TP 7
+.B Options
+In addition to the following, any option permitted in the
+.B ServerFlags
+section may also be specified here.
+When the same option appears in both places, the value given here overrides
+the one given in the
+.B ServerFlags
+section.
+.TP 7
+.BI "Option \*qIsolateDevice\*q \*q" bus\-id \*q
+Restrict device resets to the specified
+.IR bus\-id .
+See the
+.B BusID
+option (described in
+.BR "DEVICE SECTION" ,
+above) for the format of the
+.I bus\-id
+parameter.
+This option overrides
+.BR SingleCard ,
+if specified.
+At present, only PCI devices can be isolated in this manner.
+.TP 7
+.BI "Option \*qSingleCard\*q \*q" boolean \*q
+As
+.BR IsolateDevice ,
+except that the bus ID of the first device in the layout is used.
+.PP
+Here is an example of a
+.B ServerLayout
+section for a dual headed configuration with two mice:
+.PP
+.RS 4
+.nf
+.B "Section \*qServerLayout\*q"
+.B " Identifier \*qLayout 1\*q"
+.B " Screen \*qMGA 1\*q"
+.B " Screen \*qMGA 2\*q RightOf \*qMGA 1\*q"
+.B " InputDevice \*qKeyboard 1\*q \*qCoreKeyboard\*q"
+.B " InputDevice \*qMouse 1\*q \*qCorePointer\*q"
+.B " InputDevice \*qMouse 2\*q \*qSendCoreEvents\*q"
+.B " Option \*qBlankTime\*q \*q5\*q"
+.B "EndSection"
+.fi
+.RE
+.SH "DRI SECTION"
+This optional section is used to provide some information for the
+Direct Rendering Infrastructure.
+Details about the format of this section
+can be found in the README.DRI document, which is also available on-line at
+.IR <http://dri.freedesktop.org/> .
+.SH "VENDOR SECTION"
+The optional
+.B Vendor
+section may be used to provide vendor\-specific configuration information.
+Multiple
+.B Vendor
+sections may be present, and they may contain an
+.B Identifier
+entry and multiple
+.B Option
+flags.
+The data therein is not used in this release.
+.PP
+.SH "SEE ALSO"
+General:
+.BR X (__miscmansuffix__),
+.BR Xserver (__appmansuffix__),
+.BR __xservername__ (__appmansuffix__),
+.BR cvt (__appmansuffix__),
+.BR gtf (__appmansuffix__).
+.PP
+.B Not all modules or interfaces are available on all platforms.
+.PP
+Display drivers:
+.BR apm (__drivermansuffix__),
+.\" .BR ati (__drivermansuffix__),
+.BR chips (__drivermansuffix__),
+.BR cirrus (__drivermansuffix__),
+.BR cyrix (__drivermansuffix__),
+.BR fbdev (__drivermansuffix__),
+.BR glide (__drivermansuffix__),
+.BR glint (__drivermansuffix__),
+.BR i128 (__drivermansuffix__),
+.BR i740 (__drivermansuffix__),
+.BR i810 (__drivermansuffix__),
+.BR imstt (__drivermansuffix__),
+.BR mga (__drivermansuffix__),
+.BR neomagic (__drivermansuffix__),
+.BR nv (__drivermansuffix__),
+.BR r128 (__drivermansuffix__),
+.BR rendition (__drivermansuffix__),
+.BR savage (__drivermansuffix__),
+.BR s3virge (__drivermansuffix__),
+.BR siliconmotion (__drivermansuffix__),
+.BR sis (__drivermansuffix__),
+.BR sunbw2 (__drivermansuffix__),
+.BR suncg14 (__drivermansuffix__),
+.BR suncg3 (__drivermansuffix__),
+.BR suncg6 (__drivermansuffix__),
+.BR sunffb (__drivermansuffix__),
+.BR sunleo (__drivermansuffix__),
+.BR suntcx (__drivermansuffix__),
+.BR tdfx (__drivermansuffix__),
+.BR tga (__drivermansuffix__),
+.BR trident (__drivermansuffix__),
+.BR tseng (__drivermansuffix__),
+.BR vesa (__drivermansuffix__),
+.BR vga (__drivermansuffix__),
+.BR via (__drivermansuffix__),
+.BR vmware (__drivermansuffix__).
+.PP
+Input drivers:
+.\" .BR acecad (__drivermansuffix__),
+.\" .BR calcomp (__drivermansuffix__),
+.BR citron (__drivermansuffix__),
+.BR dmc (__drivermansuffix__),
+.BR dynapro (__drivermansuffix__),
+.BR elographics (__drivermansuffix__),
+.BR fpit (__drivermansuffix__),
+.BR js_x (__drivermansuffix__),
+.BR kbd (__drivermansuffix__),
+.BR keyboard (__drivermansuffix__),
+.\" .BR magictouch (__drivermansuffix__),
+.BR microtouch (__drivermansuffix__),
+.BR mouse (__drivermansuffix__),
+.BR mutouch (__drivermansuffix__),
+.BR palmax (__drivermansuffix__),
+.BR penmount (__drivermansuffix__),
+.BR tek4957 (__drivermansuffix__),
+.\" .BR ur98 (__drivermansuffix__),
+.BR void (__drivermansuffix__),
+.BR wacom (__drivermansuffix__).
+.PP
+Other modules and interfaces:
+.BR fbdevhw (__drivermansuffix__),
+.\" .BR shadowfb (__drivermansuffix__),
+.BR v4l (__drivermansuffix__).
+.br
+.SH AUTHORS
+This manual page was largely rewritten by David Dawes
+.IR <dawes@xfree86.org> .
diff --git a/xorg-server/hw/xfree86/doc/sgml/DESIGN.sgml b/xorg-server/hw/xfree86/doc/sgml/DESIGN.sgml
new file mode 100644
index 000000000..5beff653f
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/sgml/DESIGN.sgml
@@ -0,0 +1,7414 @@
+<!DOCTYPE linuxdoc PUBLIC "-//Xorg//DTD linuxdoc//EN" [
+ <!ENTITY % defs SYSTEM "defs.ent"> %defs;
+ <!-- config file keyword markup -->
+ <!ENTITY s.key STARTTAG "bf">
+ <!ENTITY e.key ENDTAG "bf">
+ <!-- specific config file keywords -->
+ <!ENTITY k.device "&s.key;Device&e.key;">
+ <!ENTITY k.monitor "&s.key;Monitor&e.key;">
+ <!ENTITY k.display "&s.key;Display&e.key;">
+ <!ENTITY k.inputdevice "&s.key;InputDevice&e.key;">
+ <!ENTITY k.screen "&s.key;Screen&e.key;">
+ <!ENTITY k.serverlayout "&s.key;ServerLayout&e.key;">
+ <!ENTITY k.driver "&s.key;Driver&e.key;">
+ <!ENTITY k.module "&s.key;Module&e.key;">
+ <!ENTITY k.identifier "&s.key;Identifier&e.key;">
+ <!ENTITY k.serverflags "&s.key;ServerFlags&e.key;">
+ <!-- command line markup -->
+ <!ENTITY s.cmd STARTTAG "tt">
+ <!ENTITY e.cmd ENDTAG "tt">
+ <!-- inline code markup -->
+ <!ENTITY s.code STARTTAG "tt">
+ <!ENTITY e.code ENDTAG "tt">
+ <!-- function indent -->
+ <!ENTITY f.indent "&nl&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp">
+] >
+
+<article>
+
+<title>XFree86 server 4.x Design (DRAFT)
+<author>The XFree86 Project, Inc
+<and>Updates for X11R&relvers; by Jim Gettys
+<date>19 December 2003
+
+
+
+
+
+
+
+<ident>
+$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DESIGN.sgml,v 1.53 2003/08/23 14:10:14 dawes Exp $
+</ident>
+
+
+<p>
+<bf>NOTE</bf>: This is a DRAFT document, and the interfaces described here
+are subject to change without notice.
+
+
+<sect>Preface
+<p>
+
+The broad design principles are:
+<itemize>
+ <item>keep it reasonable
+ <itemize>
+ <item>We cannot rewrite the complete server
+ <item>We don't want to re-invent the wheel
+ </itemize>
+ <item>keep it modular
+ <itemize>
+ <item>As many things as possible should go into modules
+ <item>The basic loader binary should be minimal
+ <item>A clean design with well defined layering is important
+ <item>DDX specific global variables are a nono
+ <item>The structure should be flexible enough to allow
+ future extensions
+ <item> The structure should minimize duplication of common code
+ </itemize>
+ <item>keep important features in mind
+ <itemize>
+ <item>multiple screens, including multiple instances of drivers
+ <item>mixing different color depths and visuals on different
+ and ideally even on the same screen
+ <item>better control of the PCI device used
+ <item>better config file parser
+ <item>get rid of all VGA compatibility assumptions
+ </itemize>
+</itemize>
+
+Unless we find major deficiencies in the DIX layer, we should avoid
+making changes there.
+
+<sect>The xorg.conf File
+<p>
+
+The xorg.conf file format is similar to the old format, with the following
+changes:
+
+<sect1>&k.device; section
+<p>
+
+ The &k.device; sections are similar to what they used to be, and
+ describe hardware-specific information for a single video card.
+ &k.device;
+ Some new keywords are added:
+
+
+ <descrip>
+ <tag>Driver "drivername"</tag>
+ Specifies the name of the driver to be used for the card. This
+ is mandatory.
+ <tag>BusID "busslot"</tag>
+ Specifies uniquely the location of the card on the bus. The
+ purpose is to identify particular cards in a multi-headed
+ configuration. The format of the argument is intentionally
+ vague, and may be architecture dependent. For a PCI bus, it
+ is something like "bus:slot:func".
+ </descrip>
+
+ A &k.device; section is considered ``active'' if there is a reference
+ to it in an active &k.screen; section.
+
+<sect1>&k.screen; section
+<p>
+
+ The &k.screen; sections are similar to what they used to be. They
+ no longer have a &k.driver; keyword, but an &k.identifier; keyword
+ is added. (The &k.driver; keyword may be accepted in place of the
+ &k.identifier; keyword for compatibility purposes.) The identifier
+ can be used to identify which screen is to be active when multiple
+ &k.screen sections are present. It is possible to specify the active
+ screen from the command line. A default is chosen in the absence
+ of one being specified. A &k.screen; section is considered ``active''
+ if there is a reference to it either from the command line, or from
+ an active &k.serverlayout; section.
+
+<sect1>&k.inputdevice; section
+<p>
+
+ The &k.inputdevice; section is a new section that describes
+ configuration information for input devices. It replaces the old
+ &s.key;Keyboard&e.key;, &s.key;Pointer&e.key; and &s.key;XInput&e.key;
+ sections. Like the &k.device; section, it has two mandatory keywords:
+ &k.identifier; and &k.driver;. For compatibility purposes the old
+ &s.key;Keyboard&e.key; and &s.key;Pointer&e.key; sections are
+ converted by the parser into &k.inputdevice; sections as follows:
+
+ <descrip>
+ <tag>&s.key;Keyboard&e.key;</tag>
+ &k.identifier; "Implicit Core Keyboard"<newline>
+ &k.driver; "keyboard"
+ <tag>&s.key;Pointer&e.key;</tag>
+ &k.identifier; "Implicit Core Pointer"<newline>
+ &k.driver; "mouse"
+ </descrip>
+
+ An &k.inputdevice; section is considered active if there is a
+ reference to it in an active &k.serverlayout; section. An
+ &k.inputdevice; section may also be referenced implicitly if there
+ is no &k.serverlayout; section, if the &s.cmd;-screen&e.cmd; command
+ line options is used, or if the &k.serverlayout; section doesn't
+ reference any &k.inputdevice; sections. In this case, the first
+ sections with drivers "keyboard" and "mouse" are used as the core
+ keyboard and pointer respectively.
+
+<sect1>&k.serverlayout; section
+<p>
+
+ The &k.serverlayout; section is a new section that is used to identify
+ which &k.screen; sections are to be used in a multi-headed configuration,
+ and the relative layout of those screens. It also identifies which
+ &k.inputdevice; sections are to be used. Each &k.serverlayout section
+ has an identifier, a list of &k.screen; section identifiers, and a list of
+ &k.inputdevice; section identifiers. &k.serverflags; options may also be
+ included in a &k.serverlayout; section, making it possible to override
+ the global values in the &k.serverflags; section.
+
+ A &k.serverlayout; section can be made active by being referenced on
+ the command line. In the absence of this, a default will be chosen
+ (the first one found). The screen names may optionally be followed
+ by a number specifying the preferred screen number, and optionally
+ by information specifying the physical positioning of the screen,
+ either in absolute terms or relative to another screen (or screens).
+ When no screen number is specified, they are numbered according to
+ the order in which they are listed. The old (now obsolete) method
+ of providing the positioning information is to give the names of
+ the four adjacent screens. The order of these is top, bottom, left,
+ right. Here is an example of a &k.serverlayout; section for two
+ screens using the old method, with the second located to the right
+ of the first:
+
+ <code>
+ Section "ServerLayout"
+ Identifier "Main Layout"
+ Screen 0 "Screen 1" "" "" "" "Screen 2"
+ Screen 1 "Screen 2"
+ Screen "Screen 3"
+ EndSection
+ </code>
+
+ The preferred way of specifying the layout is to explicitly specify
+ the screen's location in absolute terms or relative to another
+ screen.
+
+ In the absolute case, the upper left corner's coordinates are given
+ after the &s.key;Absolute&e.key; keyword. If the coordinates are
+ omitted, a value of &s.code;(0,0)&e.code; is assumed. An example
+ of absolute positioning follows:
+
+ <code>
+ Section "ServerLayout"
+ Identifier "Main Layout"
+ Screen 0 "Screen 1" Absolute 0 0
+ Screen 1 "Screen 2" Absolute 1024 0
+ Screen "Screen 3" Absolute 2048 0
+ EndSection
+ </code>
+
+ In the relative case, the position is specified by either using one of
+ the following keywords followed by the name of the reference screen:
+
+ <quote>
+ &s.key;RightOf&nl;
+ LeftOf&nl;
+ Above&nl;
+ Below&nl;
+ Relative&e.key;
+ </quote>
+
+ When the &s.key;Relative&e.key; keyword is used, the reference screen
+ name is followed by the coordinates of the new screen's origin
+ relative to reference screen. The following example shows how to use
+ some of the relative positioning options.
+
+ <code>
+ Section "ServerLayout"
+ Identifier "Main Layout"
+ Screen 0 "Screen 1"
+ Screen 1 "Screen 2" RightOf "Screen 1"
+ Screen "Screen 3" Relative "Screen 1" 2048 0
+ EndSection
+ </code>
+
+<sect1>Options
+<p>
+
+ Options are used more extensively. They may appear in most sections
+ now. Options related to drivers can be present in the &k.screen;,
+ &k.device; and &k.monitor; sections and the &k.display; subsections.
+ The order of precedence is &k.display;, &k.screen;, &k.monitor;,
+ &k.device;. Options have been extended to allow an optional value
+ to be specified in addition to the option name. For more details
+ about options, see the <ref id="options" name="Options"> section
+ for details.
+
+<sect>Driver Interface
+<p>
+
+The driver interface consists of a minimal set of entry points that are
+required based on the external events that the driver must react to.
+No non-essential structure is imposed on the way they are used beyond
+that. This is a significant difference compared with the old design.
+
+The entry points for drawing operations are already taken care of by
+the framebuffer code (including, XAA). Extensions and enhancements to
+framebuffer code are outside the scope of this document.
+
+This approach to the driver interface provides good flexibility, but does
+increase the complexity of drivers. To help address this, the XFree86
+common layer provides a set of ``helper'' functions to take care of things
+that most drivers need. These helpers help minimise the amount of code
+duplication between drivers. The use of helper functions by drivers is
+however optional, though encouraged. The basic philosophy behind the
+helper functions is that they should be useful to many drivers, that
+they should balance this against the complexity of their interface. It
+is inevitable that some drivers may find some helpers unsuitable and
+need to provide their own code.
+
+Events that a driver needs to react to are:
+
+ <descrip>
+ <tag>ScreenInit</tag>
+
+ An initialisation function is called from the DIX layer for each
+ screen at the start of each server generation.
+
+ <tag>Enter VT</tag>
+
+ The server takes control of the console.
+
+ <tag>Leave VT</tag>
+
+ The server releases control of the console.
+
+ <tag>Mode Switch</tag>
+
+ Change video mode.
+
+ <tag>ViewPort change</tag>
+
+ Change the origin of the physical view port.
+
+ <tag>ScreenSaver state change</tag>
+
+ Screen saver activation/deactivation.
+
+ <tag>CloseScreen</tag>
+
+ A close screen function is called from the DIX layer for each screen
+ at the end of each server generation.
+ </descrip>
+
+
+In addition to these events, the following functions are required by
+the XFree86 common layer:
+
+ <descrip>
+ <tag>Identify</tag>
+
+ Print a driver identifying message.
+
+ <tag>Probe</tag>
+
+ This is how a driver identifies if there is any hardware present that
+ it knows how to drive.
+
+ <tag>PreInit</tag>
+
+ Process information from the xorg.conf file, determine the
+ full characteristics of the hardware, and determine if a valid
+ configuration is present.
+ </descrip>
+
+The VidMode extension also requires:
+
+ <descrip>
+ <tag>ValidMode</tag>
+
+ Identify if a new mode is usable with the current configuration.
+ The PreInit function (and/or helpers it calls) may also make use
+ of the ValidMode function or something similar.
+ </descrip>
+
+
+Other extensions may require other entry points. The drivers will
+inform the common layer of these in such cases.
+
+<sect>Resource Access Control Introduction
+<p>
+
+Graphics devices are accessed through ranges in I/O or memory space.
+While most modern graphics devices allow relocation of such ranges many
+of them still require the use of well established interfaces such as
+VGA memory and IO ranges or 8514/A IO ranges. With modern buses (like
+PCI) it is possible for multiple video devices to share access to these
+resources. The RAC (Resource Access Control) subsystem provides a
+mechanism for this.
+
+<sect1>Terms and Definitions
+<p>
+
+<sect2>Bus
+<p>
+
+ ``Bus'' is ambiguous as it is used for different things: it may refer
+ to physical incompatible extension connectors in a computer system.
+ The RAC system knows two such systems: The ISA bus and the PCI bus.
+ (On the software level EISA, MCA and VL buses are currently treated
+ like ISA buses). ``Bus'' may also refer to logically different
+ entities on a single bus system which are connected via bridges. A
+ PCI system may have several distinct PCI buses connecting each other
+ by PCI-PCI bridges or to the host CPU by HOST-PCI bridges.
+
+ Systems that host more than one bus system link these together using
+ bridges. Bridges are a concern to RAC as they might block or pass
+ specific resources. PCI-PCI bridges may be set up to pass VGA
+ resources to the secondary bus. PCI-ISA buses pass any resources not
+ decoded on the primary PCI bus to the ISA bus. This way VGA resources
+ (although exclusive on the ISA bus) can be shared by ISA and PCI
+ cards. Currently HOST-PCI bridges are not yet handled by RAC as they
+ require specific drivers.
+
+<sect2>Entity
+<p>
+
+ The smallest independently addressable unit on a system bus is
+ referred to as an entity. So far we know ISA and PCI entities. PCI
+ entities can be located on the PCI bus by an unique ID consisting of
+ the bus, card and function number.
+
+<sect2>Resource
+<p>
+
+ ``Resource'' refers to a range of memory or I/O addresses an entity
+ can decode.
+
+ If a device is capable of disabling this decoding the resource is
+ called sharable. For PCI devices a generic method is provided to
+ control resource decoding. Other devices will have to provide a
+ device specific function to control decoding.
+
+ If the entity is capable of decoding this range at a different
+ location this resource is considered relocatable.
+
+ Resources which start at a specific address and occupy a single
+ continuous range are called block resources.
+
+ Alternatively resource addresses can be decoded in a way that they
+ satisfy the conditions:
+ <quote><verb>
+ address & mask == base
+ </verb></quote>
+ and
+ <quote><verb>
+ base & mask == base
+ </verb></quote>
+ Resources addressed in such a way are called sparse resources.
+
+<sect2>Server States
+<p>
+
+ The resource access control system knows two server states: the
+ SETUP and the OPERATING state. The SETUP state is entered whenever
+ a mode change takes place or the server exits or does VT switching.
+ During this state all entity resources are under resource access
+ control. During OPERATING state only those entities are controlled
+ which actually have shared resources that conflict with others.
+
+<sect>Control Flow in the Server and Mandatory Driver Functions
+<p>
+
+At the start of each server generation, &s.code;main()&e.code;
+(&s.code;dix/main.c&e.code;) calls the DDX function
+&s.code;InitOutput()&e.code;. This is the first place that the DDX gets
+control. &s.code;InitOutput()&e.code; is expected to fill in the global
+&s.code;screenInfo&e.code; struct, and one
+&s.code;screenInfo.screen[]&e.code; entry for each screen present. Here
+is what &s.code;InitOutput()&e.code; does:
+
+<sect1>Parse the xorg.conf file
+<p>
+
+ This is done at the start of the first server generation only.
+
+ The xorg.conf file is read in full, and the resulting information
+ stored in data structures. None of the parsed information is
+ processed at this point. The parser data structures are opaque to
+ the video drivers and to most of the common layer code.
+
+ The entire file is parsed first to remove any section ordering
+ requirements.
+
+
+<sect1>Initial processing of parsed information and command line options
+<p>
+
+ This is done at the start of the first server generation only.
+
+ The initial processing is to determine paths like the
+ &s.key;ModulePath&e.key;, etc, and to determine which &k.serverlayout;,
+ &k.screen; and &k.device; sections are active.
+
+
+<sect1>Enable port I/O access
+<p>
+
+ Port I/O access is controlled from the XFree86 common layer, and is
+ ``all or nothing''. It is enabled prior to calling driver probes, at
+ the start of subsequent server generations, and when VT switching
+ back to the Xserver. It is disabled at the end of server generations,
+ and when VT switching away from the Xserver.
+
+ The implementation details of this may vary on different platforms.
+
+
+<sect1>General bus probe
+<p>
+
+ This is done at the start of the first server generation only.
+
+ In the case of ix86 machines, this will be a general PCI probe.
+ The full information obtained here will be available to the drivers.
+ This information persists for the life of the Xserver. In the PCI
+ case, the PCI information for all video cards found is available by
+ calling &s.code;xf86GetPciVideoInfo()&e.code;.
+
+ <quote>
+ &s.code;pciVideoPtr *xf86GetPciVideoInfo(void)&e.code;
+ <quote><p>
+ returns a pointer to a list of pointers to
+ &s.code;pciVideoRec&e.code; entries, of which there is one for
+ each detected PCI video card. The list is terminated with a
+ &s.code;NULL&e.code; pointer. If no PCI video cards were
+ detected, the return value is &s.code;NULL&e.code;.
+
+ </quote>
+ </quote>
+
+ After the bus probe, the resource broker is initialised.
+
+
+<sect1>Load initial set of modules
+<p>
+
+ This is done at the start of the first server generation only.
+
+ The core server contains a list of mandatory modules. These are loaded
+ first. Currently the only module on this list is the bitmap font module.
+
+ The next set of modules loaded are those specified explicitly in the
+ &k.module; section of the config file.
+
+ The final set of initial modules are the driver modules referenced
+ by the active &k.device; and &k.inputdevice; sections in the config
+ file. Each of these modules is loaded exactly once.
+
+
+<sect1>Register Video and Input Drivers
+<p>
+
+ This is done at the start of the first server generation only.
+
+ When a driver module is loaded, the loader calls its
+ &s.code;Setup&e.code; function. For video drivers, this function
+ calls &s.code;xf86AddDriver()&e.code; to register the driver's
+ &s.code;DriverRec&e.code;, which contains a small set of essential
+ details and driver entry points required during the early phase of
+ &s.code;InitOutput()&e.code;. &s.code;xf86AddDriver()&e.code; adds
+ it to the global &s.code;xf86DriverList[]&e.code; array.
+
+ The &s.code;DriverRec&e.code; contains the driver canonical name,
+ the &s.code;Identify()&e.code;,
+ &s.code;Probe()&e.code; and &s.code;AvailableOptions()&e.code;
+ function entry points as well as a pointer
+ to the driver's module (as returned from the loader when the driver
+ was loaded) and a reference count which keeps track of how many
+ screens are using the driver. The entry driver entry points are
+ those required prior to the driver allocating and filling in its
+ &s.code;ScrnInfoRec&e.code;.
+
+ For a static server, the &s.code;xf86DriverList[]&e.code; array is
+ initialised at build time, and the loading of modules is not done.
+
+ A similar procedure is used for input drivers. The input driver's
+ &s.code;Setup&e.code; function calls
+ &s.code;xf86AddInputDriver()&e.code; to register the driver's
+ &s.code;InputDriverRec&e.code;, which contains a small set of
+ essential details and driver entry points required during the early
+ phase of &s.code;InitInput()&e.code;.
+ &s.code;xf86AddInputDriver()&e.code; adds it to the global
+ &s.code;xf86InputDriverList[]&e.code; array. For a static server,
+ the &s.code;xf86InputDriverList[]&e.code; array is initialised at
+ build time.
+
+ Both the &s.code;xf86DriverList[]&e.code; and
+ &s.code;xf86InputDriverList[]&e.code; arrays have been initialised
+ by the end of this stage.
+
+ Once all the drivers are registered, their
+ &s.code;ChipIdentify()&e.code; functions are called.
+
+ <quote>
+ &s.code;void ChipIdentify(int flags)&e.code;
+ <quote>
+ This is expected to print a message indicating the driver name,
+ a short summary of what it supports, and a list of the chipset
+ names that it supports. It may use the xf86PrintChipsets() helper
+ to do this.
+ </quote>
+ </quote>
+
+ <quote>
+ &s.code;void xf86PrintChipsets(const char *drvname, const char *drvmsg,
+ &f.indent;SymTabPtr chips)&e.code;
+ <quote>
+ This function provides an easy way for a driver's ChipIdentify
+ function to format the identification message.
+ </quote>
+ </quote>
+
+<sect1>Initialise Access Control
+<p>
+
+ This is done at the start of the first server generation only.
+
+ The Resource Access Control (RAC) subsystem is initialised before
+ calling any driver functions that may access hardware. All generic
+ bus information is probed and saved (for restoration later). All
+ (shared resource) video devices are disabled at the generic bus
+ level, and a probe is done to find the ``primary'' video device. These
+ devices remain disabled for the next step.
+
+
+<sect1>Video Driver Probe<label id="probe">
+<p>
+ This is done at the start of the first server generation only. The
+ &s.code;ChipProbe()&e.code; function of each registered video driver
+ is called.
+
+ <quote><p>
+ &s.code;Bool ChipProbe(DriverPtr drv, int flags)&e.code;
+ <quote><p>
+ The purpose of this is to identify all instances of hardware
+ supported by the driver. The flags value is currently either 0,
+ &s.code;PROBE_DEFAULT&e.code; or &s.code;PROBE_DETECT&e.code;.
+ &s.code;PROBE_DETECT&e.code; is used if "-configure" or "-probe"
+ command line arguments are given and indicates to the
+ &s.code;Probe()&e.code; function that it should not configure the
+ bus entities and that no xorg.conf information is available.
+
+ The probe must find the active device sections that match the
+ driver by calling &s.code;xf86MatchDevice()&e.code;. The number
+ of matches found limits the maximum number of instances for this
+ driver. If no matches are found, the function should return
+ &s.code;FALSE&e.code; immediately.
+
+ Devices that cannot be identified by using device-independent
+ methods should be probed at this stage (keeping in mind that access
+ to all resources that can be disabled in a device-independent way
+ are disabled during this phase). The probe must be a minimal
+ probe. It should just determine if there is a card present that
+ the driver can drive. It should use the least intrusive probe
+ methods possible. It must not do anything that is not essential,
+ like probing for other details such as the amount of memory
+ installed, etc. It is recommended that the
+ &s.code;xf86MatchPciInstances()&e.code; helper function be used
+ for identifying matching PCI devices, and similarly the
+ &s.code;xf86MatchIsaInstances()&e.code; for ISA (non-PCI) devices
+ (see the <ref id="rac" name="RAC"> section). These helpers also
+ checks and claims the appropriate entity. When not using the
+ helper, that should be done with &s.code;xf86CheckPciSlot()&e.code;
+ and &s.code;xf86ClaimPciSlot()&e.code; for PCI devices and
+ &s.code;xf86ClaimIsaSlot()&e.code; for ISA devices (see the
+ <ref id="rac" name="RAC"> section).
+
+ The probe must register all non-relocatable resources at this
+ stage. If a resource conflict is found between exclusive resources
+ the driver will fail immediately. This is usually best done with
+ the &s.code;xf86ConfigPciEntity()&e.code; helper function
+ for PCI and &s.code;xf86ConfigIsaEntity()&e.code; for ISA
+ (see the <ref id="rac" name="RAC"> section). It is possible to
+ register some entity specific functions with those helpers. When
+ not using the helpers, the &s.code;xf86AddEntityToScreen()&e.code;
+ &s.code;xf86ClaimFixedResources()&e.code; and
+ &s.code;xf86SetEntityFuncs()&e.code; should be used instead (see
+ the <ref id="rac" name="RAC"> section).
+
+ If a chipset is specified in an active device section which the
+ driver considers relevant (ie it has no driver specified, or the
+ driver specified matches the driver doing the probe), the Probe
+ must return &s.code;FALSE&e.code; if the chipset doesn't match
+ one supported by the driver.
+
+ If there are no active device sections that the driver considers
+ relevant, it must return &s.code;FALSE&e.code;.
+
+ Allocate a &s.code;ScrnInfoRec&e.code; for each active instance of the
+ hardware found, and fill in the basic information, including the
+ other driver entry points. This is best done with the
+ &s.code;xf86ConfigIsaEntity()&e.code; helper function for ISA
+ instances or &s.code;xf86ConfigPciEntity()&e.code; for PCI instances.
+ These functions allocate a &s.code;ScrnInfoRec&e.code; for active
+ entities. Optionally &s.code;xf86AllocateScreen()&e.code;
+ function may also be used to allocate the &s.code;ScrnInfoRec&e.code;.
+ Any of these functions take care of initialising fields to defined
+ ``unused'' values.
+
+ Claim the entities for each instance of the hardware found. This
+ prevents other drivers from claiming the same hardware.
+
+ Must leave hardware in the same state it found it in, and must not
+ do any hardware initialisation.
+
+ All detection can be overridden via the config file, and that
+ parsed information is available to the driver at this stage.
+
+ Returns &s.code;TRUE&e.code; if one or more instances are found,
+ and &s.code;FALSE&e.code; otherwise.
+
+ </quote>
+
+ &s.code;int xf86MatchDevice(const char *drivername,
+ &f.indent;GDevPtr **driversectlist)&e.code;
+ <quote><p>
+
+ This function takes the name of the driver and returns via
+ &s.code;driversectlist&e.code; a list of device sections that
+ match the driver name. The function return value is the number
+ of matches found. If a fatal error is encountered the return
+ value is &s.code;-1&e.code;.
+
+ The caller should use &s.code;xfree()&e.code; to free
+ &s.code;*driversectlist&e.code; when it is no longer needed.
+
+ </quote>
+
+ &s.code;ScrnInfoPtr xf86AllocateScreen(DriverPtr drv, int flags)&e.code;
+ <quote><p>
+ This function allocates a new &s.code;ScrnInfoRec&e.code; in the
+ &s.code;xf86Screens[]&e.code; array. This function is normally
+ called by the video driver &s.code;ChipProbe()&e.code; functions.
+ The return value is a pointer to the newly allocated
+ &s.code;ScrnInfoRec&e.code;. The &s.code;scrnIndex&e.code;,
+ &s.code;origIndex&e.code;, &s.code;module&e.code; and
+ &s.code;drv&e.code; fields are initialised. The reference count
+ in &s.code;drv&e.code; is incremented. The storage for any
+ currently allocated ``privates'' pointers is also allocated and
+ the &s.code;privates&e.code; field initialised (the privates data
+ is of course not allocated or initialised). This function never
+ returns on failure. If the allocation fails, the server exits
+ with a fatal error. The flags value is not currently used, and
+ should be set to zero.
+ </quote>
+ </quote>
+
+ At the completion of this, a list of &s.code;ScrnInfoRecs&e.code;
+ have been allocated in the &s.code;xf86Screens[]&e.code; array, and
+ the associated entities and fixed resources have been claimed. The
+ following &s.code;ScrnInfoRec&e.code; fields must be initialised at
+ this point:
+
+ <quote><verb>
+ driverVersion
+ driverName
+ scrnIndex(*)
+ origIndex(*)
+ drv(*)
+ module(*)
+ name
+ Probe
+ PreInit
+ ScreenInit
+ EnterVT
+ LeaveVT
+ numEntities
+ entityList
+ access
+ </verb></quote>
+
+ <tt>(*)</tt> These are initialised when the &s.code;ScrnInfoRec&e.code;
+ is allocated, and not explicitly by the driver.
+
+ The following &s.code;ScrnInfoRec&e.code; fields must be initialised
+ if the driver is going to use them:
+
+ <quote><verb>
+ SwitchMode
+ AdjustFrame
+ FreeScreen
+ ValidMode
+ </verb></quote>
+
+<sect1>Matching Screens
+<p>
+
+ This is done at the start of the first server generation only.
+
+ After the Probe phase is finished, there will be some number of
+ &s.code;ScrnInfoRecs&e.code;. These are then matched with the active
+ &k.screen; sections in the xorg.conf, and those not having an active
+ &k.screen; section are deleted. If the number of remaining screens
+ is 0, &s.code;InitOutput()&e.code; sets
+ &s.code;screenInfo.numScreens&e.code; to &s.code;0&e.code; and
+ returns.
+
+ At this point the following fields of the &s.code;ScrnInfoRecs&e.code;
+ must be initialised:
+
+ <quote><verb>
+ confScreen
+ </verb></quote>
+
+
+<sect1>Allocate non-conflicting resources
+<p>
+
+ This is done at the start of the first server generation only.
+
+ Before calling the drivers again, the resource information collected
+ from the Probe phase is processed. This includes checking the extent
+ of PCI resources for the probed devices, and resolving any conflicts
+ in the relocatable PCI resources. It also reports conflicts, checks
+ bus routing issues, and anything else that is needed to enable the
+ entities for the next phase.
+
+ If any drivers registered an &s.code;EntityInit()&e.code; function
+ during the Probe phase, then they are called here.
+
+
+<sect1>Sort the Screens and pre-check Monitor Information
+<p>
+
+ This is done at the start of the first server generation only.
+
+ The list of screens is sorted to match the ordering requested in the
+ config file.
+
+ The list of modes for each active monitor is checked against the
+ monitor's parameters. Invalid modes are pruned.
+
+
+<sect1>PreInit
+<p>
+
+ This is done at the start of the first server generation only.
+
+ For each &s.code;ScrnInfoRec&e.code;, enable access to the screens entities and call
+ the &s.code;ChipPreInit()&e.code; function.
+
+ <quote><p>
+ &s.code;Bool ChipPreInit(ScrnInfoRec screen, int flags)&e.code;
+ <quote><p>
+ The purpose of this function is to find out all the information
+ required to determine if the configuration is usable, and to
+ initialise those parts of the &s.code;ScrnInfoRec&e.code; that
+ can be set once at the beginning of the first server generation.
+
+ The number of entities registered for the screen should be checked
+ against the expected number (most drivers expect only one). The
+ entity information for each of them should be retrieved (with
+ &s.code;xf86GetEntityInfo()&e.code;) and checked for the correct
+ bus type and that none of the sharable resources registered during
+ the Probe phase was rejected.
+
+ Access to resources for the entities that can be controlled in a
+ device-independent way are enabled before this function is called.
+ If the driver needs to access any resources that it has disabled
+ in an &s.code;EntityInit()&e.code; function that it registered,
+ then it may enable them here providing that it disables them before
+ this function returns.
+
+ This includes probing for video memory, clocks, ramdac, and all
+ other HW info that is needed. It includes determining the
+ depth/bpp/visual and related info. It includes validating and
+ determining the set of video modes that will be used (and anything
+ that is required to determine that).
+
+ This information should be determined in the least intrusive way
+ possible. The state of the HW must remain unchanged by this
+ function. Although video memory (including MMIO) may be mapped
+ within this function, it must be unmapped before returning. Driver
+ specific information should be stored in a structure hooked into
+ the &s.code;ScrnInfoRec&e.code;'s &s.code;driverPrivate&e.code;
+ field. Any other modules which require persistent data (ie data
+ that persists across server generations) should be initialised in
+ this function, and they should allocate a ``privates'' index to
+ hook their data into by calling
+ &s.code;xf86AllocateScrnInfoPrivateIndex().&e.code; The ``privates''
+ data is persistent.
+
+ Helper functions for some of these things are provided at the
+ XFree86 common level, and the driver can choose to make use of
+ them.
+
+ All additional resources that the screen needs must be registered
+ here. This should be done with
+ &s.code;xf86RegisterResources()&e.code;. If some of the fixed
+ resources registered in the Probe phase are not needed or not
+ decoded by the hardware when in the OPERATING server state, their
+ status should be updated with
+ &s.code;xf86SetOperatingState()&e.code;.
+
+ Modules may be loaded at any point in this function, and all
+ modules that the driver will need must be loaded before the end
+ of this function. Either the &s.code;xf86LoadSubModule()&e.code;
+ or the &s.code;xf86LoadDrvSubModule()&e.code; function should be
+ used to load modules depending on whether a
+ &s.code;ScrnInfoRec&e.code; has been set up. A driver may unload
+ a module within this function if it was only needed temporarily,
+ and the &s.code;xf86UnloadSubModule()&e.code; function should be used
+ to do that. Otherwise there is no need to explicitly unload modules
+ because the loader takes care of module dependencies and will
+ unload submodules automatically if/when the driver module is
+ unloaded.
+
+ The bulk of the &s.code;ScrnInfoRec&e.code; fields should be filled
+ out in this function.
+
+ &s.code;ChipPreInit()&e.code; returns &s.code;FALSE&e.code; when
+ the configuration is unusable in some way (unsupported depth, no
+ valid modes, not enough video memory, etc), and &s.code;TRUE&e.code;
+ if it is usable.
+
+ It is expected that if the &s.code;ChipPreInit()&e.code; function
+ returns &s.code;TRUE&e.code;, then the only reasons that subsequent
+ stages in the driver might fail are lack or resources (like xalloc
+ failures). All other possible reasons for failure should be
+ determined by the &s.code;ChipPreInit()&e.code; function.
+
+ </quote>
+ </quote>
+
+ The &s.code;ScrnInfoRecs&e.code; for screens where the &s.code;ChipPreInit()&e.code; fails are removed.
+ If none remain, &s.code;InitOutput()&e.code; sets &s.code;screenInfo.numScreens&e.code; to &s.code;0&e.code; and returns.
+
+ At this point, further fields of the &s.code;ScrnInfoRecs&e.code; would normally be
+ filled in. Most are not strictly mandatory, but many are required
+ by other layers and/or helper functions that the driver may choose
+ to use. The documentation for those layers and helper functions
+ indicates which they require.
+
+ The following fields of the &s.code;ScrnInfoRecs&e.code; should be filled in if the
+ driver is going to use them:
+
+ <quote><verb>
+ monitor
+ display
+ depth
+ pixmapBPP
+ bitsPerPixel
+ weight (>8bpp only)
+ mask (>8bpp only)
+ offset (>8bpp only)
+ rgbBits (8bpp only)
+ gamma
+ defaultVisual
+ maxHValue
+ maxVValue
+ virtualX
+ virtualY
+ displayWidth
+ frameX0
+ frameY0
+ frameX1
+ frameY1
+ zoomLocked
+ modePool
+ modes
+ currentMode
+ progClock (TRUE if clock is programmable)
+ chipset
+ ramdac
+ clockchip
+ numClocks (if not programmable)
+ clock[] (if not programmable)
+ videoRam
+ biosBase
+ memBase
+ memClk
+ driverPrivate
+ chipID
+ chipRev
+ </verb></quote>
+
+ <quote><p>
+ &s.code;pointer xf86LoadSubModule(ScrnInfoPtr pScrn, const char *name)&e.code:
+ and
+ &s.code;pointer xf86LoadDrvSubModule(DriverPtr drv, const char *name)&e.code:
+ <quote><p>
+ Load a module that a driver depends on. This function loads the
+ module &s.code;name&e.code; as a sub module of the driver. The
+ return value is a handle identifying the new module. If the load
+ fails, the return value will be &s.code;NULL&e.code;. If a driver
+ needs to explicitly unload a module it has loaded in this way,
+ the return value must be saved and passed to
+ &s.code;xf86UnloadSubModule()&e.code; when unloading.
+
+ </quote>
+
+ &s.code;void xf86UnloadSubModule(pointer module)&e.code;
+ <quote><p>
+ Unloads the module referenced by &s.code;module&e.code;.
+ &s.code;module&e.code; should be a pointer returned previously
+ by &s.code;xf86LoadSubModule()&e.code; or
+ &s.code;xf86LoadDrvSubModule()&e.code; .
+
+ </quote>
+ </quote>
+
+<sect1>Cleaning up Unused Drivers
+<p>
+
+ At this point it is known which screens will be in use, and which
+ drivers are being used. Unreferenced drivers (and modules they
+ may have loaded) are unloaded here.
+
+
+<sect1>Consistency Checks
+<p>
+
+ The parameters that must be global to the server, like pixmap formats,
+ bitmap bit order, bitmap scanline unit and image byte order are
+ compared for each of the screens. If a mismatch is found, the server
+ exits with an appropriate message.
+
+
+<sect1>Check if Resource Control is Needed
+<p>
+
+ Determine if resource access control is needed. This is the case
+ if more than one screen is used. If necessary the RAC wrapper module
+ is loaded.
+
+<sect1>AddScreen (ScreenInit)
+<p>
+
+ At this point, the valid screens are known.
+ &s.code;AddScreen()&e.code; is called for each of them, passing
+ &s.code;ChipScreenInit()&e.code; as the argument.
+ &s.code;AddScreen()&e.code; is a DIX function that allocates a new
+ &s.code;screenInfo.screen[]&e.code; entry (aka
+ &s.code;pScreen&e.code;), and does some basic initialisation of it.
+ It then calls the &s.code;ChipScreenInit()&e.code; function, with
+ &s.code;pScreen&e.code; as one of its arguments. If
+ &s.code;ChipScreenInit()&e.code; returns &s.code;FALSE&e.code;,
+ &s.code;AddScreen()&e.code; returns &s.code;-1&e.code;. Otherwise
+ it returns the index of the screen. &s.code;AddScreen()&e.code;
+ should only fail because of programming errors or failure to allocate
+ resources (like memory). All configuration problems should be
+ detected BEFORE this point.
+
+ <quote><p>
+ &s.code;Bool ChipScreenInit(int index, ScreenPtr pScreen,
+ &f.indent;int argc, char **argv)&e.code;
+ <quote><p>
+ This is called at the start of each server generation.
+
+ Fill in all of &s.code;pScreen&e.code;, possibly doing some of
+ this by calling ScreenInit functions from other layers like mi,
+ framebuffers (cfb, etc), and extensions.
+
+ Decide which operations need to be placed under resource access
+ control. The classes of operations are the frame buffer operations
+ (&s.code;RAC_FB&e.code;), the pointer operations
+ (&s.code;RAC_CURSOR&e.code;), the viewport change operations
+ (&s.code;RAC_VIEWPORT&e.code;) and the colormap operations
+ (&s.code;RAC_COLORMAP&e.code;). Any operation that requires
+ resources which might be disabled during OPERATING state should
+ be set to use RAC. This can be specified separately for memory
+ and IO resources (the &s.code;racMemFlags&e.code; and
+ &s.code;racIoFlags&e.code; fields of the &s.code;ScrnInfoRec&e.code;
+ respectively).
+
+ Map any video memory or other memory regions.
+
+ Save the video card state. Enough state must be saved so that
+ the original state can later be restored.
+
+ Initialise the initial video mode. The &s.code;ScrnInfoRec&e.code;'s
+ &s.code;vtSema&e.code; field should be set to &s.code;TRUE&e.code;
+ just prior to changing the video hardware's state.
+
+ </quote>
+ </quote>
+
+
+ The &s.code;ChipScreenInit()&e.code; function (or functions from other
+ layers that it calls) should allocate entries in the
+ &s.code;ScreenRec&e.code;'s &s.code;devPrivates&e.code; area by
+ calling &s.code;AllocateScreenPrivateIndex()&e.code; if it needs
+ per-generation storage. Since the &s.code;ScreenRec&e.code;'s
+ &s.code;devPrivates&e.code; information is cleared for each server
+ generation, this is the correct place to initialise it.
+
+ After &s.code;AddScreen()&e.code; has successfully returned, the
+ following &s.code;ScrnInfoRec&e.code; fields are initialised:
+
+ <quote><verb>
+ pScreen
+ racMemFlags
+ racIoFlags
+ </verb></quote>
+
+ The &s.code;ChipScreenInit()&e.code; function should initialise the
+ &s.code;CloseScreen&e.code; and &s.code;SaveScreen&e.code; fields
+ of &s.code;pScreen&e.code;. The old value of
+ &s.code;pScreen-&gt;CloseScreen&e.code; should be saved as part of
+ the driver's per-screen private data, allowing it to be called from
+ &s.code;ChipCloseScreen()&e.code;. This means that the existing
+ &s.code;CloseScreen()&e.code; function is wrapped.
+
+<sect1>Finalising RAC Initialisation
+<p>
+
+ After all the &s.code;ChipScreenInit()&e.code; functions have been
+ called, each screen has registered its RAC requirements. This
+ information is used to determine which shared resources are requested
+ by more than one driver and set the access functions accordingly.
+ This is done following these rules:
+
+ <enum>
+ <item>The sharable resources registered by each entity are compared.
+ If a resource is registered by more than one entity the entity
+ will be marked to indicate that it needs to share this resources
+ type (IO or MEM).
+
+ <item>A resource marked ``disabled'' during OPERATING state will be
+ ignored entirely.
+
+ <item>A resource marked ``unused'' will only conflict with an overlapping
+ resource of an other entity if the second is actually in use
+ during OPERATING state.
+
+ <item>If an ``unused'' resource was found to conflict but the entity
+ does not use any other resource of this type the entire resource
+ type will be disabled for that entity.
+ </enum>
+
+
+<sect1>Finishing InitOutput()
+<p>
+
+ At this point &s.code;InitOutput()&e.code; is finished, and all the
+ screens have been setup in their initial video mode.
+
+
+<sect1>Mode Switching
+<p>
+
+ When a SwitchMode event is received, &s.code;ChipSwitchMode()&e.code;
+ is called (when it exists):
+
+ <quote><p>
+ &s.code;Bool ChipSwitchMode(int index, DisplayModePtr mode, int flags)&e.code;
+ <quote><p>
+ Initialises the new mode for the screen identified by
+ &s.code;index;&e.code;. The viewport may need to be adjusted
+ also.
+
+ </quote>
+ </quote>
+
+
+<sect1>Changing Viewport
+<p>
+
+ When a Change Viewport event is received,
+ &s.code;ChipAdjustFrame()&e.code; is called (when it exists):
+
+ <quote><p>
+ &s.code;void ChipAdjustFrame(int index, int x, int y, int flags)&e.code;
+ <quote><p>
+ Changes the viewport for the screen identified by
+ &s.code;index;&e.code;.
+
+ It should be noted that many chipsets impose restrictions on where the
+ viewport may be placed in the virtual resolution, either for alignment
+ reasons, or to prevent the start of the viewport from being positioned
+ within a pixel (as can happen in a 24bpp mode). After calculating the
+ value the chipset's panning registers need to be set to for non-DGA
+ modes, this function should recalculate the ScrnInfoRec's
+ &s.code;frameX0&e.code;, &s.code;frameY0&e.code, &s.code;frameX1&e.code;
+ and &s.code;frameY1&e.code; fields to correspond to that value. If
+ this is not done, switching to another mode might cause the position
+ of a hardware cursor to change.
+
+ </quote>
+ </quote>
+
+
+<sect1>VT Switching
+<p>
+
+ When a VT switch event is received, &s.code;xf86VTSwitch()&e.code;
+ is called. &s.code;xf86VTSwitch()&e.code; does the following:
+
+ <descrip>
+ <tag>On ENTER:</tag>
+ <itemize>
+ <item>enable port I/O access
+
+ <item>save and initialise the bus/resource state
+
+ <item>enter the SETUP server state
+
+ <item>calls &s.code;ChipEnterVT()&e.code; for each screen
+
+ <item>enter the OPERATING server state
+
+ <item>validate GCs
+
+ <item>Restore fb from saved pixmap for each screen
+
+ <item>Enable all input devices
+ </itemize>
+ <tag>On LEAVE:</tag>
+ <itemize>
+ <item>Save fb to pixmap for each screen
+
+ <item>validate GCs
+
+ <item>enter the SETUP server state
+
+ <item>calls &s.code;ChipLeaveVT()&e.code; for each screen
+
+ <item>disable all input devices
+
+ <item>restore bus/resource state
+
+ <item>disables port I/O access
+ </itemize>
+ </descrip>
+
+ <quote><p>
+ &s.code;Bool ChipEnterVT(int index, int flags)&e.code;
+ <quote><p>
+ This function should initialise the current video mode and
+ initialise the viewport, turn on the HW cursor if appropriate,
+ etc.
+
+ Should it re-save the video state before initialising the video
+ mode?
+
+ </quote>
+
+ &s.code;void ChipLeaveVT(int index, int flags)&e.code;
+ <quote><p>
+ This function should restore the saved video state. If
+ appropriate it should also turn off the HW cursor, and invalidate
+ any pixmap/font caches.
+
+ </quote>
+
+ Optionally, &s.code;ChipLeaveVT()&e.code; may also unmap memory
+ regions. If so, &s.code;ChipEnterVT()&e.code; will need to remap
+ them. Additionally, if an aperture used to access video memory is
+ unmapped and remapped in this fashion, &s.code;ChipEnterVT()&e.code;
+ will also need to notify the framebuffer layers of the aperture's new
+ location in virtual memory. This is done with a call to the screen's
+ &s.code;ModifyPixmapHeader()&e.code; function, as follows
+
+ <quote><p>
+ &s.code;(*pScreen->ModifyPixmapHeader)(pScrn->ppix,
+ &f.indent;-1, -1, -1, -1, -1, <it>NewApertureAddress</it>);&e.code;
+ <quote><p>
+ where the &s.code``ppix''&e.code; field in a ScrnInfoRec
+ points to the pixmap used by the screen's
+ &s.code;SaveRestoreImage()&e.code; function to hold the screen's
+ contents while switched out.
+
+ </quote>
+ </quote>
+
+ Currently, aperture remapping, as described here, should not be
+ attempted if the driver uses the &s.code;xf8_16bpp&e.code; or
+ &s.code;xf8_32bpp&e.code; framebuffer layers. A pending
+ restructuring of VT switching will address this restriction in
+ the near future.
+
+ </quote>
+
+ Other layers may wrap the &s.code;ChipEnterVT()&e.code; and
+ &s.code;ChipLeaveVT()&e.code; functions if they need to take some
+ action when these events are received.
+
+<sect1>End of server generation
+<p>
+
+ At the end of each server generation, the DIX layer calls
+ &s.code;ChipCloseScreen()&e.code; for each screen:
+
+ <quote><p>
+ &s.code;Bool ChipCloseScreen(int index, ScreenPtr pScreen)&e.code;
+ <quote><p>
+ This function should restore the saved video state and unmap the
+ memory regions.
+
+ It should also free per-screen data structures allocated by the
+ driver. Note that the persistent data held in the
+ &s.code;ScrnInfoRec&e.code;'s &s.code;driverPrivate&e.code; field
+ should not be freed here because it is needed by subsequent server
+ generations.
+
+ The &s.code;ScrnInfoRec&e.code;'s &s.code;vtSema&e.code; field
+ should be set to &s.code;FALSE&e.code; once the video HW state
+ has been restored.
+
+ Before freeing the per-screen driver data the saved
+ &s.code;CloseScreen&e.code; value should be restored to
+ &s.code;pScreen-&gt;CloseScreen&e.code;, and that function should
+ be called after freeing the data.
+
+ </quote>
+ </quote>
+
+<sect>Optional Driver Functions
+<p>
+
+The functions outlined here can be called from the XFree86 common layer,
+but their presence is optional.
+
+<sect1>Mode Validation
+<p>
+
+ When a mode validation helper supplied by the XFree86-common layer is
+ being used, it can be useful to provide a function to check for hw
+ specific mode constraints:
+
+ <quote><p>
+ &s.code;ModeStatus ChipValidMode(int index, DisplayModePtr mode,
+ &f.indent;Bool verbose, int flags)&e.code;
+ <quote><p>
+ Check the passed mode for hw-specific constraints, and return the
+ appropriate status value.
+
+ </quote>
+ </quote>
+
+<p>
+This function may also modify the effective timings and clock of the passed
+mode. These have been stored in the mode's &s.code;Crtc*&e.code; and
+&s.code;SynthClock&e.code; elements, and have already been adjusted for
+interlacing, doublescanning, multiscanning and clock multipliers and dividers.
+The function should not modify any other mode field, unless it wants to modify
+the mode timings reported to the user by &s.code;xf86PrintModes()&e.code;.
+
+<p>
+The function is called once for every mode in the xorg.conf Monitor section
+assigned to the screen, with &s.code;flags&e.code; set to
+&s.code;MODECHECK_INITIAL&e.code;. It is subsequently called for every mode
+in the xorg.conf Display subsection assigned to the screen, with
+&s.code;flags&e.code; set to &s.code;MODECHECK_FINAL&e.code;. In the second
+case, the mode will have successfully passed all other tests. In addition,
+the &s.code;ScrnInfoRec&e.code;'s &s.code;virtualX&e.code;,
+&s.code;virtualY&e.code; and &s.code;displayWidth&e.code; fields will have been
+set as if the mode to be validated were to be the last mode accepted.
+
+<p>
+In effect, calls with MODECHECK_INITIAL are intended for checks that do not
+depend on any mode other than the one being validated, while calls with
+MODECHECK_FINAL are intended for checks that may involve more than one mode.
+
+<sect1>Free screen data
+<p>
+
+ When a screen is deleted prior to the completion of the ScreenInit
+ phase the &s.code;ChipFreeScreen()&e.code; function is called when defined.
+
+ <quote><p>
+ &s.code;void ChipFreeScreen(int scrnindex, int flags)&e.code;
+ <quote><p>
+ Free any driver-allocated data that may have been allocated up to
+ and including an unsuccessful &s.code;ChipScreenInit()&e.code;
+ call. This would predominantly be data allocated by
+ &s.code;ChipPreInit()&e.code; that persists across server
+ generations. It would include the &s.code;driverPrivate&e.code;,
+ and any ``privates'' entries that modules may have allocated.
+
+ </quote>
+ </quote>
+
+
+<sect>Recommended driver functions
+<p>
+
+The functions outlined here are for internal use by the driver only.
+They are entirely optional, and are never accessed directly from higher
+layers. The sample function declarations shown here are just examples.
+The interface (if any) used is up to the driver.
+
+<sect1>Save
+<p>
+
+ Save the video state. This could be called from &s.code;ChipScreenInit()&e.code; and
+ (possibly) &s.code;ChipEnterVT()&e.code;.
+
+ <quote><p>
+ &s.code;void ChipSave(ScrnInfoPtr pScrn)&e.code;
+ <quote><p>
+ Saves the current state. This will only be saving pre-server
+ states or states before returning to the server. There is only
+ one current saved state per screen and it is stored in private
+ storage in the screen.
+
+ </quote>
+ </quote>
+
+<sect1>Restore
+<p>
+
+ Restore the original video state. This could be called from the
+ &s.code;ChipLeaveVT()&e.code; and &s.code;ChipCloseScreen()&e.code;
+ functions.
+
+ <quote><p>
+ &s.code;void ChipRestore(ScrnInfoPtr pScrn)&e.code;
+ <quote><p>
+ Restores the saved state from the private storage. Usually only
+ used for restoring text modes.
+
+ </quote>
+ </quote>
+
+
+<sect1>Initialise Mode
+<p>
+
+ Initialise a video mode. This could be called from the
+ &s.code;ChipScreenInit()&e.code;, &s.code;ChipSwitchMode()&e.code;
+ and &s.code;ChipEnterVT()&e.code; functions.
+
+ <quote><p>
+ &s.code;Bool ChipModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode)&e.code;
+ <quote><p>
+ Programs the hardware for the given video mode.
+
+ </quote>
+ </quote>
+
+
+<sect>Data and Data Structures
+<p>
+
+<sect1>Command line data
+<p>
+
+Command line options are typically global, and are stored in global
+variables. These variables are read-only and are available to drivers
+via a function call interface. Most of these command line values are
+processed via helper functions to ensure that they are treated consistently
+by all drivers. The other means of access is provided for cases where
+the supplied helper functions might not be appropriate.
+
+Some of them are:
+
+<quote><verb>
+ xf86Verbose verbosity level
+ xf86Bpp -bpp from the command line
+ xf86Depth -depth from the command line
+ xf86Weight -weight from the command line
+ xf86Gamma -{r,g,b,}gamma from the command line
+ xf86FlipPixels -flippixels from the command line
+ xf86ProbeOnly -probeonly from the command line
+ defaultColorVisualClass -cc from the command line
+</verb></quote>
+
+If we ever do allow for screen-specific command line options, we may
+need to rethink this.
+
+These can be accessed in a read-only manner by drivers with the following
+functions:
+
+ <quote><p>
+ &s.code;int xf86GetVerbosity()&e.code;
+ <quote><p>
+ Returns the value of &s.code;xf86Verbose&e.code;.
+
+ </quote>
+
+ &s.code;int xf86GetDepth()&e.code;
+ <quote><p>
+ Returns the &s.cmd;-depth&e.cmd; command line setting. If not
+ set on the command line, &s.code;-1&e.code; is returned.
+
+ </quote>
+
+ &s.code;rgb xf86GetWeight()&e.code;
+ <quote><p>
+ Returns the &s.cmd;-weight&e.cmd; command line setting. If not
+ set on the command line, &s.code;{0, 0, 0}&e.code; is returned.
+
+ </quote>
+
+ &s.code;Gamma xf86GetGamma()&e.code;
+ <quote><p>
+ Returns the &s.cmd;-gamma&e.cmd; or &s.cmd;-rgamma&e.cmd;,
+ &s.cmd;-ggamma&e.cmd;, &s.cmd;-bgamma&e.cmd; command line settings.
+ If not set on the command line, &s.code;{0.0, 0.0, 0.0}&e.code;
+ is returned.
+
+ </quote>
+
+ &s.code;Bool xf86GetFlipPixels()&e.code;
+ <quote><p>
+ Returns &s.code;TRUE&e.code; if &s.cmd;-flippixels&e.cmd; is
+ present on the command line, and &s.code;FALSE&e.code; otherwise.
+
+ </quote>
+
+ &s.code;const char *xf86GetServerName()&e.code;
+ <quote><p>
+ Returns the name of the X server from the command line.
+
+ </quote>
+ </quote>
+
+<sect1>Data handling
+<p>
+
+Config file data contains parts that are global, and parts that are
+Screen specific. All of it is parsed into data structures that neither
+the drivers or most other parts of the server need to know about.
+
+The global data is typically not required by drivers, and as such, most
+of it is stored in the private &s.code;xf86InfoRec&e.code;.
+
+The screen-specific data collected from the config file is stored in
+screen, device, display, monitor-specific data structures that are separate
+from the &s.code;ScrnInfoRecs&e.code;, with the appropriate elements/fields
+hooked into the &s.code;ScrnInfoRecs&e.code; as required. The screen
+config data is held in &s.code;confScreenRec&e.code;, device data in
+the &s.code;GDevRec&e.code;, monitor data in the &s.code;MonRec&e.code;,
+and display data in the &s.code;DispRec&e.code;.
+
+The XFree86 common layer's screen specific data (the actual data in use
+for each screen) is held in the &s.code;ScrnInfoRecs&e.code;. As has
+been outlined above, the &s.code;ScrnInfoRecs&e.code; are allocated at probe
+time, and it is the responsibility of the Drivers' &s.code;Probe()&e.code;
+and &s.code;PreInit()&e.code; functions to finish filling them in based
+on both data provided on the command line and data provided from the
+Config file. The precedence for this is:
+
+ <quote>
+ command line -&gt; config file -&gt; probed/default data
+ </quote>
+
+For most things in this category there are helper functions that the
+drivers can use to ensure that the above precedence is consistently
+used.
+
+As well as containing screen-specific data that the XFree86 common layer
+(including essential parts of the server infrastructure as well as helper
+functions) needs to access, it also contains some data that drivers use
+internally. When considering whether to add a new field to the
+&s.code;ScrnInfoRec&e.code;, consider the balance between the convenience
+of things that lots of drivers need and the size/obscurity of the
+&s.code;ScrnInfoRec&e.code;.
+
+Per-screen driver specific data that cannot be accommodated with the
+static &s.code;ScrnInfoRec&e.code; fields is held in a driver-defined
+data structure, a pointer to which is assigned to the
+&s.code;ScrnInfoRec&e.code;'s &s.code;driverPrivate&e.code; field. This
+is per-screen data that persists across server generations (as does the
+bulk of the static &s.code;ScrnInfoRec&e.code; data). It would typically
+also include the video card's saved state.
+
+Per-screen data for other modules that the driver uses (for example,
+the XAA module) that is reset for each server generation is hooked into
+the &s.code;ScrnInfoRec&e.code; through it's &s.code;privates&e.code;
+field.
+
+Once it has stabilised, the data structures and variables accessible to
+video drivers will be documented here. In the meantime, those things
+defined in the &s.code;xf86.h&e.code; and &s.code;xf86str.h&e.code;
+files are visible to video drivers. Things defined in
+&s.code;xf86Priv.h&e.code; and &s.code;xf86Privstr.h&e.code; are NOT
+intended to be visible to video drivers, and it is an error for a driver
+to include those files.
+
+
+<sect1>Accessing global data
+<p>
+
+Some other global state information that the drivers may access via
+functions is as follows:
+
+ <quote><p>
+ &s.code;Bool xf86ServerIsExiting()&e.code;
+ <quote><p>
+ Returns &s.code;TRUE&e.code; if the server is at the end of a
+ generation and is in the process of exiting, and
+ &s.code;FALSE&e.code; otherwise.
+
+ </quote>
+
+ &s.code;Bool xf86ServerIsResetting()&e.code;
+ <quote><p>
+ Returns &s.code;TRUE&e.code; if the server is at the end of a
+ generation and is in the process of resetting, and
+ &s.code;FALSE&e.code; otherwise.
+
+ </quote>
+
+ &s.code;Bool xf86ServerIsInitialising()&e.code;
+ <quote><p>
+ Returns &s.code;TRUE&e.code; if the server is at the beginning of
+ a generation and is in the process of initialising, and
+ &s.code;FALSE&e.code; otherwise.
+
+ </quote>
+
+ &s.code;Bool xf86ServerIsOnlyProbing()&e.code;
+ <quote><p>
+ Returns &s.code;TRUE&e.code; if the -probeonly command line flag
+ was specified, and &s.code;FALSE&e.code; otherwise.
+
+ </quote>
+
+ &s.code;Bool xf86CaughtSignal()&e.code;
+ <quote><p>
+ Returns &s.code;TRUE&e.code; if the server has caught a signal,
+ and &s.code;FALSE&e.code; otherwise.
+
+ </quote>
+ </quote>
+
+<sect1>Allocating private data
+<p>
+
+A driver and any module it uses may allocate per-screen private storage
+in either the &s.code;ScreenRec&e.code; (DIX level) or
+&s.code;ScrnInfoRec&e.code; (XFree86 common layer level).
+&s.code;ScreenRec&e.code; storage persists only for a single server
+generation, and &s.code;ScrnInfoRec&e.code; storage persists across
+generations for the lifetime of the server.
+
+The &s.code;ScreenRec&e.code; &s.code;devPrivates&e.code; data must be
+reallocated/initialised at the start of each new generation. This is
+normally done from the &s.code;ChipScreenInit()&e.code; function, and
+Init functions for other modules that it calls. Data allocated in this
+way should be freed by the driver's &s.code;ChipCloseScreen()&e.code;
+functions, and Close functions for other modules that it calls. A new
+&s.code;devPrivates&e.code; entry is allocated by calling the
+&s.code;AllocateScreenPrivateIndex()&e.code; function.
+
+ <quote><p>
+ &s.code;int AllocateScreenPrivateIndex()&e.code;
+ <quote><p>
+ This function allocates a new element in the
+ &s.code;devPrivates&e.code; field of all currently existing
+ &s.code;ScreenRecs&e.code;. The return value is the index of this
+ new element in the &s.code;devPrivates&e.code; array. The
+ &s.code;devPrivates&e.code; field is of type
+ &s.code;DevUnion&e.code;:
+
+ <verb>
+ typedef union _DevUnion {
+ pointer ptr;
+ long val;
+ unsigned long uval;
+ pointer (*fptr)(void);
+ } DevUnion;
+ </verb>
+
+ which allows the element to be used for any of the above types.
+ It is commonly used as a pointer to data that the caller allocates
+ after the new index has been allocated.
+
+ This function will return &s.code;-1&e.code; when there is an
+ error allocating the new index.
+
+ </quote>
+ </quote>
+
+The &s.code;ScrnInfoRec&e.code; &s.code;privates&e.code; data persists
+for the life of the server, so only needs to be allocated once. This
+should be done from the &s.code;ChipPreInit()&e.code; function, and Init
+functions for other modules that it calls. Data allocated in this way
+should be freed by the driver's &s.code;ChipFreeScreen()&e.code; functions,
+and Free functions for other modules that it calls. A new
+&s.code;privates&e.code; entry is allocated by calling the
+&s.code;xf86AllocateScrnInfoPrivateIndex()&e.code; function.
+
+
+ <quote><p>
+ &s.code;int xf86AllocateScrnInfoPrivateIndex()&e.code;
+ <quote><p>
+ This function allocates a new element in the &s.code;privates&e.code;
+ field of all currently existing &s.code;ScrnInfoRecs&e.code;.
+ The return value is the index of this new element in the
+ &s.code;privates&e.code; array. The &s.code;privates&e.code;
+ field is of type &s.code;DevUnion&e.code;:
+
+ <verb>
+ typedef union _DevUnion {
+ pointer ptr;
+ long val;
+ unsigned long uval;
+ pointer (*fptr)(void);
+ } DevUnion;
+ </verb>
+
+ which allows the element to be used for any of the above types.
+ It is commonly used as a pointer to data that the caller allocates
+ after the new index has been allocated.
+
+ This function will not return when there is an error allocating
+ the new index. When there is an error it will cause the server
+ to exit with a fatal error. The similar function for allocation
+ privates in the &s.code;ScreenRec&e.code;
+ (&s.code;AllocateScreenPrivateIndex()&e.code;) differs in this
+ respect by returning &s.code;-1&e.code; when the allocation fails.
+
+ </quote>
+ </quote>
+
+<sect>Keeping Track of Bus Resources<label id="rac">
+<p>
+
+<sect1>Theory of Operation
+<p>
+
+The XFree86 common layer has knowledge of generic access control mechanisms
+for devices on certain bus systems (currently the PCI bus) as well as
+of methods to enable or disable access to the buses itself. Furthermore
+it can access information on resources decoded by these devices and if
+necessary modify it.
+
+When first starting the Xserver collects all this information, saves it
+for restoration, checks it for consistency, and if necessary, corrects
+it. Finally it disables all resources on a generic level prior to
+calling any driver function.
+
+When the &s.code;Probe()&e.code; function of each driver is called the
+device sections are matched against the devices found in the system.
+The driver may probe devices at this stage that cannot be identified by
+using device independent methods. Access to all resources that can be
+controlled in a device independent way is disabled. The
+&s.code;Probe()&e.code; function should register all non-relocatable
+resources at this stage. If a resource conflict is found between
+exclusive resources the driver will fail immediately. Optionally the
+driver might specify an &s.code;EntityInit()&e.code;,
+&s.code;EntityLeave()&e.code; and &s.code;EntityEnter()&e.code; function.
+
+&s.code;EntityInit()&e.code; can be used to disable any shared resources
+that are not controlled by the generic access control functions. It is
+called prior to the PreInit phase regardless if an entity is active or
+not. When calling the &s.code;EntityInit()&e.code;,
+&s.code;EntityEnter()&e.code; and &s.code;EntityLeave()&e.code; functions
+the common level will disable access to all other entities on a generic
+level. Since the common level has no knowledge of device specific
+methods to disable access to resources it cannot be guaranteed that
+certain resources are not decoded by any other entity until the
+&s.code;EntityInit()&e.code; or &s.code;EntityEnter()&e.code; phase is
+finished. Device drivers should therefore register all those resources
+which they are going to disable. If these resources are never to be
+used by any driver function they may be flagged &s.code;ResInit&e.code;
+so that they can be removed from the resource list after processing all
+&s.code;EntityInit()&e.code; functions. &s.code;EntityEnter()&e.code;
+should disable decoding of all resources which are not registered as
+exclusive and which are not handled by the generic access control in
+the common level. The difference to &s.code;EntityInit()&e.code; is
+that the latter one is only called once during lifetime of the server.
+It can therefore be used to set up variables prior to disabling resources.
+&s.code;EntityLeave()&e.code; should restore the original state when
+exiting the server or switching to a different VT. It also needs to
+disable device specific access functions if they need to be disabled on
+server exit or VT switch. The default state is to enable them before
+giving up the VT.
+
+In &s.code;PreInit()&e.code; phase each driver should check if any
+sharable resources it has registered during &s.code;Probe()&e.code; has
+been denied and take appropriate action which could simply be to fail.
+If it needs to access resources it has disabled during
+&s.code;EntitySetup()&e.code; it can do so provided it has registered
+these and will disable them before returning from
+&s.code;PreInit()&e.code;. This also applies to all other driver
+functions. Several functions are provided to request resource ranges,
+register these, correct PCI config space and add replacements for the
+generic access functions. Resources may be marked ``disabled'' or
+``unused'' during OPERATING stage. Although these steps could also be
+performed in &s.code;ScreenInit()&e.code;, this is not desirable.
+
+Following &s.code;PreInit()&e.code; phase the common level determines
+if resource access control is needed. This is the case if more than
+one screen is used. If necessary the RAC wrapper module is loaded. In
+&s.code;ScreenInit()&e.code; the drivers can decide which operations
+need to be placed under RAC. Available are the frame buffer operations,
+the pointer operations and the colormap operations. Any operation that
+requires resources which might be disabled during OPERATING state should
+be set to use RAC. This can be specified separately for memory and IO
+resources.
+
+When &s.code;ScreenInit()&e.code; phase is done the common level will
+determine which shared resources are requested by more than one driver
+and set the access functions accordingly. This is done following these
+rules:
+
+<enum>
+<item>The sharable resources registered by each entity are compared. If
+ a resource is registered by more than one entity the entity will be
+ marked to need to share this resources type (&s.code;IO&e.code; or
+ &s.code;MEM&e.code;).
+
+<item>A resource marked ``disabled'' during OPERATING state will be ignored
+ entirely.
+
+<item>A resource marked ``unused'' will only conflicts with an overlapping
+ resource of an other entity if the second is actually in use during
+ OPERATING state.
+
+<item>If an ``unused'' resource was found to conflict however the entity
+ does not use any other resource of this type the entire resource type
+ will be disabled for that entity.
+</enum>
+
+The driver has the choice among different ways to control access to
+certain resources:
+
+<enum>
+<item>It can rely on the generic access functions. This is probably the
+ most common case. Here the driver only needs to register any resource
+ it is going to use.
+
+<item>It can replace the generic access functions by driver specific
+ ones. This will mostly be used in cases where no generic access
+ functions are available. In this case the driver has to make sure
+ these resources are disabled when entering the &s.code;PreInit()&e.code;
+ stage. Since the replacement functions are registered in
+ &s.code;PreInit()&e.code; the driver will have to enable these
+ resources itself if it needs to access them during this state. The
+ driver can specify if the replacement functions can control memory
+ and/or I/O resources separately.
+
+<item>The driver can enable resources itself when it needs them. Each
+ driver function enabling them needs to disable them before it will
+ return. This should be used if a resource which can be controlled
+ in a device dependent way is only required during SETUP state. This
+ way it can be marked ``unused'' during OPERATING state.
+</enum>
+
+A resource which is decoded during OPERATING state however never accessed
+by the driver should be marked unused.
+
+Since access switching latencies are an issue during Xserver operation,
+the common level attempts to minimize the number of entities that need
+to be placed under RAC control. When a wrapped operation is called,
+the &s.code;EnableAccess()&e.code; function is called before control is
+passed on. &s.code;EnableAccess()&e.code; checks if a screen is under
+access control. If not it just establishes bus routing and returns.
+If the screen needs to be under access control,
+&s.code;EnableAccess()&e.code; determines which resource types
+(&s.code;MEM&e.code;, &s.code;IO&e.code;) are required. Then it tests
+if this access is already established. If so it simply returns. If
+not it disables the currently established access, fixes bus routing and
+enables access to all entities registered for this screen.
+
+Whenever a mode switch or a VT-switch is performed the common level will
+return to SETUP state.
+
+<sect1>Resource Types
+<p>
+
+Resource have certain properties. When registering resources each range
+is accompanied by a flag consisting of the ORed flags of the different
+properties the resource has. Each resource range may be classified
+according to
+
+<itemize>
+ <item>its physical properties i.e., if it addresses
+ memory (&s.code;ResMem&e.code;) or
+ I/O space (&s.code;ResIo&e.code;),
+ <item>if it addresses a
+ block (&s.code;ResBlock&e.code;) or
+ sparse (&s.code;ResSparse&e.code;)
+ range,
+ <item>its access properties.
+</itemize>
+
+There are two known access properties:
+
+<itemize>
+ <item>&s.code;ResExclusive&e.code;
+ for resources which may not be shared with any other device and
+ <item>&s.code;ResShared&e.code;
+ for resources which can be disabled and therefore can be shared.
+</itemize>
+
+If it is necessary to test a resource against any type a generic access
+type &s.code;ResAny&e.code; is provided. If this is set the resource
+will conflict with any resource of a different entity intersecting its
+range. Further it can be specified that a resource is decoded however
+never used during any stage (&s.code;ResUnused&e.code;) or during
+OPERATING state (&s.code;ResUnusedOpr&e.code;). A resource only visible
+during the init functions (ie. &s.code;EntityInit()&e.code;,
+&s.code;EntityEnter()&e.code; and &s.code;EntityLeave()&e.code; should
+be registered with the flag &s.code;ResInit&e.code;. A resource that
+might conflict with background resource ranges may be flagged with
+&s.code;ResBios&e.code;. This might be useful when registering resources
+ranges that were assigned by the system Bios.
+
+Several predefined resource lists are available for VGA and 8514/A
+resources in &s.code;common/xf86Resources.h&e.code;.
+
+<sect1>Available Functions<label id="avail">
+<p>
+
+The functions provided for resource management are listed in their order
+of use in the driver.
+
+
+<sect2>Probe Phase
+<p>
+
+In this phase each driver detects those resources it is able to drive,
+creates an entity record for each of them, registers non-relocatable
+resources and allocates screens and adds the resources to screens.
+
+Two helper functions are provided for matching device sections in the
+xorg.conf file to the devices:
+
+ <quote><p>
+ &s.code;int xf86MatchPciInstances(const char *driverName, int vendorID,
+ &f.indent;SymTabPtr chipsets, PciChipsets *PCIchipsets,
+ &f.indent;GDevPtr *devList, int numDevs, DriverPtr drvp,
+ &f.indent;int **foundEntities)&e.code;
+ <quote><p>
+ This function finds matches between PCI cards that a driver supports
+ and config file device sections. It is intended for use in the
+ &s.code;ChipProbe()&e.code; function of drivers for PCI cards.
+ Only probed PCI devices with a vendor ID matching
+ &s.code;vendorID&e.code; are considered. &s.code;devList&e.code;
+ and &s.code;numDevs&e.code; are typically those found from
+ calling &s.code;xf86MatchDevice()&e.code;, and represent the active
+ config file device sections relevant to the driver.
+ &s.code;PCIchipsets&e.code; is a table that provides a mapping
+ between the PCI device IDs, the driver's internal chipset tokens
+ and a list of fixed resources.
+
+ When a device section doesn't have a &s.key;BusID&e.key; entry it
+ can only match the primary video device. Secondary devices are
+ only matched with device sections that have a matching
+ &s.key;BusID&e.key; entry.
+
+ Once the preliminary matches have been found, a final match is
+ confirmed by checking if the chipset override, ChipID override or
+ probed PCI chipset type match one of those given in the
+ &s.code;chipsets&e.code; and &s.code;PCIchipsets&e.code; lists.
+ The &s.code;PCIchipsets&e.code; list includes a list of the PCI
+ device IDs supported by the driver. The list should be terminated
+ with an entry with PCI ID &s.code;-1&e.code;". The
+ &s.code;chipsets&e.code; list is a table mapping the driver's
+ internal chipset tokens to names, and should be terminated with
+ a &s.code;NULL&e.code; entry. Only those entries with a
+ corresponding entry in the &s.code;PCIchipsets&e.code; list are
+ considered. The order of precedence is: config file chipset,
+ config file ChipID, probed PCI device ID.
+
+ In cases where a driver handles PCI chipsets with more than one
+ vendor ID, it may set &s.code;vendorID&e.code; to
+ &s.code;0&e.code;, and OR each devID in the list with (the
+ vendor&nbsp;ID&nbsp;&lt;&lt;&nbsp;16).
+
+ Entity index numbers for confirmed matches are returned as an
+ array via &s.code;foundEntities&e.code;. The PCI information,
+ chipset token and device section for each match are found in the
+ &s.code;EntityInfoRec&e.code; referenced by the indices.
+
+ The function return value is the number of confirmed matches. A
+ return value of &s.code;-1&e.code; indicates an internal error.
+ The returned &s.code;foundEntities&e.code; array should be freed
+ by the driver with &s.code;xfree()&e.code; when it is no longer
+ needed in cases where the return value is greater than zero.
+
+ </quote>
+
+ &s.code;int xf86MatchIsaInstances(const char *driverName,
+ &f.indent;SymTabPtr chipsets, IsaChipsets *ISAchipsets,
+ &f.indent;DriverPtr drvp, FindIsaDevProc FindIsaDevice,
+ &f.indent;GDevPtr *devList, int numDevs,
+ int **foundEntities)&e.code;
+ <quote><p>
+ This function finds matches between ISA cards that a driver supports
+ and config file device sections. It is intended for use in the
+ &s.code;ChipProbe()&e.code; function of drivers for ISA cards.
+ &s.code;devList&e.code; and &s.code;numDevs&e.code; are
+ typically those found from calling &s.code;xf86MatchDevice()&e.code;,
+ and represent the active config file device sections relevant to
+ the driver. &s.code;ISAchipsets&e.code; is a table that provides
+ a mapping between the driver's internal chipset tokens and the
+ resource classes. &s.code;FindIsaDevice&e.code; is a
+ driver-provided function that probes the hardware and returns the
+ chipset token corresponding to what was detected, and
+ &s.code;-1&e.code; if nothing was detected.
+
+ If the config file device section contains a chipset entry, then
+ it is checked against the &s.code;chipsets&e.code; list. When
+ no chipset entry is present, the &s.code;FindIsaDevice&e.code;
+ function is called instead.
+
+ Entity index numbers for confirmed matches are returned as an
+ array via &s.code;foundEntities&e.code;. The chipset token and
+ device section for each match are found in the
+ &s.code;EntityInfoRec&e.code; referenced by the indices.
+
+ The function return value is the number of confirmed matches. A
+ return value of &s.code;-1&e.code; indicates an internal error.
+ The returned &s.code;foundEntities&e.code; array should be freed
+ by the driver with &s.code;xfree()&e.code; when it is no longer
+ needed in cases where the return value is greater than zero.
+
+ </quote>
+ </quote>
+
+These two helper functions make use of several core functions that are
+available at the driver level:
+
+ <quote><p>
+ &s.code;Bool xf86ParsePciBusString(const char *busID, int *bus,
+ &f.indent;int *device, int *func)&e.code;
+ <quote><p>
+ Takes a &s.code;BusID&e.code; string, and if it is in the correct
+ format, returns the PCI &s.code;bus&e.code;, &s.code;device&e.code;,
+ &s.code;func&e.code; values that it indicates. The format of the
+ string is expected to be "PCI:bus:device:func" where each of `bus',
+ `device' and `func' are decimal integers. The ":func" part may
+ be omitted, and the func value assumed to be zero, but this isn't
+ encouraged. The "PCI" prefix may also be omitted. The prefix
+ "AGP" is currently equivalent to the "PCI" prefix. If the string
+ isn't a valid PCI BusID, the return value is &s.code;FALSE&e.code;.
+
+ </quote>
+
+
+ &s.code;Bool xf86ComparePciBusString(const char *busID, int bus,
+ &f.indent;int device, int func)&e.code;
+ <quote><p>
+ Compares a &s.code;BusID&e.code; string with PCI &s.code;bus&e.code;,
+ &s.code;device&e.code;, &s.code;func&e.code; values. If they
+ match &s.code;TRUE&e.code; is returned, and &s.code;FALSE&e.code;
+ if they don't.
+
+ </quote>
+
+ &s.code;Bool xf86ParseIsaBusString(const char *busID)&e.code;
+ <quote><p>
+ Compares a &s.code;BusID&e.code; string with the ISA bus ID string
+ ("ISA" or "ISA:"). If they match &s.code;TRUE&e.code; is returned,
+ and &s.code;FALSE&e.code; if they don't.
+
+ </quote>
+
+ &s.code;Bool xf86CheckPciSlot(int bus, int device, int func)&e.code;
+ <quote><p>
+ Checks if the PCI slot &s.code;bus:device:func&e.code; has been
+ claimed. If so, it returns &s.code;FALSE&e.code;, and otherwise
+ &s.code;TRUE&e.code;.
+
+ </quote>
+
+ &s.code;int xf86ClaimPciSlot(int bus, int device, int func, DriverPtr drvp,
+ &f.indent;int chipset, GDevPtr dev, Bool active)&e.code;
+ <quote><p>
+ This function is used to claim a PCI slot, allocate the associated
+ entity record and initialise their data structures. The return
+ value is the index of the newly allocated entity record, or
+ &s.code;-1&e.code; if the claim fails. This function should always
+ succeed if &s.code;xf86CheckPciSlot()&e.code; returned
+ &s.code;TRUE&e.code; for the same PCI slot.
+
+ </quote>
+
+ &s.code;Bool xf86IsPrimaryPci(void)&e.code;
+ <quote><p>
+ This function returns &s.code;TRUE&e.code; if the primary card is
+ a PCI device, and &s.code;FALSE&e.code; otherwise.
+
+ </quote>
+
+ &s.code;int xf86ClaimIsaSlot(DriverPtr drvp, int chipset,
+ &f.indent;GDevPtr dev, Bool active)&e.code;
+ <quote><p>
+ This allocates an entity record entity and initialise the data
+ structures. The return value is the index of the newly allocated
+ entity record.
+
+ </quote>
+
+ &s.code;Bool xf86IsPrimaryIsa(void)&e.code;
+ <quote><p>
+ This function returns &s.code;TRUE&e.code; if the primary card is
+ an ISA (non-PCI) device, and &s.code;FALSE&e.code; otherwise.
+
+ </quote>
+ </quote>
+
+Two helper functions are provided to aid configuring entities:
+ <quote><p>
+ &s.code;ScrnInfoPtr xf86ConfigPciEntity(ScrnInfoPtr pScrn,
+ &f.indent;int scrnFlag, int entityIndex,
+ &f.indent;PciChipsets *p_chip,
+ &f.indent;resList res, EntityProc init,
+ &f.indent;EntityProc enter, EntityProc leave,
+ &f.indent;pointer private)&e.code;
+ <p>
+ &s.code;ScrnInfoPtr xf86ConfigIsaEntity(ScrnInfoPtr pScrn,
+ &f.indent;int scrnFlag, int entityIndex,
+ &f.indent;IsaChipsets *i_chip,
+ &f.indent;resList res, EntityProc init,
+ &f.indent;EntityProc enter, EntityProc leave,
+ &f.indent;pointer private)&e.code;
+ <quote><p>
+ These functions are used to register the non-relocatable resources
+ for an entity, and the optional entity-specific &s.code;Init&e.code;, &s.code;Enter&e.code; and
+ &s.code;Leave&e.code; functions. Usually the list of fixed resources is obtained
+ from the Isa/PciChipsets lists. However an additional list of
+ resources may be passed. Generally this is not required.
+ For active entities a &s.code;ScrnInfoRec&e.code; is allocated
+ if the &s.code;pScrn&e.code; argument is &s.code;NULL&e.code;.
+The
+ return value is &s.code;TRUE&e.code; when successful. The init, enter, leave
+ functions are defined as follows:
+
+ <quote>
+ &s.code;typedef void (*EntityProc)(int entityIndex,
+ &f.indent;pointer private)&e.code;
+ </quote>
+
+ They are passed the entity index and a pointer to a private scratch
+ area. This can be set up during &s.code;Probe()&e.code; and
+ its address can be passed to
+ &s.code;xf86ConfigIsaEntity()&e.code; and
+ &s.code;xf86ConfigPciEntity()&e.code; as the last argument.
+
+ </quote>
+ </quote>
+
+These two helper functions make use of several core functions that are
+available at the driver level:
+ <quote><p>
+ &s.code;void xf86ClaimFixedResources(resList list, int entityIndex)&e.code;
+ <quote><p>
+ This function registers the non-relocatable resources which cannot
+ be disabled and which therefore would cause the server to fail
+ immediately if they were found to conflict. It also records
+ non-relocatable but sharable resources for processing after the
+ &s.code;Probe()&e.code; phase.
+
+ </quote>
+
+ &s.code;Bool xf86SetEntityFuncs(int entityIndex, EntityProc init,
+ &f.indent;EntityProc enter, EntityProc leave, pointer)&e.code;
+ <quote><p>
+ This function registers with an entity the &s.code;init&e.code;,
+ &s.code;enter&e.code;, &s.code;leave&e.code; functions along
+ with the pointer to their private area.
+
+ </quote>
+
+ &s.code;void xf86AddEntityToScreen(ScrnInfoPtr pScrn, int entityIndex)&e.code;
+ <quote><p>
+ This function associates the entity referenced by
+ &s.code;entityIndex&e.code; with the screen.
+
+ </quote>
+ </quote>
+
+<sect2>PreInit Phase
+<p>
+
+During this phase the remaining resources should be registered.
+&s.code;PreInit()&e.code; should call &s.code;xf86GetEntityInfo()&e.code;
+to obtain a pointer to an &s.code;EntityInfoRec&e.code; for each entity
+it is able to drive and check if any resource are listed in its
+&s.code;resources&e.code; field. If resources registered in the Probe
+phase have been rejected in the post-Probe phase
+(&s.code;resources&e.code; is non-&s.code;NULL&e.code;), then the driver should
+decide if it can continue without using these or if it should fail.
+
+ <quote><p>
+ &s.code;EntityInfoPtr xf86GetEntityInfo(int entityIndex)&e.code;
+ <quote><p>
+ This function returns a pointer to the &s.code;EntityInfoRec&e.code;
+ referenced by &s.code;entityIndex&e.code;. The returned
+ &s.code;EntityInfoRec&e.code; should be freed with
+ &s.code;xfree()&e.code; when no longer needed.
+
+ </quote>
+ </quote>
+Several functions are provided to simplify resource registration:
+ <quote><p>
+ &s.code;Bool xf86IsEntityPrimary(int entityIndex)&e.code;
+ <quote><p>
+ This function returns &s.code;TRUE&e.code; if the entity referenced
+ by &s.code;entityIndex&e.code; is the primary display device (i.e.,
+ the one initialised at boot time and used in text mode).
+
+ </quote>
+
+ &s.code;Bool xf86IsScreenPrimary(int scrnIndex)&e.code;
+ <quote><p>
+ This function returns &s.code;TRUE&e.code; if the primary entity
+ is registered with the screen referenced by
+ &s.code;scrnIndex&e.code;.
+
+ </quote>
+
+ &s.code;pciVideoPtr xf86GetPciInfoForEntity(int entityIndex)&e.code;
+ <quote><p>
+ This function returns a pointer to the &s.code;pciVideoRec&e.code;
+ for the specified entity. If the entity is not a PCI device,
+ &s.code;NULL&e.code; is returned.
+
+ </quote>
+ </quote>
+
+The primary function for registration of resources is:
+ <quote><p>
+ &s.code;resPtr xf86RegisterResources(int entityIndex, resList list,
+ &f.indent;int access)&e.code;
+ <quote><p>
+ This function tries to register the resources in
+ &s.code;list&e.code;. If list is &s.code;NULL&e.code; it tries
+ to determine the resources automatically. This only works for
+ entities that provide a generic way to read out the resource ranges
+ they decode. So far this is only the case for PCI devices. By
+ default the PCI resources are registered as shared
+ (&s.code;ResShared&e.code;) if the driver wants to set a different
+ access type it can do so by specifying the access flags in the
+ third argument. A value of &s.code;0&e.code; means to use the
+ default settings. If for any reason the resource broker is not
+ able to register some of the requested resources the function will
+ return a pointer to a list of the failed ones. In this case the
+ driver may be able to move the resource to different locations.
+ In case of PCI bus entities this is done by passing the list of
+ failed resources to &s.code;xf86ReallocatePciResources()&e.code;.
+ When the registration succeeds, the return value is
+ &s.code;NULL&e.code;.
+
+ </quote>
+
+ &s.code;resPtr xf86ReallocatePciResources(int entityIndex, resPtr pRes)&e.code;
+ <quote><p>
+ This function takes a list of PCI resources that need to be
+ reallocated and returns &s.code;NULL&e.code when all relocations are
+ successful.
+ &s.code;xf86RegisterResources()&e.code; should be called again to
+ register the relocated resources with the broker.
+ If the reallocation fails, a list of the resources that could not be
+ relocated is returned.
+
+ </quote>
+ </quote>
+
+Two functions are provided to obtain a resource range of a given type:
+ <quote><p>
+ &s.code;resRange xf86GetBlock(long type, memType size,
+ &f.indent;memType window_start, memType window_end,
+ &f.indent;memType align_mask, resPtr avoid)&e.code;
+ <quote><p>
+ This function tries to find a block range of size
+ &s.code;size&e.code; and type &s.code;type&e.code; in a window
+ bound by &s.code;window_start&e.code; and &s.code;window_end&e.code;
+ with the alignment specified in &s.code;align_mask&e.code;.
+ Optionally a list of resource ranges which should be avoided within
+ the window can be supplied. On failure a zero-length range of
+ type &s.code;ResEnd&e.code; will be returned.
+
+ </quote>
+ &s.code;resRange xf86GetSparse(long type, memType fixed_bits,
+ &f.indent;memType decode_mask, memType address_mask,
+ &f.indent;resPtr avoid)&e.code;
+ <quote><p>
+ This function is like the previous one, but attempts to find a
+ sparse range instead of a block range. Here three values have to
+ be specified: the &s.code;address_mask&e.code; which marks all
+ bits of the mask part of the address, the &s.code;decode_mask&e.code;
+ which masks out the bits which are hardcoded and are therefore
+ not available for relocation and the values of the fixed bits.
+ The function tries to find a base that satisfies the given condition.
+ If the function fails it will return a zero range of type
+ &s.code;ResEnd&e.code;. Optionally it might be passed a list of
+ resource ranges to avoid.
+
+ </quote>
+ </quote>
+
+Some PCI devices are broken in the sense that they return invalid size
+information for a certain resource. In this case the driver can supply
+the correct size and make sure that the resource range allocated for
+the card is large enough to hold the address range decoded by the card.
+The function &s.code;xf86FixPciResource()&e.code; can be used to do this:
+ <quote><p>
+ &s.code;Bool xf86FixPciResource(int entityIndex, unsigned int prt,
+ &f.indent;CARD32 alignment, long type)&e.code;
+ <quote><p>
+ This function fixes a PCI resource allocation. The
+ &s.code;prt&e.code; parameter contains the number of the PCI base
+ register that needs to be fixed (&s.code;0-5&e.code;, and
+ &s.code;6&e.code; for the BIOS base register). The size is
+ specified by the alignment. Since PCI resources need to span an
+ integral range of size &s.code;2^n&e.code;, the alignment also
+ specifies the number of addresses that will be decoded. If the
+ driver specifies a type mask it can override the default type for
+ PCI resources which is &s.code;ResShared&e.code;. The resource
+ broker needs to know that to find a matching resource range. This
+ function should be called before calling
+ &s.code;xf86RegisterResources()&e.code;. The return value is
+ &s.code;TRUE&e.code; when the function succeeds.
+
+ </quote>
+
+ &s.code;Bool xf86CheckPciMemBase(pciVideoPtr pPci, memType base)&e.code;
+ <quote><p>
+ This function checks that the memory base address specified matches
+ one of the PCI base address register values for the given PCI
+ device. This is mostly used to check that an externally provided
+ base address (e.g., from a config file) matches an actual value
+ allocated to a device.
+
+ </quote>
+ </quote>
+
+The driver may replace the generic access control functions for an entity.
+This is done with the &s.code;xf86SetAccessFuncs()&e.code;:
+ <quote><p>
+ &s.code;void xf86SetAccessFuncs(EntityInfoPtr pEnt,
+ &f.indent;xf86SetAccessFuncPtr funcs,
+ &f.indent;xf86SetAccessFuncPtr oldFuncs)&e.code;
+ <quote><p>
+ with:
+ </quote>
+
+ <verb>
+ typedef struct {
+ xf86AccessPtr mem;
+ xf86AccessPtr io;
+ xf86AccessPtr io_mem;
+ } xf86SetAccessFuncRec, *xf86SetAccessFuncPtr;
+ </verb>
+
+ <quote><p>
+ The driver can pass three functions: one for I/O access, one for
+ memory access and one for combined memory and I/O access. If the
+ memory access and combined access functions are identical the
+ common level assumes that the memory access cannot be controlled
+ independently of I/O access, if the I/O access function and the
+ combined access functions are the same it is assumed that I/O can
+ not be controlled independently. If memory and I/O have to be
+ controlled together all three values should be the same. If a
+ non &s.code;NULL&e.code; value is passed as third argument it is
+ interpreted as an address where to store the old access record.
+ If the third argument is &s.code;NULL&e.code; it will be assumed
+ that the generic access should be enabled before replacing the
+ access functions. Otherwise it will be disabled. The driver may
+ enable them itself using the returned values. It should do this
+ from its replacement access functions as the generic access may
+ be disabled by the common level on certain occasions. If replacement
+ functions are specified they must control all resources of the
+ specific type registered for the entity.
+
+ </quote>
+ </quote>
+
+To find out if a specific resource range conflicts with another
+resource the &s.code;xf86ChkConflict()&e.code; function may be used:
+ <quote><p>
+ &s.code;memType xf86ChkConflict(resRange *rgp, int entityIndex)&e.code;
+ <quote><p>
+ This function checks if the resource range &s.code;rgp&e.code; of
+ for the specified entity conflicts with with another resource.
+ If a conflict is found, the address of the start of the conflict
+ is returned. The return value is zero when there is no conflict.
+
+ </quote>
+ </quote>
+
+The OPERATING state properties of previously registered fixed resources
+can be set with the &s.code;xf86SetOperatingState()&e.code; function:
+ <quote><p>
+ &s.code;resPtr xf86SetOperatingState(resList list, int entityIndex,
+ &f.indent;int mask)&e.code;
+ <quote><p>
+ This function is used to set the status of a resource during
+ OPERATING state. &s.code;list&e.code; holds a list to which
+ &s.code;mask&e.code; is to be applied. The parameter
+ &s.code;mask&e.code; may have the value &s.code;ResUnusedOpr&e.code;
+ and &s.code;ResDisableOpr&e.code;. The first one should be used
+ if a resource isn't used by the driver during OPERATING state
+ although it is decoded by the device, while the latter one indicates
+ that the resource is not decoded during OPERATING state. Note
+ that the resource ranges have to match those specified during
+ registration. If a range has been specified starting at
+ &s.code;A&e.code; and ending at &s.code;B&e.code; and suppose
+ &s.code;C&e.code; us a value satisfying
+ &s.code;A&nbsp;&lt;&nbsp;C&nbsp;&lt;&nbsp;B&e.code; one may not
+ specify the resource range &s.code;(A,B)&e.code; by splitting it
+ into two ranges &s.code;(A,C)&e.code; and &s.code;(C,B)&e.code;.
+
+ </quote>
+ </quote>
+
+The following two functions are provided for special cases:
+ <quote><p>
+ &s.code;void xf86RemoveEntityFromScreen(ScrnInfoPtr pScrn, int entityIndex)&e.code;
+ <quote><p>
+ This function may be used to remove an entity from a screen. This
+ only makes sense if a screen has more than one entity assigned or
+ the screen is to be deleted. No test is made if the screen has
+ any entities left.
+
+ </quote>
+
+ &s.code;void xf86DeallocateResourcesForEntity(int entityIndex, long type)&e.code;
+ <quote><p>
+ This function deallocates all resources of a given type registered
+ for a certain entity from the resource broker list.
+
+ </quote>
+ </quote>
+
+<sect2>ScreenInit Phase
+<p>
+
+All that is required in this phase is to setup the RAC flags. Note that
+it is also permissible to set these flags up in the PreInit phase. The
+RAC flags are held in the &s.code;racIoFlags&e.code; and &s.code;racMemFlags&e.code; fields of the
+&s.code;ScrnInfoRec&e.code; for each screen. They specify which graphics operations
+might require the use of shared resources. This can be specified
+separately for memory and I/O resources. The available flags are defined
+in &s.code;rac/xf86RAC.h&e.code;. They are:
+
+ &s.code;RAC_FB&e.code;
+ <quote>
+ for framebuffer operations (including hw acceleration)
+ </quote>
+ &s.code;RAC_CURSOR&e.code;
+ <quote>
+ for Cursor operations
+ (??? I'm not sure if we need this for SW cursor it depends
+ on which level the sw cursor is drawn)
+ </quote>
+ &s.code;RAC_COLORMAP&e.code;
+ <quote>
+ for colormap operations
+ </quote>
+ &s.code;RAC_VIEWPORT&e.code;
+ <quote>
+ for the call to &s.code;ChipAdjustFrame()&e.code; </quote>
+
+
+The flags are ORed together.
+
+<sect>Config file ``Option'' entries<label id="options">
+<p>
+
+Option entries are permitted in most sections and subsections of the
+config file. There are two forms of option entries:
+
+<descrip>
+<tag>Option "option-name"</tag>
+ A boolean option.
+<tag>Option "option-name" "option-value"</tag>
+ An option with an arbitrary value.
+</descrip>
+
+The option entries are handled by the parser, and a list of the parsed
+options is included with each of the appropriate data structures that
+the drivers have access to. The data structures used to hold the option
+information are opaque to the driver, and a driver must not access the
+option data directly. Instead, the common layer provides a set of
+functions that may be used to access, check and manipulate the option
+data.
+
+First, the low level option handling functions. In most cases drivers
+would not need to use these directly.
+
+ <quote><p>
+ &s.code;pointer xf86FindOption(pointer options, const char *name)&e.code;
+ <quote><p>
+ Takes a list of options and an option name, and returns a handle
+ for the first option entry in the list matching the name. Returns
+ &s.code;NULL&e.code; if no match is found.
+
+ </quote>
+
+ &s.code;char *xf86FindOptionValue(pointer options, const char *name)&e.code;
+ <quote><p>
+ Takes a list of options and an option name, and returns the value
+ associated with the first option entry in the list matching the
+ name. If the matching option has no value, an empty string
+ (&s.code;""&e.code;) is returned. Returns &s.code;NULL&e.code;
+ if no match is found.
+
+ </quote>
+
+ &s.code;void xf86MarkOptionUsed(pointer option)&e.code;
+ <quote><p>
+ Takes a handle for an option, and marks that option as used.
+
+ </quote>
+
+ &s.code;void xf86MarkOptionUsedByName(pointer options, const char *name)&e.code;
+ <quote><p>
+ Takes a list of options and an option name and marks the first
+ option entry in the list matching the name as used.
+
+ </quote>
+ </quote>
+
+
+Next, the higher level functions that most drivers would use.
+ <quote><p>
+ &s.code;void xf86CollectOptions(ScrnInfoPtr pScrn, pointer extraOpts)&e.code;
+ <quote><p>
+ Collect the options from each of the config file sections used by
+ the screen (&s.code;pScrn&e.code;) and return the merged list as
+ &s.code;pScrn-&gt;options&e.code;. This function requires that
+ &s.code;pScrn-&gt;confScreen&e.code;, &s.code;pScrn-&gt;display&e.code;,
+ &s.code;pScrn-&gt;monitor&e.code;,
+ &s.code;pScrn-&gt;numEntities&e.code;, and
+ &s.code;pScrn-&gt;entityList&e.code; are initialised.
+ &s.code;extraOpts&e.code; may optionally be set to an additional
+ list of options to be combined with the others. The order of
+ precedence for options is &s.code;extraOpts&e.code;, display,
+ confScreen, monitor, device.
+
+ </quote>
+
+ &s.code;void xf86ProcessOptions(int scrnIndex, pointer options,
+ &f.indent;OptionInfoPtr optinfo)&e.code;
+ <quote><p>
+ Processes a list of options according to the information in the
+ array of &s.code;OptionInfoRecs&e.code; (&s.code;optinfo&e.code;).
+ The resulting information is stored in the &s.code;value&e.code;
+ fields of the appropriate &s.code;optinfo&e.code; entries. The
+ &s.code;found&e.code; fields are set to &s.code;TRUE&e.code;
+ when an option with a value of the correct type if found, and
+ &s.code;FALSE&e.code; otherwise. The &s.code;type&e.code; field
+ is used to determine the expected value type for each option.
+ Each option in the list of options for which there is a name match
+ (but not necessarily a value type match) is marked as used.
+ Warning messages are printed when option values don't match the
+ types specified in the optinfo data.
+
+ NOTE: If this function is called before a driver's screen number
+ is known (e.g., from the &s.code;ChipProbe()&e.code; function) a
+ &s.code;scrnIndex&e.code; value of &s.code;-1&e.code; should be
+ used.
+
+ NOTE 2: Given that this function stores into the
+ &s.code;OptionInfoRecs&e.code; pointed to by &s.code;optinfo&e.code,
+ the caller should ensure the &s.code;OptionInfoRecs&e.code; are
+ (re-)initialised before the call, especially if the caller expects
+ to use the predefined option values as defaults.
+
+ The &s.code;OptionInfoRec&e.code; is defined as follows:
+
+ <verb>
+ typedef struct {
+ double freq;
+ int units;
+ } OptFrequency;
+
+ typedef union {
+ unsigned long num;
+ char * str;
+ double realnum;
+ Bool bool;
+ OptFrequency freq;
+ } ValueUnion;
+
+ typedef enum {
+ OPTV_NONE = 0,
+ OPTV_INTEGER,
+ OPTV_STRING, /* a non-empty string */
+ OPTV_ANYSTR, /* Any string, including an empty one */
+ OPTV_REAL,
+ OPTV_BOOLEAN,
+ OPTV_FREQ
+ } OptionValueType;
+
+ typedef enum {
+ OPTUNITS_HZ = 1,
+ OPTUNITS_KHZ,
+ OPTUNITS_MHZ
+ } OptFreqUnits;
+
+ typedef struct {
+ int token;
+ const char* name;
+ OptionValueType type;
+ ValueUnion value;
+ Bool found;
+ } OptionInfoRec, *OptionInfoPtr;
+ </verb>
+
+ &s.code;OPTV_FREQ&e.code; can be used for options values that are
+ frequencies. These values are a floating point number with an
+ optional unit name appended. The unit name can be one of "Hz",
+ "kHz", "k", "MHz", "M". The multiplier associated with the unit
+ is stored in &s.code;freq.units&e.code;, and the scaled frequency
+ is stored in &s.code;freq.freq&e.code;. When no unit is specified,
+ &s.code;freq.units&e.code; is set to &s.code;0&e.code;, and
+ &s.code;freq.freq&e.code; is unscaled.
+
+ Typical usage is to setup an array of
+ &s.code;OptionInfoRecs&e.code; with all fields initialised.
+ The &s.code;value&e.code; and &s.code;found&e.code; fields get
+ set by &s.code;xf86ProcessOptions()&e.code;. For cases where the
+ value parsing is more complex, the driver should specify
+ &s.code;OPTV_STRING&e.code;, and parse the string itself. An
+ example of using this option handling is included in the
+ <ref id="sample" name="Sample Driver"> section.
+
+ </quote>
+
+ &s.code;void xf86ShowUnusedOptions(int scrnIndex, pointer options)&e.code;
+ <quote><p>
+ Prints out warning messages for each option in the list of options
+ that isn't marked as used. This is intended to show options that
+ the driver hasn't recognised. It would normally be called near
+ the end of the &s.code;ChipScreenInit()&e.code; function, but only
+ when &s.code;serverGeneration&nbsp;==&nbsp;1&e.code;.
+
+ </quote>
+
+ &s.code;OptionInfoPtr xf86TokenToOptinfo(const OptionInfoRec *table,
+ &f.indent;int token)&e.code;
+
+ <quote><p>
+ Returns a pointer to the &s.code;OptionInfoRec&e.code; in
+ &s.code;table&e.code; with a token field matching
+ &s.code;token&e.code;. Returns &s.code;NULL&e.code; if no match
+ is found.
+
+ </quote>
+
+ &s.code;Bool xf86IsOptionSet(const OptionInfoRec *table, int token)&e.code;
+ <quote><p>
+ Returns the &s.code;found&e.code; field of the
+ &s.code;OptionInfoRec&e.code; in &s.code;table&e.code; with a
+ &s.code;token&e.code; field matching &s.code;token&e.code;. This
+ can be used for options of all types. Note that for options of
+ type &s.code;OPTV_BOOLEAN&e.code;, it isn't sufficient to check
+ this to determine the value of the option. Returns
+ &s.code;FALSE&e.code; if no match is found.
+
+ </quote>
+
+ &s.code;char *xf86GetOptValString(const OptionInfoRec *table, int token)&e.code;
+ <quote><p>
+ Returns the &s.code;value.str&e.code; field of the
+ &s.code;OptionInfoRec&e.code; in &s.code;table&e.code; with a
+ token field matching &s.code;token&e.code;. Returns
+ &s.code;NULL&e.code; if no match is found.
+
+ </quote>
+
+ &s.code;Bool xf86GetOptValInteger(const OptionInfoRec *table, int token,
+ &f.indent;int *value)&e.code;
+ <quote><p>
+ Returns via &s.code;*value&e.code; the &s.code;value.num&e.code;
+ field of the &s.code;OptionInfoRec&e.code; in &s.code;table&e.code;
+ with a &s.code;token&e.code; field matching &s.code;token&e.code;.
+ &s.code;*value&e.code; is only changed when a match is found so
+ it can be safely initialised with a default prior to calling this
+ function. The function return value is as for
+ &s.code;xf86IsOptionSet()&e.code;.
+
+ </quote>
+
+ &s.code;Bool xf86GetOptValULong(const OptionInfoRec *table, int token,
+ &f.indent;unsigned long *value)&e.code;
+ <quote><p>
+ Like &s.code;xf86GetOptValInteger()&e.code;, except the value is
+ treated as an &s.code;unsigned long&e.code;.
+
+ </quote>
+
+ &s.code;Bool xf86GetOptValReal(const OptionInfoRec *table, int token,
+ &f.indent;double *value)&e.code;
+ <quote><p>
+ Like &s.code;xf86GetOptValInteger()&e.code;, except that
+ &s.code;value.realnum&e.code; is used.
+
+ </quote>
+
+ &s.code;Bool xf86GetOptValFreq(const OptionInfoRec *table, int token,
+ &f.indent;OptFreqUnits expectedUnits, double *value)&e.code;
+ <quote><p>
+ Like &s.code;xf86GetOptValInteger()&e.code;, except that the
+ &s.code;value.freq&e.code; data is returned. The frequency value
+ is scaled to the units indicated by &s.code;expectedUnits&e.code;.
+ The scaling is exact when the units were specified explicitly in
+ the option's value. Otherwise, the &s.code;expectedUnits&e.code;
+ field is used as a hint when doing the scaling. In this case,
+ values larger than &s.code;1000&e.code; are assumed to have be
+ specified in the next smallest units. For example, if the Option
+ value is "10000" and expectedUnits is &s.code;OPTUNITS_MHZ&e.code;,
+ the value returned is &s.code;10&e.code;.
+
+ </quote>
+
+ &s.code;Bool xf86GetOptValBool(const OptionInfoRec *table, int token, Bool *value)&e.code;
+ <quote><p>
+ This function is used to check boolean options
+ (&s.code;OPTV_BOOLEAN&e.code;). If the function return value is
+ &s.code;FALSE&e.code;, it means the option wasn't set. Otherwise
+ &s.code;*value&e.code; is set to the boolean value indicated by
+ the option's value. No option &s.code;value&e.code; is interpreted
+ as &s.code;TRUE&e.code;. Option values meaning &s.code;TRUE&e.code;
+ are "1", "yes", "on", "true", and option values meaning
+ &s.code;FALSE&e.code; are "0", "no", "off", "false". Option names
+ both with the "no" prefix in their names, and with that prefix
+ removed are also checked and handled in the obvious way.
+ &s.code;*value&e.code; is not changed when the option isn't present.
+ It should normally be set to a default value before calling this
+ function.
+
+ </quote>
+
+ &s.code;Bool xf86ReturnOptValBool(const OptionInfoRec *table, int token, Bool def)&e.code;
+ <quote><p>
+ This function is used to check boolean options
+ (&s.code;OPTV_BOOLEAN&e.code;). If the option is set, its value
+ is returned. If the options is not set, the default value specified
+ by &s.code;def&e.code; is returned. The option interpretation is
+ the same as for &s.code;xf86GetOptValBool()&e.code;.
+
+ </quote>
+
+ &s.code;int xf86NameCmp(const char *s1, const char *s2)&e.code;
+ <quote><p>
+ This function should be used when comparing strings from the config
+ file with expected values. It works like &s.code;strcmp()&e.code;,
+ but is not case sensitive and space, tab, and `<tt>_</tt>' characters
+ are ignored in the comparison. The use of this function isn't
+ restricted to parsing option values. It may be used anywhere
+ where this functionality required.
+
+ </quote>
+ </quote>
+
+<sect>Modules, Drivers, Include Files and Interface Issues
+<p>
+
+NOTE: this section is incomplete.
+
+
+<sect1>Include files
+<p>
+
+The following include files are typically required by video drivers:
+
+ <quote><p>
+ All drivers should include these:
+ <quote>
+ &s.code;"xf86.h"&nl;
+ "xf86_OSproc.h"&nl;
+ "xf86_ansic.h"&nl;
+ "xf86Resources.h"&e.code;
+ </quote>
+ Wherever inb/outb (and related things) are used the following should be
+ included:
+ <quote>
+ &s.code;"compiler.h"&e.code;
+ </quote>
+ Note: in drivers, this must be included after &s.code;"xf86_ansic.h"&e.code;.
+
+ Drivers that need to access PCI vendor/device definitions need this:
+ <quote>
+ &s.code;"xf86PciInfo.h"&e.code;
+ </quote>
+
+ Drivers that need to access the PCI config space need this:
+ <quote>
+ &s.code;"xf86Pci.h"&e.code;
+ </quote>
+
+ Drivers that initialise a SW cursor need this:
+ <quote>
+ &s.code;"mipointer.h"&e.code;
+ </quote>
+
+ All drivers implementing backing store need this:
+ <quote>
+ &s.code;"mibstore.h"&e.code;
+ </quote>
+
+ All drivers using the mi colourmap code need this:
+ <quote>
+ &s.code;"micmap.h"&e.code;
+ </quote>
+
+ If a driver uses the vgahw module, it needs this:
+ <quote>
+ &s.code;"vgaHW.h"&e.code;
+ </quote>
+
+ Drivers supporting VGA or Hercules monochrome screens need:
+ <quote>
+ &s.code;"xf1bpp.h"&e.code;
+ </quote>
+
+ Drivers supporting VGA or EGC 16-colour screens need:
+ <quote>
+ &s.code;"xf4bpp.h"&e.code;
+ </quote>
+
+ Drivers using cfb need:
+ <quote>
+ &s.code;#define PSZ 8&nl;
+ #include "cfb.h"&nl;
+ #undef PSZ&e.code;
+ </quote>
+
+ Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
+ <quote>
+ &s.code;"cfb16.h"&nl;
+ "cfb24.h"&nl;
+ "cfb32.h"&e.code;
+ </quote>
+
+ If a driver uses XAA, it needs these:
+ <quote>
+ &s.code;"xaa.h"&nl;
+ "xaalocal.h"&e.code;
+ </quote>
+
+ If a driver uses the fb manager, it needs this:
+ <quote>
+ &s.code;"xf86fbman.h"&e.code;
+ </quote>
+ </quote>
+
+Non-driver modules should include &s.code;"xf86_ansic.h"&e.code; to get the correct
+wrapping of ANSI C/libc functions.
+
+All modules must NOT include any system include files, or the following:
+
+ <quote>
+ &s.code;"xf86Priv.h"&nl;
+ "xf86Privstr.h"&nl;
+ "xf86_OSlib.h"&nl;
+ "Xos.h"&e.code;
+ </quote>
+
+In addition, "xf86_libc.h" must not be included explicitly. It is
+included implicitly by "xf86_ansic.h".
+
+
+<sect>Offscreen Memory Manager
+<p>
+
+Management of offscreen video memory may be handled by the XFree86
+framebuffer manager. Once the offscreen memory manager is running,
+drivers or extensions may allocate, free or resize areas of offscreen
+video memory using the following functions (definitions taken from
+&s.code;xf86fbman.h&e.code;):
+
+<code>
+ typedef struct _FBArea {
+ ScreenPtr pScreen;
+ BoxRec box;
+ int granularity;
+ void (*MoveAreaCallback)(struct _FBArea*, struct _FBArea*)
+ void (*RemoveAreaCallback)(struct _FBArea*)
+ DevUnion devPrivate;
+ } FBArea, *FBAreaPtr;
+
+ typedef void (*MoveAreaCallbackProcPtr)(FBAreaPtr from, FBAreaPtr to)
+ typedef void (*RemoveAreaCallbackProcPtr)(FBAreaPtr)
+
+ FBAreaPtr xf86AllocateOffscreenArea (
+ ScreenPtr pScreen,
+ int width, int height,
+ int granularity,
+ MoveAreaCallbackProcPtr MoveAreaCallback,
+ RemoveAreaCallbackProcPtr RemoveAreaCallback,
+ pointer privData
+ )
+
+ void xf86FreeOffscreenArea (FBAreaPtr area)
+
+ Bool xf86ResizeOffscreenArea (
+ FBAreaPtr area
+ int w, int h
+ )
+</code>
+
+The function:
+<quote>
+ &s.code;Bool xf86FBManagerRunning(ScreenPtr pScreen)&e.code;
+</quote>
+
+can be used by an extension to check if the driver has initialized
+the memory manager. The manager is not available if this returns
+&s.code;FALSE&e.code; and the functions above will all fail.
+
+
+&s.code;xf86AllocateOffscreenArea()&e.code; can be used to request a
+rectangle of dimensions &s.code;width&e.code; x &s.code;height&e.code;
+(in pixels) from unused offscreen memory. &s.code;granularity&e.code;
+specifies that the leftmost edge of the rectangle must lie on some
+multiple of &s.code;granularity&e.code; pixels. A granularity of zero
+means the same thing as a granularity of one - no alignment preference.
+A &s.code;MoveAreaCallback&e.code; can be provided to notify the requester
+when the offscreen area is moved. If no &s.code;MoveAreaCallback&e.code;
+is supplied then the area is considered to be immovable. The
+&s.code;privData&e.code; field will be stored in the manager's internal
+structure for that allocated area and will be returned to the requester
+in the &s.code;FBArea&e.code; passed via the
+&s.code;MoveAreaCallback&e.code;. An optional
+&s.code;RemoveAreaCallback&e.code; is provided. If the driver provides
+this it indicates that the area should be allocated with a lower priority.
+Such an area may be removed when a higher priority request (one that
+doesn't have a &s.code;RemoveAreaCallback&e.code;) is made. When this
+function is called, the driver will have an opportunity to do whatever
+cleanup it needs to do to deal with the loss of the area, but it must
+finish its cleanup before the function exits since the offscreen memory
+manager will free the area immediately after.
+
+&s.code;xf86AllocateOffscreenArea()&e.code; returns &s.code;NULL&e.code;
+if it was unable to allocate the requested area. When no longer needed,
+areas should be freed with &s.code;xf86FreeOffscreenArea()&e.code;.
+
+&s.code;xf86ResizeOffscreenArea()&e.code; resizes an existing
+&s.code;FBArea&e.code;. &s.code;xf86ResizeOffscreenArea()&e.code;
+returns &s.code;TRUE&e.code; if the resize was successful. If
+&s.code;xf86ResizeOffscreenArea()&e.code; returns &s.code;FALSE&e.code;,
+the original &s.code;FBArea&e.code; is left unmodified. Resizing an
+area maintains the area's original &s.code;granularity&e.code;,
+&s.code;devPrivate&e.code;, and &s.code;MoveAreaCallback&e.code;.
+&s.code;xf86ResizeOffscreenArea()&e.code; has considerably less overhead
+than freeing the old area then reallocating the new size, so it should
+be used whenever possible.
+
+The function:
+ <quote>
+ &s.code;Bool xf86QueryLargestOffscreenArea(
+ &f.indent;ScreenPtr pScreen,
+ &f.indent;int *width, int *height,
+ &f.indent;int granularity,
+ &f.indent;int preferences,
+ &f.indent;int priority
+ &nl)&e.code;
+ </quote>
+
+is provided to query the width and height of the largest single
+&s.code;FBArea&e.code; allocatable given a particular priority.
+&s.code;preferences&e.code; can be one of the following to indicate
+whether width, height or area should be considered when determining
+which is the largest single &s.code;FBArea&e.code; available.
+
+ <quote>
+ &s.code;FAVOR_AREA_THEN_WIDTH&nl;
+ FAVOR_AREA_THEN_HEIGHT&nl;
+ FAVOR_WIDTH_THEN_AREA&nl;
+ FAVOR_HEIGHT_THEN_AREA&e.code;
+ </quote>
+
+&s.code;priority&e.code; is one of the following:
+
+ <quote><p>
+ &s.code;PRIORITY_LOW&e.code;
+ <quote><p>
+ Return the largest block available without stealing anyone else's
+ space. This corresponds to the priority of allocating a
+ &s.code;FBArea&e.code; when a &s.code;RemoveAreaCallback&e.code;
+ is provided.
+
+ </quote>
+ &s.code;PRIORITY_NORMAL&e.code;
+ <quote><p>
+ Return the largest block available if it is acceptable to steal a
+ lower priority area from someone. This corresponds to the priority
+ of allocating a &s.code;FBArea&e.code; without providing a
+ &s.code;RemoveAreaCallback&e.code;.
+
+ </quote>
+ &s.code;PRIORITY_EXTREME&e.code;
+ <quote><p>
+ Return the largest block available if all &s.code;FBAreas&e.code;
+ that aren't locked down were expunged from memory first. This
+ corresponds to any allocation made directly after a call to
+ &s.code;xf86PurgeUnlockedOffscreenAreas()&e.code;.
+
+ </quote>
+ </quote>
+
+
+The function:
+
+ <quote>
+ &s.code;Bool xf86PurgeUnlockedOffscreenAreas(ScreenPtr pScreen)&e.code;
+ </quote>
+
+is provided as an extreme method to free up offscreen memory. This
+will remove all removable &s.code;FBArea&e.code; allocations.
+
+
+Initialization of the XFree86 framebuffer manager is done via
+
+ <quote>
+ &s.code;Bool xf86InitFBManager(ScreenPtr pScreen, BoxPtr FullBox)&e.code;
+ </quote>
+
+&s.code;FullBox&e.code; represents the area of the framebuffer that the
+manager is allowed to manage. This is typically a box with a width of
+&s.code;pScrn-&gt;displayWidth&e.code; and a height of as many lines as
+can be fit within the total video memory, however, the driver can reserve
+areas at the extremities by passing a smaller area to the manager.
+
+&s.code;xf86InitFBManager()&e.code; must be called before XAA is
+initialized since XAA uses the manager for it's pixmap cache.
+
+An alternative function is provided to allow the driver to initialize
+the framebuffer manager with a Region rather than a box.
+
+ <quote>
+ &s.code;Bool xf86InitFBManagerRegion(ScreenPtr pScreen,
+ &f.indent;RegionPtr FullRegion)&e.code;
+ </quote>
+
+&s.code;xf86InitFBManagerRegion()&e.code;, unlike
+&s.code;xf86InitFBManager()&e.code;, does not remove the area used for
+the visible screen so that area should not be included in the region
+passed to the function. &s.code;xf86InitFBManagerRegion()&e.code; is
+useful when non-contiguous areas are available to be managed, and is
+required when multiple framebuffers are stored in video memory (as in
+the case where an overlay of a different depth is stored as a second
+framebuffer in offscreen memory).
+
+
+<sect>Colormap Handling<label id="cmap">
+<p>
+
+A generic colormap handling layer is provided within the XFree86 common
+layer. This layer takes care of most of the details, and only requires
+a function from the driver that loads the hardware palette when required.
+To use the colormap layer, a driver calls the
+&s.code;xf86HandleColormaps()&e.code; function.
+
+ <quote><p>
+ &s.code;Bool xf86HandleColormaps(ScreenPtr pScreen, int maxColors,
+ &f.indent;int sigRGBbits, LoadPaletteFuncPtr loadPalette,
+ &f.indent;SetOverscanFuncPtr setOverscan,
+ unsigned int flags)&e.code;
+ <quote><p>
+ This function must be called after the default colormap has been
+ initialised. The &s.code;pScrn-&gt;gamma&e.code; field must also
+ be initialised, preferably by calling &s.code;xf86SetGamma()&e.code;.
+ &s.code;maxColors&e.code; is the number of entries in the palette.
+ &s.code;sigRGBbits&e.code; is the size in bits of each color
+ component in the DAC's palette. &s.code;loadPalette&e.code;
+ is a driver-provided function for loading a colormap into the
+ hardware, and is described below. &s.code;setOverscan&e.code; is
+ an optional function that may be provided when the overscan color
+ is an index from the standard LUT and when it needs to be adjusted
+ to keep it as close to black as possible. The
+ &s.code;setOverscan&e.code; function programs the overscan index.
+ It shouldn't normally be used for depths other than 8.
+ &s.code;setOverscan&e.code; should be set to &s.code;NULL&e.code;
+ when it isn't needed. &s.code;flags&e.code; may be set to the
+ following (which may be ORed together):
+
+ &s.code;CMAP_PALETTED_TRUECOLOR&e.code;
+ <quote><p>
+ the TrueColor visual is paletted and is
+ just a special case of DirectColor.
+ This flag is only valid for
+ &s.code;bpp&nbsp;&gt;&nbsp;8&e.code;.
+
+ </quote>
+
+ &s.code;CMAP_RELOAD_ON_MODE_SWITCH&e.code;
+ <quote><p>
+ reload the colormap automatically
+ after mode switches. This is useful
+ for when the driver is resetting the
+ hardware during mode switches and
+ corrupting or erasing the hardware
+ palette.
+
+ </quote>
+
+ &s.code;CMAP_LOAD_EVEN_IF_OFFSCREEN&e.code;
+ <quote><p>
+ reload the colormap even if the screen
+ is switched out of the server's VC.
+ The palette is <it>not</it> reloaded when
+ the screen is switched back in, nor after
+ mode switches. This is useful when the
+ driver needs to keep track of palette
+ changes.
+
+ </quote>
+
+ The colormap layer normally reloads the palette after VT enters so it
+ is not necessary for the driver to save and restore the palette
+ when switching VTs. The driver must, however, still save the
+ initial palette during server start up and restore it during
+ server exit.
+
+ </quote>
+
+ &s.code;void LoadPalette(ScrnInfoPtr pScrn, int numColors, int *indices,
+ &f.indent;LOCO *colors, VisualPtr pVisual)&e.code;
+ <quote><p>
+ &s.code;LoadPalette()&e.code; is a driver-provided function for
+ loading a colormap into hardware. &s.code;colors&e.code; is the
+ array of RGB values that represent the full colormap.
+ &s.code;indices&e.code; is a list of index values into the colors
+ array. These indices indicate the entries that need to be updated.
+ &s.code;numColors&e.code; is the number of the indices to be
+ updated.
+
+ </quote>
+
+ &s.code;void SetOverscan(ScrnInfoPtr pScrn, int overscan)&e.code;
+ <quote><p>
+ &s.code;SetOverscan()&e.code; is a driver-provided function for
+ programming the &s.code;overscan&e.code; index. As described
+ above, it is normally only appropriate for LUT modes where all
+ colormap entries are available for the display, but where one of
+ them is also used for the overscan (typically 8bpp for VGA compatible
+ LUTs). It isn't required in cases where the overscan area is
+ never visible.
+
+ </quote>
+ </quote>
+
+
+<sect>DPMS Extension
+<p>
+
+Support code for the DPMS extension is included in the XFree86 common layer.
+This code provides an interface between the main extension code, and a means
+for drivers to initialise DPMS when they support it. One function is
+available to drivers to do this initialisation, and it is always available,
+even when the DPMS extension is not supported by the core server (in
+which case it returns a failure result).
+
+
+ <quote><p>
+ &s.code;Bool xf86DPMSInit(ScreenPtr pScreen, DPMSSetProcPtr set, int flags)&e.code;
+ <quote><p>
+ This function registers a driver's DPMS level programming function
+ &s.code;set&e.code;. It also checks
+ &s.code;pScrn-&gt;options&e.code; for the "dpms" option, and when
+ present marks DPMS as being enabled for that screen. The
+ &s.code;set&e.code; function is called whenever the DPMS level
+ changes, and is used to program the requested level.
+ &s.code;flags&e.code; is currently not used, and should be
+ &s.code;0&e.code;. If the initialisation fails for any reason,
+ including when there is no DPMS support in the core server, the
+ function returns &s.code;FALSE&e.code;.
+
+ </quote>
+ </quote>
+
+
+Drivers that implement DPMS support must provide the following function,
+that gets called when the DPMS level is changed:
+
+
+ <quote><p>
+ &s.code;void ChipDPMSSet(ScrnInfoPtr pScrn, int level, int flags)&e.code;
+ <quote><p>
+ Program the DPMS level specified by &s.code;level&e.code;. Valid
+ values of &s.code;level&e.code; are &s.code;DPMSModeOn&e.code;,
+ &s.code;DPMSModeStandby&e.code;, &s.code;DPMSModeSuspend&e.code;,
+ &s.code;DPMSModeOff&e.code;. These values are defined in
+ &s.code;"extensions/dpms.h"&e.code;.
+
+ </quote>
+ </quote>
+
+
+<sect>DGA Extension
+<p>
+
+Drivers can support the XFree86 Direct Graphics Architecture (DGA) by
+filling out a structure of function pointers and a list of modes and
+passing them to DGAInit.
+
+ <quote><p>
+ &s.code;Bool DGAInit(ScreenPtr pScreen, DGAFunctionPtr funcs,
+ &f.indent;DGAModePtr modes, int num)&e.code;
+ <quote><p>
+ <verb>
+/** The DGAModeRec **/
+
+typedef struct {
+ int num;
+ DisplayModePtr mode;
+ int flags;
+ int imageWidth;
+ int imageHeight;
+ int pixmapWidth;
+ int pixmapHeight;
+ int bytesPerScanline;
+ int byteOrder;
+ int depth;
+ int bitsPerPixel;
+ unsigned long red_mask;
+ unsigned long green_mask;
+ unsigned long blue_mask;
+ int viewportWidth;
+ int viewportHeight;
+ int xViewportStep;
+ int yViewportStep;
+ int maxViewportX;
+ int maxViewportY;
+ int viewportFlags;
+ int offset;
+ unsigned char *address;
+ int reserved1;
+ int reserved2;
+} DGAModeRec, *DGAModePtr;
+</verb>
+
+ &s.code;num&e.code;
+ <quote>
+ Can be ignored. The DGA DDX will assign these numbers.
+ </quote>
+
+ &s.code;mode&e.code;
+ <quote>
+ A pointer to the &s.code;DisplayModeRec&e.code; for this mode.
+ </quote>
+
+ &s.code;flags&e.code;
+ <quote><p>
+ The following flags are defined and may be OR'd together:
+
+ &s.code;DGA_CONCURRENT_ACCESS&e.code;
+ <quote><p>
+ Indicates that the driver supports concurrent graphics
+ accelerator and linear framebuffer access.
+
+ </quote>
+
+ &s.code;DGA_FILL_RECT&nl;
+ DGA_BLIT_RECT&nl;
+ DGA_BLIT_RECT_TRANS&e.code;
+ <quote><p>
+ Indicates that the driver supports the FillRect, BlitRect
+ or BlitTransRect functions in this mode.
+
+ </quote>
+
+ &s.code;DGA_PIXMAP_AVAILABLE&e.code;
+ <quote><p>
+ Indicates that Xlib may be used on the framebuffer.
+ This flag will usually be set unless the driver wishes
+ to prohibit this for some reason.
+
+ </quote>
+
+ &s.code;DGA_INTERLACED&nl;
+ DGA_DOUBLESCAN&e.code;
+ <quote><p>
+ Indicates that these are interlaced or double scan modes.
+
+ </quote>
+ </quote>
+
+ &s.code;imageWidth&nl;
+ imageHeight&e.code;
+ <quote><p>
+ These are the dimensions of the linear framebuffer
+ accessible by the client.
+
+ </quote>
+
+ &s.code;pixmapWidth&nl;
+ pixmapHeight&e.code;
+ <quote><p>
+ These are the dimensions of the area of the
+ framebuffer accessible by the graphics accelerator.
+
+ </quote>
+
+ &s.code;bytesPerScanline&e.code;
+ <quote><p>
+ Pitch of the framebuffer in bytes.
+
+ </quote>
+
+ &s.code;byteOrder&e.code;
+ <quote><p>
+ Usually the same as
+ &s.code;pScrn-&gt;imageByteOrder&e.code;.
+
+ </quote>
+
+ &s.code;depth&e.code;
+ <quote><p>
+ The depth of the framebuffer in this mode.
+
+ </quote>
+
+ &s.code;bitsPerPixel&e.code;
+ <quote><p>
+ The number of bits per pixel in this mode.
+
+ </quote>
+
+ &s.code;red_mask&nl;
+ green_mask&nl;
+ blue_mask&e.code;
+ <quote><p>
+ The RGB masks for this mode, if applicable.
+
+ </quote>
+
+ &s.code;viewportWidth&nl;
+ viewportHeight&e.code;
+ <quote><p>
+ Dimensions of the visible part of the framebuffer.
+ Usually &s.code;mode-&gt;HDisplay&e.code; and
+ &s.code;mode-&gt;VDisplay&e.code;.
+
+ </quote>
+
+ &s.code;xViewportStep&nl;
+ yViewportStep&e.code;
+ <quote><p>
+ The granularity of x and y viewport positions that
+ the driver supports in this mode.
+
+ </quote>
+
+ &s.code;maxViewportX&nl;
+ maxViewportY&e.code;
+ <quote><p>
+ The maximum viewport position supported by the
+ driver in this mode.
+
+ </quote>
+
+ &s.code;viewportFlags&e.code;
+ <quote><p>
+ The following may be OR'd together:
+
+ &s.code;DGA_FLIP_IMMEDIATE&e.code;
+ <quote><p>
+ The driver supports immediate viewport changes.
+
+ </quote>
+ &s.code;DGA_FLIP_RETRACE&e.code;
+ <quote<p>
+ The driver supports viewport changes at retrace.
+
+ </quote>
+ </quote>
+
+ &s.code;offset&e.code;
+ <quote><p>
+ The offset into the linear framebuffer that corresponds to
+ pixel (0,0) for this mode.
+
+ </quote>
+
+ &s.code;address&e.code;
+ <quote><p>
+ The virtual address of the framebuffer as mapped by the driver.
+ This is needed when DGA_PIXMAP_AVAILABLE is set.
+
+ </quote>
+
+ <verb>
+/** The DGAFunctionRec **/
+
+typedef struct {
+ Bool (*OpenFramebuffer)(
+ ScrnInfoPtr pScrn,
+ char **name,
+ unsigned char **mem,
+ int *size,
+ int *offset,
+ int *extra
+ );
+ void (*CloseFramebuffer)(ScrnInfoPtr pScrn);
+ Bool (*SetMode)(ScrnInfoPtr pScrn, DGAModePtr pMode);
+ void (*SetViewport)(ScrnInfoPtr pScrn, int x, int y, int flags);
+ int (*GetViewport)(ScrnInfoPtr pScrn);
+ void (*Sync)(ScrnInfoPtr);
+ void (*FillRect)(
+ ScrnInfoPtr pScrn,
+ int x, int y, int w, int h,
+ unsigned long color
+ );
+ void (*BlitRect)(
+ ScrnInfoPtr pScrn,
+ int srcx, int srcy,
+ int w, int h,
+ int dstx, int dsty
+ );
+ void (*BlitTransRect)(
+ ScrnInfoPtr pScrn,
+ int srcx, int srcy,
+ int w, int h,
+ int dstx, int dsty,
+ unsigned long color
+ );
+} DGAFunctionRec, *DGAFunctionPtr;
+</verb>
+
+ </quote>
+
+ &s.code;Bool OpenFramebuffer (pScrn, name, mem, size, offset, extra)&e.code;
+ <quote><p>
+ &s.code;OpenFramebuffer()&e.code; should pass the client everything
+ it needs to know to be able to open the framebuffer. These
+ parameters are OS specific and their meanings are to be interpreted
+ by an OS specific client library.
+
+ &s.code;name&e.code;
+ <quote><p>
+ The name of the device to open or &s.code;NULL&e.code; if
+ there is no special device to open. A &s.code;NULL&e.code;
+ name tells the client that it should open whatever device
+ one would usually open to access physical memory.
+
+ </quote>
+ &s.code;mem&e.code;
+ <quote><p>
+ The physical address of the start of the framebuffer.
+
+ </quote>
+ &s.code;size&e.code;
+ <quote><p>
+ The size of the framebuffer in bytes.
+
+ </quote>
+ &s.code;offset&e.code;
+ <quote><p>
+ Any offset into the device, if applicable.
+
+ </quote>
+ &s.code;flags&e.code;
+ <quote><p>
+ Any additional information that the client may need.
+ Currently, only the &s.code;DGA_NEED_ROOT&e.code; flag is
+ defined.
+
+ </quote>
+ </quote>
+
+ &s.code;void CloseFramebuffer (pScrn)&e.code;
+ <quote><p>
+ &s.code;CloseFramebuffer()&e.code; merely informs the driver (if it
+ even cares) that client no longer needs to access the framebuffer
+ directly. This function is optional.
+
+ </quote>
+
+ &s.code;Bool SetMode (pScrn, pMode)&e.code;
+ <quote><p>
+ &s.code;SetMode()&e.code; tells the driver to initialize the mode
+ passed to it. If &s.code;pMode&e.code; is &s.code;NULL&e.code;,
+ then the driver should restore the original pre-DGA mode.
+
+ </quote>
+
+ &s.code;void SetViewport (pScrn, x, y, flags)&e.code;
+ <quote><p>
+ &s.code;SetViewport()&e.code; tells the driver to make the upper
+ left-hand corner of the visible screen correspond to coordinate
+ &s.code;(x,y)&e.code; on the framebuffer. &s.code;Flags&e.code;
+ currently defined are:
+
+ &s.code;DGA_FLIP_IMMEDIATE&e.code;
+ <quote><p>
+ The viewport change should occur immediately.
+
+ </quote>
+ &s.code;DGA_FLIP_RETRACE&e.code;
+ <quote><p>
+ The viewport change should occur at the
+ vertical retrace, but this function should
+ return sooner if possible.
+
+ </quote>
+ The &s.code;(x,y)&e.code; locations will be passed as the client
+ specified them, however, the driver is expected to round these
+ locations down to the next supported location as specified by the
+ &s.code;xViewportStep&e.code; and &s.code;yViewportStep&e.code;
+ for the current mode.
+
+ </quote>
+
+ &s.code;int GetViewport (pScrn)&e.code;
+ <quote><p>
+ &s.code;GetViewport()&e.code; gets the current page flip status.
+ Set bits in the returned int correspond to viewport change requests
+ still pending. For instance, set bit zero if the last SetViewport
+ request is still pending, bit one if the one before that is still
+ pending, etc.
+
+ </quote>
+
+ &s.code;void Sync (pScrn)&e.code;
+ <quote><p>
+ This function should ensure that any graphics accelerator operations
+ have finished. This function should not return until the graphics
+ accelerator is idle.
+
+ </quote>
+
+ &s.code;void FillRect (pScrn, x, y, w, h, color)&e.code;
+ <quote><p>
+ This optional function should fill a rectangle
+ &s.code;w&nbsp;&times;&nbsp;h&e.code; located at
+ &s.code;(x,y)&e.code; in the given color.
+
+ </quote>
+
+ &s.code;void BlitRect (pScrn, srcx, srcy, w, h, dstx, dsty)&e.code;
+ <quote><p>
+ This optional function should copy an area
+ &s.code;w&nbsp;&times;&nbsp;h&e.code; located at
+ &s.code;(srcx,srcy)&e.code; to location &s.code;(dstx,dsty)&e.code;.
+ This function will need to handle copy directions as appropriate.
+
+ </quote>
+
+ &s.code;void BlitTransRect (pScrn, srcx, srcy, w, h, dstx, dsty, color)&e.code;
+ <quote><p>
+ This optional function is the same as BlitRect except that pixels
+ in the source corresponding to the color key &s.code;color&e.code;
+ should be skipped.
+
+ </quote>
+ </quote>
+
+<sect>The XFree86 X Video Extension (Xv) Device Dependent Layer
+<p>
+
+XFree86 offers the X Video Extension which allows clients to treat video
+as any another primitive and ``Put'' video into drawables. By default,
+the extension reports no video adaptors as being available since the
+DDX layer has not been initialized. The driver can initialize the DDX
+layer by filling out one or more &s.code;XF86VideoAdaptorRecs&e.code;
+as described later in this document and passing a list of
+&s.code;XF86VideoAdaptorPtr&e.code; pointers to the following function:
+
+ <quote>
+ &s.code;Bool xf86XVScreenInit(
+ &f.indent;ScreenPtr pScreen,
+ &f.indent;XF86VideoAdaptorPtr *adaptPtrs,
+ &f.indent;int num)&e.code;
+ </quote>
+
+After doing this, the extension will report video adaptors as being
+available, providing the data in their respective
+&s.code;XF86VideoAdaptorRecs&e.code; was valid.
+&s.code;xf86XVScreenInit()&e.code; <em>copies</em> data from the structure
+passed to it so the driver may free it after the initialization. At
+the moment, the DDX only supports rendering into Window drawables.
+Pixmap rendering will be supported after a sufficient survey of suitable
+hardware is completed.
+
+The &s.code;XF86VideoAdaptorRec&e.code;:
+
+<quote><p>
+<verb>
+typedef struct {
+ unsigned int type;
+ int flags;
+ char *name;
+ int nEncodings;
+ XF86VideoEncodingPtr pEncodings;
+ int nFormats;
+ XF86VideoFormatPtr pFormats;
+ int nPorts;
+ DevUnion *pPortPrivates;
+ int nAttributes;
+ XF86AttributePtr pAttributes;
+ int nImages;
+ XF86ImagePtr pImages;
+ PutVideoFuncPtr PutVideo;
+ PutStillFuncPtr PutStill;
+ GetVideoFuncPtr GetVideo;
+ GetStillFuncPtr GetStill;
+ StopVideoFuncPtr StopVideo;
+ SetPortAttributeFuncPtr SetPortAttribute;
+ GetPortAttributeFuncPtr GetPortAttribute;
+ QueryBestSizeFuncPtr QueryBestSize;
+ PutImageFuncPtr PutImage;
+ QueryImageAttributesFuncPtr QueryImageAttributes;
+} XF86VideoAdaptorRec, *XF86VideoAdaptorPtr;
+</verb>
+
+ Each adaptor will have its own XF86VideoAdaptorRec. The fields are
+ as follows:
+
+ &s.code;type&e.code;
+ <quote><p>
+ This can be any of the following flags OR'd together.
+
+ &s.code;XvInputMask&e.code;
+ &s.code;XvOutputMask&e.code;
+ <quote><p>
+ These refer to the target drawable and are similar to a Window's
+ class. &s.code;XvInputMask&e.code; indicates that the adaptor
+ can put video into a drawable. &s.code;XvOutputMask&e.code;
+ indicates that the adaptor can get video from a drawable.
+ </quote>
+
+ &s.code;XvVideoMask&e.code;
+ &s.code;XvStillMask&e.code;
+ &s.code;XvImageMask&e.code;
+ <quote><p>
+ These indicate that the adaptor supports video, still or
+ image primitives respectively.
+ </quote>
+
+ &s.code;XvWindowMask&e.code;
+ &s.code;XvPixmapMask&e.code;
+ <quote><p>
+ These indicate the types of drawables the adaptor is capable
+ of rendering into. At the moment, Pixmap rendering is not
+ supported and the &s.code;XvPixmapMask&e.code; flag is ignored.
+ </quote>
+
+ </quote>
+
+ &s.code;flags&e.code;
+ <quote><p>
+ Currently, the following flags are defined:
+
+ &s.code;VIDEO_NO_CLIPPING&e.code;
+ <quote><p>
+ This indicates that the video adaptor does not support
+ clipping. The driver will never receive ``Put'' requests
+ where less than the entire area determined by
+ &s.code;drw_x&e.code;, &s.code;drw_y&e.code;,
+ &s.code;drw_w&e.code; and &s.code;drw_h&e.code; is visible.
+ This flag does not apply to ``Get'' requests. Hardware
+ that is incapable of clipping ``Gets'' may punt or get
+ the extents of the clipping region passed to it.
+
+ </quote>
+
+ &s.code;VIDEO_INVERT_CLIPLIST&e.code;
+ <quote><p>
+ This indicates that the video driver requires the clip
+ list to contain the regions which are obscured rather
+ than the regions which are are visible.
+
+ </quote>
+
+ &s.code;VIDEO_OVERLAID_STILLS&e.code;
+ <quote><p>
+ Implementing PutStill for hardware that does video as an
+ overlay can be awkward since it's unclear how long to leave
+ the video up for. When this flag is set, StopVideo will be
+ called whenever the destination gets clipped or moved so that
+ the still can be left up until then.
+
+ </quote>
+
+ &s.code;VIDEO_OVERLAID_IMAGES&e.code;
+ <quote><p>
+ Same as &s.code;VIDEO_OVERLAID_STILLS&e.code; but for images.
+ </quote>
+
+ &s.code;VIDEO_CLIP_TO_VIEWPORT&e.code;
+ <quote><p>
+ Indicates that the clip region passed to the driver functions
+ should be clipped to the visible portion of the screen in the
+ case where the viewport is smaller than the virtual desktop.
+ </quote>
+
+ </quote>
+
+ &s.code;name&e.code;
+ <quote><p>
+ The name of the adaptor.
+
+ </quote>
+
+ &s.code;nEncodings&nl;
+ pEncodings&e.code;
+ <quote><p>
+ The number of encodings the adaptor is capable of and pointer
+ to the &s.code;XF86VideoEncodingRec&e.code; array. The
+ &s.code;XF86VideoEncodingRec&e.code; is described later on.
+ For drivers that only support XvImages there should be an encoding
+ named "XV_IMAGE" and the width and height should specify
+ the maximum size source image supported.
+
+ </quote>
+
+ &s.code;nFormats&nl;
+ pFormats&e.code;
+ <quote><p>
+ The number of formats the adaptor is capable of and pointer to
+ the &s.code;XF86VideoFormatRec&e.code; array. The
+ &s.code;XF86VideoFormatRec&e.code; is described later on.
+
+ </quote>
+
+ &s.code;nPorts&nl;
+ pPortPrivates&e.code;
+ <quote><p>
+ The number of ports is the number of separate data streams which
+ the adaptor can handle simultaneously. If you have more than
+ one port, the adaptor is expected to be able to render into more
+ than one window at a time. &s.code;pPortPrivates&e.code; is
+ an array of pointers or ints - one for each port. A port's
+ private data will be passed to the driver any time the port is
+ requested to do something like put the video or stop the video.
+ In the case where there may be many ports, this enables the
+ driver to know which port the request is intended for. Most
+ commonly, this will contain a pointer to the data structure
+ containing information about the port. In Xv, all ports on
+ a particular adaptor are expected to be identical in their
+ functionality.
+
+ </quote>
+
+ &s.code;nAttributes&nl;
+ pAttributes&e.code;
+ <quote><p>
+ The number of attributes recognized by the adaptor and a pointer to
+ the array of &s.code;XF86AttributeRecs&e.code;. The
+ &s.code;XF86AttributeRec&e.code; is described later on.
+
+ </quote>
+
+ &s.code;nImages&nl;
+ pImages&e.code;
+ <quote><p>
+ The number of &s.code;XF86ImageRecs&e.code; supported by the adaptor
+ and a pointer to the array of &s.code;XF86ImageRecs&e.code;. The
+ &s.code;XF86ImageRec&e.code; is described later on.
+
+ </quote>
+
+
+ &s.code;PutVideo PutStill GetVideo GetStill StopVideo
+ SetPortAttribute GetPortAttribute QueryBestSize PutImage
+ QueryImageAttributes&e.code;
+ <quote><p>
+ These functions define the DDX-&gt;driver interface. In each
+ case, the pointer &s.code;data&e.code; is passed to the driver.
+ This is the port private for that port as described above. All
+ fields are required except under the following conditions:
+
+ <enum>
+ <item>&s.code;PutVideo&e.code;, &s.code;PutStill&e.code; and
+ the image routines &s.code;PutImage&e.code; and
+ &s.code;QueryImageAttributes&e.code; are not required when the
+ adaptor type does not contain &s.code;XvInputMask&e.code;.
+
+ <item>&s.code;GetVideo&e.code; and &s.code;GetStill&e.code;
+ are not required when the adaptor type does not contain
+ &s.code;XvOutputMask&e.code;.
+
+ <item>&s.code;GetVideo&e.code; and &s.code;PutVideo&e.code;
+ are not required when the adaptor type does not contain
+ &s.code;XvVideoMask&e.code;.
+
+ <item>&s.code;GetStill&e.code; and &s.code;PutStill&e.code;
+ are not required when the adaptor type does not contain
+ &s.code;XvStillMask&e.code;.
+
+ <item>&s.code;PutImage&e.code; and &s.code;QueryImageAttributes&e.code;
+ are not required when the adaptor type does not contain
+ &s.code;XvImageMask&e.code;.
+
+ </enum>
+
+ With the exception of &s.code;QueryImageAttributes&e.code;, these
+ functions should return &s.code;Success&e.code; if the operation was
+ completed successfully. They can return &s.code;XvBadAlloc&e.code;
+ otherwise. &s.code;QueryImageAttributes&e.code; returns the size
+ of the XvImage queried.
+
+ If the &s.code;VIDEO_NO_CLIPPING&e.code;
+ flag is set, the &s.code;clipBoxes&e.code; may be ignored by
+ the driver. &s.code;ClipBoxes&e.code; is an &s.code;X-Y&e.code;
+ banded region identical to those used throughout the server.
+ The clipBoxes represent the visible portions of the area determined
+ by &s.code;drw_x&e.code;, &s.code;drw_y&e.code;,
+ &s.code;drw_w&e.code; and &s.code;drw_h&e.code; in the Get/Put
+ function. The boxes are in screen coordinates, are guaranteed
+ not to overlap and an empty region will never be passed.
+ If the driver has specified &s.code;VIDEO_INVERT_CLIPLIST&e.code;,
+ &s.code;clipBoxes&e.code; will indicate the areas of the primitive
+ which are obscured rather than the areas visible.
+
+ </quote>
+
+ &s.code;typedef int (* PutVideoFuncPtr)( ScrnInfoPtr pScrn,
+ &f.indent;short vid_x, short vid_y, short drw_x, short drw_y,
+ &f.indent;short vid_w, short vid_h, short drw_w, short drw_h,
+ &f.indent;RegionPtr clipBoxes, pointer data )&e.code;
+ <quote><p>
+ This indicates that the driver should take a subsection
+ &s.code;vid_w&e.code; by &s.code;vid_h&e.code; at location
+ &s.code;(vid_x,vid_y)&e.code; from the video stream and direct
+ it into the rectangle &s.code;drw_w&e.code; by &s.code;drw_h&e.code;
+ at location &s.code;(drw_x,drw_y)&e.code; on the screen, scaling as
+ necessary. Due to the large variations in capabilities of
+ the various hardware expected to be used with this extension,
+ it is not expected that all hardware will be able to do this
+ exactly as described. In that case the driver should just do
+ ``the best it can,'' scaling as closely to the target rectangle
+ as it can without rendering outside of it. In the worst case,
+ the driver can opt to just not turn on the video.
+
+ </quote>
+
+ &s.code;typedef int (* PutStillFuncPtr)( ScrnInfoPtr pScrn,
+ &f.indent;short vid_x, short vid_y, short drw_x, short drw_y,
+ &f.indent;short vid_w, short vid_h, short drw_w, short drw_h,
+ &f.indent;RegionPtr clipBoxes, pointer data )&e.code;
+ <quote><p>
+ This is same as &s.code;PutVideo&e.code; except that the driver
+ should place only one frame from the stream on the screen.
+
+ </quote>
+
+ &s.code;typedef int (* GetVideoFuncPtr)( ScrnInfoPtr pScrn,
+ &f.indent;short vid_x, short vid_y, short drw_x, short drw_y,
+ &f.indent;short vid_w, short vid_h, short drw_w, short drw_h,
+ &f.indent;RegionPtr clipBoxes, pointer data )&e.code;
+ <quote><p>
+ This is same as &s.code;PutVideo&e.code; except that the driver
+ gets video from the screen and outputs it. The driver should
+ do the best it can to get the requested dimensions correct
+ without reading from an area larger than requested.
+
+ </quote>
+
+ &s.code;typedef int (* GetStillFuncPtr)( ScrnInfoPtr pScrn,
+ &f.indent;short vid_x, short vid_y, short drw_x, short drw_y,
+ &f.indent;short vid_w, short vid_h, short drw_w, short drw_h,
+ &f.indent;RegionPtr clipBoxes, pointer data )&e.code;
+ <quote><p>
+ This is the same as &s.code;GetVideo&e.code; except that the
+ driver should place only one frame from the screen into the
+ output stream.
+
+ </quote>
+
+ &s.code;typedef void (* StopVideoFuncPtr)(ScrnInfoPtr pScrn,
+ &f.indent;pointer data, Bool cleanup)&e.code;
+ <quote><p>
+ This indicates the driver should stop displaying the video.
+ This is used to stop both input and output video. The
+ &s.code;cleanup&e.code; field indicates that the video is
+ being stopped because the client requested it to stop or
+ because the server is exiting the current VT. In that case
+ the driver should deallocate any offscreen memory areas (if
+ there are any) being used to put the video to the screen. If
+ &s.code;cleanup&e.code; is not set, the video is being stopped
+ temporarily due to clipping or moving of the window, etc...
+ and video will likely be restarted soon so the driver should
+ not deallocate any offscreen areas associated with that port.
+
+ </quote>
+ &s.code;typedef int (* SetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
+ &f.indent;Atom attribute,INT32 value, pointer data)&e.code;
+
+ &s.code;typedef int (* GetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
+ &f.indent;Atom attribute,INT32 *value, pointer data)&e.code;
+
+ <quote><p>
+ A port may have particular attributes such as hue,
+ saturation, brightness or contrast. Xv clients set and
+ get these attribute values by sending attribute strings
+ (Atoms) to the server. Such requests end up at these
+ driver functions. It is recommended that the driver provide
+ at least the following attributes mentioned in the Xv client
+ library docs:
+ <quote>
+ &s.code;XV_ENCODING&nl;
+ XV_HUE&nl;
+ XV_SATURATION&nl;
+ XV_BRIGHTNESS&nl;
+ XV_CONTRAST&e.code;
+ </quote>
+ but the driver may recognize as many atoms as it wishes. If
+ a requested attribute is unknown by the driver it should return
+ &s.code;BadMatch&e.code;. &s.code;XV_ENCODING&e.code; is the
+ attribute intended to let the client specify which video
+ encoding the particular port should be using (see the description
+ of &s.code;XF86VideoEncodingRec&e.code; below). If the
+ requested encoding is unsupported, the driver should return
+ &s.code;XvBadEncoding&e.code;. If the value lies outside the
+ advertised range &s.code;BadValue&e.code; may be returned.
+ &s.code;Success&e.code; should be returned otherwise.
+
+ </quote>
+
+ &s.code;typedef void (* QueryBestSizeFuncPtr)(ScrnInfoPtr pScrn,
+ &f.indent;Bool motion, short vid_w, short vid_h,
+ &f.indent;short drw_w, short drw_h,
+ &f.indent;unsigned int *p_w, unsigned int *p_h, pointer data)&e.code;
+ <quote><p>
+ &s.code;QueryBestSize&e.code; provides the client with a way
+ to query what the destination dimensions would end up being
+ if they were to request that an area
+ &s.code;vid_w&e.code by &s.code;vid_h&e.code; from the video
+ stream be scaled to rectangle of
+ &s.code;drw_w&e.code; by &s.code;drw_h&e.code; on the screen.
+ Since it is not expected that all hardware will be able to
+ get the target dimensions exactly, it is important that the
+ driver provide this function.
+
+ </quote>
+
+ &s.code;typedef int (* PutImageFuncPtr)( ScrnInfoPtr pScrn,
+ &f.indent;short src_x, short src_y, short drw_x, short drw_y,
+ &f.indent;short src_w, short src_h, short drw_w, short drw_h,
+ &f.indent;int image, char *buf, short width, short height,
+ &f.indent;Bool sync, RegionPtr clipBoxes, pointer data )&e.code;
+ <quote><p>
+ This is similar to &s.code;PutStill&e.code; except that the
+ source of the video is not a port but the data stored in a system
+ memory buffer at &s.code;buf&e.code;. The data is in the format
+ indicated by the &s.code;image&e.code; descriptor and represents a
+ source of size &s.code;width&e.code; by &s.code;height&e.code;.
+ If &s.code;sync&e.code; is TRUE the driver should not return
+ from this function until it is through reading the data
+ from &s.code;buf&e.code;. Returning when &s.code;sync&e.code;
+ is TRUE indicates that it is safe for the data at &s.code;buf&e.code;
+ to be replaced, freed, or modified.
+
+ </quote>
+
+ &s.code;typedef int (* QueryImageAttributesFuncPtr)( ScrnInfoPtr pScrn,
+ &f.indent;int image, short *width, short *height,
+ &f.indent;int *pitches, int *offsets)&e.code;
+ <quote><p>
+ This function is called to let the driver specify how data for
+ a particular &s.code;image&e.code; of size &s.code;width&e.code;
+ by &s.code;height&e.code; should be stored. Sometimes only
+ the size and corrected width and height are needed. In that
+ case &s.code;pitches&e.code; and &s.code;offsets&e.code; are
+ NULL. The size of the memory required for the image is returned
+ by this function. The &s.code;width&e.code; and
+ &s.code;height&e.code; of the requested image can be altered by
+ the driver to reflect format limitations (such as component
+ sampling periods that are larger than one). If
+ &s.code;pitches&e.code; and &s.code;offsets&e.code; are not NULL,
+ these will be arrays with as many elements in them as there
+ are planes in the &s.code;image&e.code; format. The driver
+ should specify the pitch (in bytes) of each scanline in the
+ particular plane as well as the offset to that plane (in bytes)
+ from the beginning of the image.
+
+ </quote>
+
+ </quote>
+
+The XF86VideoEncodingRec:
+<quote><p>
+<verb>
+typedef struct {
+ int id;
+ char *name;
+ unsigned short width, height;
+ XvRationalRec rate;
+} XF86VideoEncodingRec, *XF86VideoEncodingPtr;
+
+</verb>
+ The &s.code;XF86VideoEncodingRec&e.code; specifies what encodings
+ the adaptor can support. Most of this data is just informational
+ and for the client's benefit, and is what will be reported by
+ &s.code;XvQueryEncodings&e.code;. The &s.code;id&e.code; field is
+ expected to be a unique identifier to allow the client to request a
+ certain encoding via the &s.code;XV_ENCODING&e.code; attribute string.
+
+</quote>
+
+The XF86VideoFormatRec:
+
+<quote><p>
+<verb>
+typedef struct {
+ char depth;
+ short class;
+} XF86VideoFormatRec, *XF86VideoFormatPtr;
+</verb>
+
+ This specifies what visuals the video is viewable in.
+ &s.code;depth&e.code; is the depth of the visual (not bpp).
+ &s.code;class&e.code; is the visual class such as
+ &s.code;TrueColor&e.code;, &s.code;DirectColor&e.code; or
+ &s.code;PseudoColor&e.code;. Initialization of an adaptor will fail
+ if none of the visuals on that screen are supported.
+
+</quote>
+
+The XF86AttributeRec:
+
+<quote><p>
+<verb>
+typedef struct {
+ int flags;
+ int min_value;
+ int max_value;
+ char *name;
+} XF86AttributeListRec, *XF86AttributeListPtr;
+
+</verb>
+
+ Each adaptor may have an array of these advertising the attributes
+ for its ports. Currently defined flags are &s.code;XvGettable&e.code;
+ and &s.code;XvSettable&e.code; which may be OR'd together indicating that
+ attribute is ``gettable'' or ``settable'' by the client. The
+ &s.code;min&e.code; and &s.code;max&e.code; field specify the valid range
+ for the value. &s.code;Name&e.code; is a text string describing the
+ attribute by name.
+
+</quote>
+
+The XF86ImageRec:
+
+<quote><p>
+<verb>
+typedef struct {
+ int id;
+ int type;
+ int byte_order;
+ char guid[16];
+ int bits_per_pixel;
+ int format;
+ int num_planes;
+
+ /* for RGB formats */
+ int depth;
+ unsigned int red_mask;
+ unsigned int green_mask;
+ unsigned int blue_mask;
+
+ /* for YUV formats */
+ unsigned int y_sample_bits;
+ unsigned int u_sample_bits;
+ unsigned int v_sample_bits;
+ unsigned int horz_y_period;
+ unsigned int horz_u_period;
+ unsigned int horz_v_period;
+ unsigned int vert_y_period;
+ unsigned int vert_u_period;
+ unsigned int vert_v_period;
+ char component_order[32];
+ int scanline_order;
+} XF86ImageRec, *XF86ImagePtr;
+</verb>
+
+ XF86ImageRec describes how video source data is laid out in memory.
+ The fields are as follows:
+
+ &s.code;id&e.code;
+ <quote><p>
+ This is a unique descriptor for the format. It is often good to
+ set this value to the FOURCC for the format when applicable.
+ </quote>
+
+ &s.code;type&e.code;
+ <quote><p>
+ This is &s.code;XvRGB&e.code; or &s.code;XvYUV&e.code;.
+ </quote>
+
+ &s.code;byte_order&e.code;
+ <quote><p>
+ This is &s.code;LSBFirst&e.code; or &s.code;MSBFirst&e.code;.
+ </quote>
+
+ &s.code;guid&e.code;
+ <quote><p>
+ This is the Globally Unique IDentifier for the format. When
+ not applicable, all characters should be NULL.
+ </quote>
+
+ &s.code;bits_per_pixel&e.code;
+ <quote><p>
+ The number of bits taken up (but not necessarily used) by each
+ pixel. Note that for some planar formats which have fractional
+ bits per pixel (such as IF09) this number may be rounded _down_.
+ </quote>
+
+ &s.code;format&e.code;
+ <quote><p>
+ This is &s.code;XvPlanar&e.code; or &s.code;XvPacked&e.code;.
+ </quote>
+
+ &s.code;num_planes&e.code;
+ <quote><p>
+ The number of planes in planar formats. This should be set to
+ one for packed formats.
+ </quote>
+
+ &s.code;depth&e.code;
+ <quote><p>
+ The significant bits per pixel in RGB formats (analgous to the
+ depth of a pixmap format).
+ </quote>
+
+ &s.code;red_mask&e.code;
+ &s.code;green_mask&e.code;
+ &s.code;blue_mask&e.code;
+ <quote><p>
+ The red, green and blue bitmasks for packed RGB formats.
+ </quote>
+
+ &s.code;y_sample_bits&e.code;
+ &s.code;u_sample_bits&e.code;
+ &s.code;v_sample_bits&e.code;
+ <quote><p>
+ The y, u and v sample sizes (in bits).
+ </quote>
+
+ &s.code;horz_y_period&e.code;
+ &s.code;horz_u_period&e.code;
+ &s.code;horz_v_period&e.code;
+ <quote><p>
+ The y, u and v sampling periods in the horizontal direction.
+ </quote>
+
+ &s.code;vert_y_period&e.code;
+ &s.code;vert_u_period&e.code;
+ &s.code;vert_v_period&e.code;
+ <quote><p>
+ The y, u and v sampling periods in the vertical direction.
+ </quote>
+
+ &s.code;component_order&e.code;
+ <quote><p>
+ Uppercase ascii characters representing the order that
+ samples are stored within packed formats. For planar formats
+ this represents the ordering of the planes. Unused characters
+ in the 32 byte string should be set to NULL.
+ </quote>
+
+ &s.code;scanline_order&e.code;
+ <quote><p>
+ This is &s.code;XvTopToBottom&e.code; or &s.code;XvBottomToTop&e.code;.
+ </quote>
+
+ Since some formats (particular some planar YUV formats) may not
+be completely defined by the parameters above, the guid, when
+available, should provide the most accurate description of the
+format.
+
+</quote>
+
+<sect>The Loader
+<p>
+
+This section describes the interfaces to the module loader. The loader
+interfaces can be divided into two groups: those that are only available to
+the XFree86 common layer, and those that are also available to modules.
+
+<sect1>Loader Overview
+<p>
+
+The loader is capable of loading modules in a range of object formats,
+and knowledge of these formats is built in to the loader. Knowledge of
+new object formats can be added to the loader in a straightforward
+manner. This makes it possible to provide OS-independent modules (for
+a given CPU architecture type). In addition to this, the loader can
+load modules via the OS-provided &s.code;dlopen(3)&e.code; service where
+available. Such modules are not platform independent, and the semantics
+of &s.code;dlopen()&e.code; on most systems results in significant
+limitations in the use of modules of this type. Support for
+&s.code;dlopen()&e.code; modules in the loader is primarily for
+experimental and development purposes.
+
+Symbols exported by the loader (on behalf of the core X server) to
+modules are determined at compile time. Only those symbols explicitly
+exported are available to modules. All external symbols of loaded
+modules are exported to other modules, and to the core X server. The
+loader can be requested to check for unresolved symbols at any time,
+and the action to be taken for unresolved symbols can be controlled by
+the caller of the loader. Typically the caller identifies which symbols
+can safely remain unresolved and which cannot.
+
+NOTE: Now that ISO-C allows pointers to functions and pointers to data to
+have different internal representations, some of the following interfaces
+will need to be revisited.
+
+<sect1>Semi-private Loader Interface
+<p>
+
+The following is the semi-private loader interface that is available to the
+XFree86 common layer.
+
+ <quote><p>
+ &s.code;void LoaderInit(void)&e.code;
+ <quote><p>
+ The &s.code;LoaderInit()&e.code; function initialises the loader,
+ and it must be called once before calling any other loader functions.
+ This function initialises the tables of exported symbols, and anything
+ else that might need to be initialised.
+
+ </quote>
+
+ &s.code;void LoaderSetPath(const char *path)&e.code;
+ <quote><p>
+ The &s.code;LoaderSetPath()&e.code; function initialises a default
+ module search path. This must be called if calls to other functions
+ are to be made without explicitly specifying a module search path.
+ The search path &s.code;path&e.code; must be a string of one or more
+ comma separated absolute paths. Modules are expected to be located
+ below these paths, possibly in subdirectories of these paths.
+
+ </quote>
+
+ &s.code;pointer LoadModule(const char *module, const char *path,
+ &f.indent;const char **subdirlist, const char **patternlist,
+ &f.indent;pointer options, const XF86ModReqInfo * modreq,
+ &f.indent;int *errmaj, int *errmin)&e.code;
+ <quote><p>
+ The &s.code;LoadModule()&e.code; function loads the module called
+ &s.code;module&e.code;. The return value is a module handle, and
+ may be used in future calls to the loader that require a reference
+ to a loaded module. The module name &s.code;module&e.code; is
+ normally the module's canonical name, which doesn't contain any
+ directory path information, or any object/library file prefixes of
+ suffixes. Currently a full pathname and/or filename is also accepted.
+ This might change. The other parameters are:
+
+ &s.code;path&e.code;
+ <quote><p>
+ An optional comma-separated list of module search paths.
+ When &s.code;NULL&e.code;, the default search path is used.
+
+ </quote>
+
+ &s.code;subdirlist&e.code;
+ <quote><p>
+ An optional &s.code;NULL&e.code; terminated list of
+ subdirectories to search. When &s.code;NULL&e.code;,
+ the default built-in list is used (refer to
+ &s.code;stdSubdirs&e.code; in &s.code;loadmod.c&e.code;).
+ The default list is also substituted for entries in
+ &s.code;subdirlist&e.code; with the value
+ &s.code;DEFAULT_LIST&e.code;. This makes is possible
+ to augment the default list instead of replacing it.
+ Subdir elements must be relative, and must not contain
+ &s.code;".."&e.code;. If any violate this requirement,
+ the load fails.
+
+ </quote>
+
+ &s.code;patternlist&e.code;
+ <quote><p>
+ An optional &s.code;NULL&e.code; terminated list of
+ POSIX regular expressions used to connect module
+ filenames with canonical module names. Each regex
+ should contain exactly one subexpression that corresponds
+ to the canonical module name. When &s.code;NULL&e.code;,
+ the default built-in list is used (refer to
+ &s.code;stdPatterns&e.code; in
+ &s.code;loadmod.c&e.code;). The default list is also
+ substituted for entries in &s.code;patternlist&e.code;
+ with the value &s.code;DEFAULT_LIST&e.code;. This
+ makes it possible to augment the default list instead
+ of replacing it.
+
+ </quote>
+
+ &s.code;options&e.code;
+ <quote><p>
+ An optional parameter that is passed to the newly
+ loaded module's &s.code;SetupProc&e.code; function
+ (if it has one). This argument is normally a
+ &s.code;NULL&e.code; terminated list of
+ &s.code;Options&e.code;, and must be interpreted that
+ way by modules loaded directly by the XFree86 common
+ layer. However, it may be used for application-specific
+ parameter passing in other situations.
+
+ When loading ``external'' modules (modules that don't
+ have the standard entry point, for example a
+ special shared library) the options parameter can be
+ set to &s.code;EXTERN_MODULE&e.code; to tell the
+ loader not to reject the module when it doesn't find
+ the standard entry point.
+
+ </quote>
+
+ &s.code;modreq&e.code;
+ <quote><p>
+ An optional &s.code;XF86ModReqInfo*&e.code; containing
+ version/ABI/vendor information to requirements to
+ check the newly loaded module against. The main
+ purpose of this is to allow the loader to verify that
+ a module of the correct type/version before running
+ its &s.code;SetupProc&e.code; function.
+
+ The &s.code;XF86ModReqInfo&e.code; struct is defined
+ as follows:
+<verb>
+typedef struct {
+ CARD8 majorversion; /* MAJOR_UNSPEC */
+ CARD8 minorversion; /* MINOR_UNSPEC */
+ CARD16 patchlevel; /* PATCH_UNSPEC */
+ const char * abiclass; /* ABI_CLASS_NONE */
+ CARD32 abiversion; /* ABI_VERS_UNSPEC */
+ const char * moduleclass; /* MOD_CLASS_NONE */
+} XF86ModReqInfo;
+</verb>
+
+ The information here is compared against the equivalent
+ information in the module's
+ &s.code;XF86ModuleVersionInfo&e.code; record (which
+ is described below). The values in comments above
+ indicate ``don't care'' settings for each of the fields.
+ The comparisons made are as follows:
+
+ &s.code;majorversion&e.code;
+ <quote><p>
+ Must match the module's majorversion
+ exactly.
+
+ </quote>
+ &s.code;minorversion&e.code;
+ <quote><p>
+ The module's minor version must be
+ no less than this value. This
+ comparison is only made if
+ &s.code;majorversion&e.code; is
+ specified and matches.
+
+ </quote>
+ &s.code;patchlevel&e.code;
+ <quote><p>
+ The module's patchlevel must be no
+ less than this value. This comparison
+ is only made if
+ &s.code;minorversion&e.code; is
+ specified and matches.
+
+ </quote>
+ &s.code;abiclass&e.code;
+ <quote><p>
+ String must match the module's abiclass
+ string.
+
+ </quote>
+ &s.code;abiversion&e.code;
+ <quote><p>
+ Must be consistent with the module's
+ abiversion (major equal, minor no
+ older).
+
+ </quote>
+ &s.code;moduleclass&e.code;
+ <quote><p>
+ String must match the module's
+ moduleclass string.
+
+ </quote>
+
+ </quote>
+
+ &s.code;errmaj&e.code;
+ <quote><p>
+ An optional pointer to a variable holding the major
+ part or the error code. When provided,
+ &s.code;*errmaj&e.code; is filled in when
+ &s.code;LoadModule()&e.code; fails.
+
+ </quote>
+
+ &s.code;errmin&e.code;
+ <quote><p>
+ Like &s.code;errmaj&e.code;, but for the minor part
+ of the error code.
+
+ </quote>
+
+ </quote>
+
+ &s.code;void UnloadModule(pointer mod)&e.code;
+ <quote><p>
+ This function unloads the module referred to by the handle mod.
+ All child modules are also unloaded recursively. This function must
+ not be used to directly unload modules that are child modules (i.e.,
+ those that have been loaded with the &s.code;LoadSubModule()&e.code;
+ described below).
+
+ </quote>
+ </quote>
+
+<sect1>Module Requirements
+<p>
+
+Modules must provide information about themselves to the loader, and
+may optionally provide entry points for "setup" and "teardown" functions
+(those two functions are referred to here as &s.code;SetupProc&e.code;
+and &s.code;TearDownProc&e.code;).
+
+The module information is contained in the
+&s.code;XF86ModuleVersionInfo&e.code; struct, which is defined as follows:
+
+<quote><p><verb>
+typedef struct {
+ const char * modname; /* name of module, e.g. "foo" */
+ const char * vendor; /* vendor specific string */
+ CARD32 _modinfo1_; /* constant MODINFOSTRING1/2 to find */
+ CARD32 _modinfo2_; /* infoarea with a binary editor/sign tool */
+ CARD32 xf86version; /* contains XF86_VERSION_CURRENT */
+ CARD8 majorversion; /* module-specific major version */
+ CARD8 minorversion; /* module-specific minor version */
+ CARD16 patchlevel; /* module-specific patch level */
+ const char * abiclass; /* ABI class that the module uses */
+ CARD32 abiversion; /* ABI version */
+ const char * moduleclass; /* module class */
+ CARD32 checksum[4]; /* contains a digital signature of the */
+ /* version info structure */
+} XF86ModuleVersionInfo;
+</verb>
+
+The fields are used as follows:
+
+ &s.code;modname&e.code;
+ <quote><p>
+ The module's name. This field is currently only for
+ informational purposes, but the loader may be modified
+ in future to require it to match the module's canonical
+ name.
+
+ </quote>
+
+ &s.code;vendor&e.code;
+ <quote><p>
+ The module vendor. This field is for informational purposes
+ only.
+
+ </quote>
+
+ &s.code;_modinfo1_&e.code;
+ <quote><p>
+ This field holds the first part of a signature that can
+ be used to locate this structure in the binary. It should
+ always be initialised to &s.code;MODINFOSTRING1&e.code;.
+
+ </quote>
+
+ &s.code;_modinfo2_&e.code;
+ <quote><p>
+ This field holds the second part of a signature that can
+ be used to locate this structure in the binary. It should
+ always be initialised to &s.code;MODINFOSTRING2&e.code;.
+
+ </quote>
+
+ &s.code;xf86version&e.code;
+ <quote><p>
+ The XFree86 version against which the module was compiled.
+ This is mostly for informational/diagnostic purposes. It
+ should be initialised to &s.code;XF86_VERSION_CURRENT&e.code;, which is
+ defined in &s.code;xf86Version.h&e.code;.
+
+ </quote>
+
+ &s.code;majorversion&e.code;
+ <quote><p>
+ The module-specific major version. For modules where this
+ version is used for more than simply informational
+ purposes, the major version should only change (be
+ incremented) when ABI incompatibilities are introduced,
+ or ABI components are removed.
+
+ </quote>
+
+ &s.code;minorversion&e.code;
+ <quote><p>
+ The module-specific minor version. For modules where this
+ version is used for more than simply informational
+ purposes, the minor version should only change (be
+ incremented) when ABI additions are made in a backward
+ compatible way. It should be reset to zero when the major
+ version is increased.
+
+ </quote>
+
+ &s.code;patchlevel&e.code;
+ <quote><p>
+ The module-specific patch level. The patch level should
+ increase with new revisions of the module where there
+ are no ABI changes, and it should be reset to zero when
+ the minor version is increased.
+
+ </quote>
+
+ &s.code;abiclass&e.code;
+ <quote><p>
+ The ABI class that the module requires. The class is
+ specified as a string for easy extensibility. It should
+ indicate which (if any) of the X server's built-in ABI
+ classes that the module relies on, or a third-party ABI
+ if appropriate. Built-in ABI classes currently defined are:
+
+ <quote>
+ &s.code;ABI_CLASS_NONE&e.code;
+ <quote>no class</quote>
+ &s.code;ABI_CLASS_ANSIC&e.code;
+ <quote>only requires the ANSI C interfaces</quote>
+ &s.code;ABI_CLASS_VIDEODRV&e.code;
+ <quote>requires the video driver ABI</quote>
+ &s.code;ABI_CLASS_XINPUT&e.code;
+ <quote>requires the XInput driver ABI</quote>
+ &s.code;ABI_CLASS_EXTENSION&e.code;
+ <quote>requires the extension module ABI</quote>
+ &s.code;ABI_CLASS_FONT&e.code;
+ <quote>requires the font module ABI</quote>
+ </quote>
+
+ </quote>
+
+ &s.code;abiversion&e.code;
+ <quote><p>
+ The version of abiclass that the module requires. The
+ version consists of major and minor components. The
+ major version must match and the minor version must be
+ no newer than that provided by the server or parent
+ module. Version identifiers for the built-in classes
+ currently defined are:
+
+ <quote>
+ &s.code;ABI_ANSIC_VERSION&nl;
+ ABI_VIDEODRV_VERSION&nl;
+ ABI_XINPUT_VERSION&nl;
+ ABI_EXTENSION_VERSION&nl;
+ ABI_FONT_VERSION&e.code;
+ </quote>
+
+ </quote>
+
+ &s.code;moduleclass&e.code;
+ <quote><p>
+ This is similar to the abiclass field, except that it
+ defines the type of module rather than the ABI it
+ requires. For example, although all video drivers require
+ the video driver ABI, not all modules that require the
+ video driver ABI are video drivers. This distinction
+ can be made with the moduleclass. Currently pre-defined
+ module classes are:
+
+ <quote>
+ &s.code;MOD_CLASS_NONE&nl;
+ MOD_CLASS_VIDEODRV&nl;
+ MOD_CLASS_XINPUT&nl;
+ MOD_CLASS_FONT&nl;
+ MOD_CLASS_EXTENSION&e.code;
+ </quote>
+
+ </quote>
+
+ &s.code;checksum&e.code;
+ <quote><p>
+ Not currently used.
+
+ </quote>
+
+</quote>
+
+The module version information, and the optional &s.code;SetupProc&e.code;
+and &s.code;TearDownProc&e.code; entry points are found by the loader
+by locating a data object in the module called "modnameModuleData",
+where "modname" is the canonical name of the module. Modules must
+contain such a data object, and it must be declared with global scope,
+be compile-time initialised, and is of the following type:
+
+<quote>
+<verb>
+typedef struct {
+ XF86ModuleVersionInfo * vers;
+ ModuleSetupProc setup;
+ ModuleTearDownProc teardown;
+} XF86ModuleData;
+</verb>
+</quote>
+
+The vers parameter must be initialised to a pointer to a correctly
+initialised &s.code;XF86ModuleVersionInfo&e.code; struct. The other
+two parameter are optional, and should be initialised to
+&s.code;NULL&e.code; when not required. The other parameters are defined
+as
+
+ <quote><p>
+ &s.code;typedef pointer (*ModuleSetupProc)(pointer, pointer, int *, int *)&e.code;
+
+ &s.code;typedef void (*ModuleTearDownProc)(pointer)&e.code;
+
+
+ &s.code;pointer SetupProc(pointer module, pointer options,
+ &f.indent;int *errmaj, int *errmin)&e.code;
+ <quote><p>
+ When defined, this function is called by the loader after successfully
+ loading a module. module is a handle for the newly loaded module,
+ and maybe used by the &s.code;SetupProc&e.code; if it calls other
+ loader functions that require a reference to it. The remaining
+ arguments are those that were passed to the
+ &s.code;LoadModule()&e.code; (or &s.code;LoadSubModule()&e.code;),
+ and are described above. When the &s.code;SetupProc&e.code; is
+ successful it must return a non-&s.code;NULL&e.code; value. The
+ loader checks this, and if it is &s.code;NULL&e.code; it unloads
+ the module and reports the failure to the caller of
+ &s.code;LoadModule()&e.code;. If the &s.code;SetupProc&e.code;
+ does things that need to be undone when the module is unloaded,
+ it should define a &s.code;TearDownProc&e.code;, and return a
+ pointer that the &s.code;TearDownProc&e.code; can use to undo what
+ has been done.
+
+ When a module is loaded multiple times, the &s.code;SetupProc&e.code;
+ is called once for each time it is loaded.
+
+ </quote>
+
+ &s.code;void TearDownProc(pointer tearDownData)&e.code;
+ <quote><p>
+ When defined, this function is called when the loader unloads a
+ module. The &s.code;tearDownData&e.code; parameter is the return
+ value of the &s.code;SetupProc()&e.code; that was called when the
+ module was loaded. The purpose of this function is to clean up
+ before the module is unloaded (for example, by freeing allocated
+ resources).
+
+ </quote>
+ </quote>
+
+<sect1>Public Loader Interface
+<p>
+
+The following is the Loader interface that is available to any part of
+the server, and may also be used from within modules.
+
+ <quote><p>
+ &s.code;pointer LoadSubModule(pointer parent, const char *module,
+ &f.indent;const char **subdirlist, const char **patternlist,
+ &f.indent;pointer options, const XF86ModReqInfo * modreq,
+ &f.indent;int *errmaj, int *errmin)&e.code;
+ <quote><p>
+ This function is like the &s.code;LoadModule()&e.code; function
+ described above, except that the module loaded is registered as a
+ child of the calling module. The &s.code;parent&e.code; parameter
+ is the calling module's handle. Modules loaded with this function
+ are automatically unloaded when the parent module is unloaded. The
+ other difference is that the path parameter may not be specified.
+ The module search path used for modules loaded with this function
+ is the default search path as initialised with
+ &s.code;LoaderSetPath()&e.code;.
+
+ </quote>
+
+ &s.code;void UnloadSubModule(pointer module)&e.code;
+ <quote><p>
+ This function unloads the module with handle &s.code;module&e.code;.
+ If that module itself has children, they are also unloaded. It is
+ like &s.code;UnloadModule()&e.code;, except that it is safe to use
+ for unloading child modules.
+
+ </quote>
+
+ &s.code;pointer LoaderSymbol(const char *symbol)&e.code;
+ <quote><p>
+ This function returns the address of the symbol with name
+ &s.code;symbol&e.code;. This may be used to locate a module entry
+ point with a known name.
+
+ </quote>
+
+ &s.code;char **LoaderlistDirs(const char **subdirlist,
+ &f.indent;const char **patternlist)&e.code;
+ <quote><p>
+ This function returns a &s.code;NULL&e.code; terminated list of
+ canonical modules names for modules found in the default module
+ search path. The &s.code;subdirlist&e.code; and
+ &s.code;patternlist&e.code; parameters are as described above, and
+ can be used to control the locations and names that are searched.
+ If no modules are found, the return value is &s.code;NULL&e.code;.
+ The returned list should be freed by calling
+ &s.code;LoaderFreeDirList()&e.code; when it is no longer needed.
+
+ </quote>
+
+ &s.code;void LoaderFreeDirList(char **list)&e.code;
+ <quote><p>
+ This function frees a module list created by
+ &s.code;LoaderlistDirs()&e.code;.
+
+ </quote>
+
+ &s.code;void LoaderReqSymLists(const char **list0, ...)&e.code;
+ <quote><p>
+ This function allows the registration of required symbols with the
+ loader. It is normally used by a caller of
+ &s.code;LoadSubModule()&e.code;. If any symbols registered in this
+ way are found to be unresolved when
+ &s.code;LoaderCheckUnresolved()&e.code; is called then
+ &s.code;LoaderCheckUnresolved()&e.code; will report a failure.
+ The function takes one or more &s.code;NULL&e.code; terminated
+ lists of symbols. The end of the argument list is indicated by a
+ &s.code;NULL&e.code; argument.
+
+ </quote>
+
+ &s.code;void LoaderReqSymbols(const char *sym0, ...)&e.code;
+ <quote><p>
+ This function is like &s.code;LoaderReqSymLists()&e.code; except
+ that its arguments are symbols rather than lists of symbols. This
+ function is more convenient when single functions are to be registered,
+ especially when the single function might depend on runtime factors.
+ The end of the argument list is indicated by a &s.code;NULL&e.code;
+ argument.
+
+ </quote>
+
+ &s.code;void LoaderRefSymLists(const char **list0, ...)&e.code;
+ <quote><p>
+ This function allows the registration of possibly unresolved symbols
+ with the loader. When &s.code;LoaderCheckUnresolved()&e.code; is
+ run it won't generate warnings for symbols registered in this way
+ unless they were also registered as required symbols.
+ The function takes one or more &s.code;NULL&e.code; terminated
+ lists of symbols. The end of the argument list is indicated by a
+ &s.code;NULL&e.code; argument.
+
+ </quote>
+
+ &s.code;void LoaderRefSymbols(const char *sym0, ...)&e.code;
+ <quote><p>
+ This function is like &s.code;LoaderRefSymLists()&e.code; except
+ that its arguments are symbols rather than lists of symbols. This
+ function is more convenient when single functions are to be registered,
+ especially when the single function might depend on runtime factors.
+ The end of the argument list is indicated by a &s.code;NULL&e.code;
+ argument.
+
+ </quote>
+
+ &s.code;int LoaderCheckUnresolved(int delayflag)&e.code;
+ <quote><p>
+ This function checks for unresolved symbols. It generates warnings
+ for unresolved symbols that have not been registered with
+ &s.code;LoaderRefSymLists()&e.code;, and maps them to a dummy
+ function. This behaviour may change in future. If unresolved
+ symbols are found that have been registered with
+ &s.code;LoaderReqSymLists()&e.code; or
+ &s.code;LoaderReqSymbols()&e.code; then this function returns a
+ non-zero value. If none of these symbols are unresolved the return
+ value is zero, indicating success.
+
+ The &s.code;delayflag&e.code; parameter should normally be set to
+ &s.code;LD_RESOLV_IFDONE&e.code;.
+
+ </quote>
+
+ &s.code;LoaderErrorMsg(const char *name, const char *modname,
+ &f.indent;int errmaj, int errmin)&e.code;
+ <quote><p>
+ This function prints an error message that includes the text ``Failed
+ to load module'', the module name &s.code;modname&e.code;, a message
+ specific to the &s.code;errmaj&e.code; value, and the value if
+ &s.code;errmin&e.code;. If &s.code;name&e.code; is
+ non-&s.code;NULL&e.code;, it is printed as an identifying prefix
+ to the message (followed by a `:').
+
+ </quote>
+ </quote>
+
+<sect1>Special Registration Functions
+<p>
+
+The loader contains some functions for registering some classes of modules.
+These may be moved out of the loader at some point.
+
+ <quote><p>
+ &s.code;void LoadExtension(ExtensionModule *ext)&e.code;
+ <quote><p>
+ This registers the entry points for the extension identified by
+ &s.code;ext&e.code;. The &s.code;ExtensionModule&e.code; struct is
+ defined as:
+
+<quote>
+<verb>
+typedef struct {
+ InitExtension initFunc;
+ char * name;
+ Bool *disablePtr;
+ InitExtension setupFunc;
+} ExtensionModule;
+</verb>
+</quote>
+
+ </quote>
+
+ &s.code;void LoadFont(FontModule *font)&e.code;
+ <quote><p>
+ This registers the entry points for the font rasteriser module
+ identified by &s.code;font&e.code;. The &s.code;FontModule&e.code;
+ struct is defined as:
+
+<quote>
+<verb>
+typedef struct {
+ InitFont initFunc;
+ char * name;
+ pointer module;
+} FontModule;
+</verb>
+</quote>
+
+ </quote>
+ </quote>
+
+</sect>
+
+
+<sect>Helper Functions
+<p>
+
+This section describe ``helper'' functions that video driver
+might find useful. While video drivers are not required to use any of
+these to be considered ``compliant'', the use of appropriate helpers is
+strongly encouraged to improve the consistency of driver behaviour.
+
+<sect1>Functions for printing messages
+<p>
+
+ <quote><p>
+ &s.code;ErrorF(const char *format, ...)&e.code;
+ <quote><p>
+ This is the basic function for writing to the error log (typically
+ stderr and/or a log file). Video drivers should usually avoid
+ using this directly in favour of the more specialised functions
+ described below. This function is useful for printing messages
+ while debugging a driver.
+
+ </quote>
+
+ &s.code;FatalError(const char *format, ...)&e.code;
+ <quote><p>
+ This prints a message and causes the Xserver to abort. It should
+ rarely be used within a video driver, as most error conditions
+ should be flagged by the return values of the driver functions.
+ This allows the higher layers to decide how to proceed. In rare
+ cases, this can be used within a driver if a fatal unexpected
+ condition is found.
+
+ </quote>
+
+ &s.code;xf86ErrorF(const char *format, ...)&e.code;
+ <quote><p>
+ This is like &s.code;ErrorF()&e.code;, except that the message is
+ only printed when the Xserver's verbosity level is set to the
+ default (&s.code;1&e.code;) or higher. It means that the messages
+ are not printed when the server is started with the
+ &s.cmd;-quiet&e.cmd; flag. Typically this function would only be
+ used for continuing messages started with one of the more specialised
+ functions described below.
+
+ </quote>
+
+ &s.code;xf86ErrorFVerb(int verb, const char *format, ...)&e.code;
+ <quote><p>
+ Like &s.code;xf86ErrorF()&e.code;, except the minimum verbosity
+ level for which the message is to be printed is given explicitly.
+ Passing a &s.code;verb&e.code; value of zero means the message
+ is always printed. A value higher than &s.code;1&e.code; can be
+ used for information would normally not be needed, but which might
+ be useful when diagnosing problems.
+
+ </quote>
+
+ &s.code;xf86Msg(MessageType type, const char *format, ...)&e.code;
+ <quote><p>
+ This is like &s.code;xf86ErrorF()&e.code;, except that the message
+ is prefixed with a marker determined by the value of
+ &s.code;type&e.code;. The marker is used to indicate the type of
+ message (warning, error, probed value, config value, etc). Note
+ the &s.code;xf86Verbose&e.code; value is ignored for messages of
+ type &s.code;X_ERROR&e.code;.
+
+ The marker values are:
+
+ <quote>
+ &s.code;X_PROBED&e.code;
+ <quote>Value was probed.</quote>
+ &s.code;X_CONFIG&e.code;
+ <quote>Value was given in the config file.</quote>
+ &s.code;X_DEFAULT&e.code;
+ <quote>Value is a default.</quote>
+ &s.code;X_CMDLINE&e.code;
+ <quote>Value was given on the command line.</quote>
+ &s.code;X_NOTICE&e.code;
+ <quote>Notice.</quote>
+ &s.code;X_ERROR&e.code;
+ <quote>Error message.</quote>
+ &s.code;X_WARNING&e.code;
+ <quote>Warning message.</quote>
+ &s.code;X_INFO&e.code;
+ <quote>Informational message.</quote>
+ &s.code;X_NONE&e.code;
+ <quote>No prefix.</quote>
+ &s.code;X_NOT_IMPLEMENTED&e.code;
+ <quote>The message relates to functionality that is not yet
+ implemented.</quote>
+ </quote>
+
+
+ </quote>
+
+ &s.code;xf86MsgVerb(MessageType type, int verb, const char *format, ...)&e.code;
+ <quote><p>
+ Like &s.code;xf86Msg()&e.code;, but with the verbosity level given
+ explicitly.
+
+ </quote>
+
+ &s.code;xf86DrvMsg(int scrnIndex, MessageType type, const char *format, ...)&e.code;
+ <quote><p>
+ This is like &s.code;xf86Msg()&e.code; except that the driver's
+ name (the &s.code;name&e.code; field of the
+ &s.code;ScrnInfoRec&e.code;) followed by the
+ &s.code;scrnIndex&e.code; in parentheses is printed following the
+ prefix. This should be used by video drivers in most cases as it
+ clearly indicates which driver/screen the message is for. If
+ &s.code;scrnIndex&e.code; is negative, this function behaves
+ exactly like &s.code;xf86Msg()&e.code;.
+
+ NOTE: This function can only be used after the
+ &s.code;ScrnInfoRec&e.code; and its &s.code;name&e.code; field
+ have been allocated. Normally, this means that it can not be
+ used before the END of the &s.code;ChipProbe()&e.code; function.
+ Prior to that, use &s.code;xf86Msg()&e.code;, providing the
+ driver's name explicitly. No screen number can be supplied at
+ that point.
+
+ </quote>
+
+ &s.code;xf86DrvMsgVerb(int scrnIndex, MessageType type, int verb,
+ &f.indent;const char *format, ...)&e.code;
+ <quote><p>
+ Like &s.code;xf86DrvMsg()&e.code;, but with the verbosity level
+ given explicitly.
+
+ </quote>
+ </quote>
+
+
+<sect1>Functions for setting values based on command line and config file
+<p>
+
+ <quote><p>
+ &s.code;Bool xf86SetDepthBpp(ScrnInfoPtr scrp, int depth, int bpp,
+ &f.indent;int fbbpp, int depth24flags)&e.code;
+ <quote><p>
+ This function sets the &s.code;depth&e.code;, &s.code;pixmapBPP&e.code; and &s.code;bitsPerPixel&e.code; fields
+ of the &s.code;ScrnInfoRec&e.code;. It also determines the defaults for display-wide
+ attributes and pixmap formats the screen will support, and finds
+ the Display subsection that matches the depth/bpp. This function
+ should normally be called very early from the
+ &s.code;ChipPreInit()&e.code; function.
+
+ It requires that the &s.code;confScreen&e.code; field of the &s.code;ScrnInfoRec&e.code; be
+ initialised prior to calling it. This is done by the XFree86
+ common layer prior to calling &s.code;ChipPreInit()&e.code;.
+
+ The parameters passed are:
+
+ &s.code;depth&e.code;
+ <quote><p>
+ driver's preferred default depth if no other is given.
+ If zero, use the overall server default.
+
+ </quote>
+ &s.code;bpp&e.code;
+ <quote><p>
+ Same, but for the pixmap bpp.
+
+ </quote>
+ &s.code;fbbpp&e.code;
+ <quote><p>
+ Same, but for the framebuffer bpp.
+
+ </quote>
+ &s.code;depth24flags&e.code;
+ <quote><p>
+ Flags that indicate the level of 24/32bpp support
+ and whether conversion between different framebuffer
+ and pixmap formats is supported. The flags for this
+ argument are defined as follows, and multiple flags
+ may be ORed together:
+
+ &s.code;NoDepth24Support&e.code;
+ <quote>No depth 24 formats supported</quote>
+ &s.code;Support24bppFb&e.code;
+ <quote>24bpp framebuffer supported</quote>
+ &s.code;Support32bppFb&e.code;
+ <quote>32bpp framebuffer supported</quote>
+ &s.code;SupportConvert24to32&e.code;
+ <quote>Can convert 24bpp pixmap to 32bpp fb</quote>
+ &s.code;SupportConvert32to24&e.code;
+ <quote>Can convert 32bpp pixmap to 24bpp fb</quote>
+ &s.code;ForceConvert24to32&e.code;
+ <quote>Force 24bpp pixmap to 32bpp fb conversion</quote>
+ &s.code;ForceConvert32to24&e.code;
+ <quote>Force 32bpp pixmap to 24bpp fb conversion</quote>
+
+ </quote>
+
+ It uses the command line, config file, and default values in the
+ correct order of precedence to determine the depth and bpp values.
+ It is up to the driver to check the results to see that it supports
+ them. If not the &s.code;ChipPreInit()&e.code; function should
+ return &s.code;FALSE&e.code;.
+
+ If only one of depth/bpp is given, the other is set to a reasonable
+ (and consistent) default.
+
+ If a driver finds that the initial &s.code;depth24flags&e.code;
+ it uses later results in a fb format that requires more video
+ memory than is available it may call this function a second time
+ with a different &s.code;depth24flags&e.code; setting.
+
+ On success, the return value is &s.code;TRUE&e.code;. On failure
+ it prints an error message and returns &s.code;FALSE&e.code;.
+
+ The following fields of the &s.code;ScrnInfoRec&e.code; are
+ initialised by this function:
+
+ <quote>
+ &s.code;depth&e.code;, &s.code;bitsPerPixel&e.code;,
+ &s.code;display&e.code;, &s.code;imageByteOrder&e.code;,
+ &s.code;bitmapScanlinePad&e.code;,
+ &s.code;bitmapScanlineUnit&e.code;, &s.code;bitmapBitOrder&e.code;,
+ &s.code;numFormats&e.code;, &s.code;formats&e.code;,
+ &s.code;fbFormat&e.code;.
+ </quote>
+
+ </quote>
+
+ &s.code;void xf86PrintDepthBpp(scrnInfoPtr scrp)&e.code;
+ <quote><p>
+ This function can be used to print out the depth and bpp settings.
+ It should be called after the final call to
+ &s.code;xf86SetDepthBpp()&e.code;.
+
+ </quote>
+
+ &s.code;Bool xf86SetWeight(ScrnInfoPtr scrp, rgb weight, rgb mask)&e.code;
+ <quote><p>
+ This function sets the &s.code;weight&e.code;, &s.code;mask&e.code;,
+ &s.code;offset&e.code; and &s.code;rgbBits&e.code; fields of the
+ &s.code;ScrnInfoRec&e.code;. It would normally be called fairly
+ early in the &s.code;ChipPreInit()&e.code; function for
+ depths&nbsp;>&nbsp;8bpp.
+
+ It requires that the &s.code;depth&e.code; and
+ &s.code;display&e.code; fields of the &s.code;ScrnInfoRec&e.code;
+ be initialised prior to calling it.
+
+ The parameters passed are:
+
+ &s.code;weight&e.code;
+ <quote><p>
+ driver's preferred default weight if no other is given.
+ If zero, use the overall server default.
+
+ </quote>
+
+ &s.code;mask&e.code;
+ <quote><p>
+ Same, but for mask.
+
+ </quote>
+
+ It uses the command line, config file, and default values in the
+ correct order of precedence to determine the weight value. It
+ derives the mask and offset values from the weight and the defaults.
+ It is up to the driver to check the results to see that it supports
+ them. If not the &s.code;ChipPreInit()&e.code; function should
+ return &s.code;FALSE&e.code;.
+
+ On success, this function prints a message showing the weight
+ values selected, and returns &s.code;TRUE&e.code;.
+
+ On failure it prints an error message and returns &s.code;FALSE&e.code;.
+
+ The following fields of the &s.code;ScrnInfoRec&e.code; are
+ initialised by this function:
+
+ <quote>
+ &s.code;weight&e.code;, &s.code;mask&e.code;, &s.code;offset&e.code;.
+ </quote>
+
+ </quote>
+
+ &s.code;Bool xf86SetDefaultVisual(ScrnInfoPtr scrp, int visual)&e.code;
+ <quote><p>
+ This function sets the &s.code;defaultVisual&e.code; field of the
+ &s.code;ScrnInfoRec&e.code;. It would normally be called fairly
+ early from the &s.code;ChipPreInit()&e.code; function.
+
+ It requires that the &s.code;depth&e.code; and
+ &s.code;display&e.code; fields of the &s.code;ScrnInfoRec&e.code;
+ be initialised prior to calling it.
+
+ The parameters passed are:
+
+ &s.code;visual&e.code;
+ <quote><p>
+ driver's preferred default visual if no other is given.
+ If &s.code;-1&e.code;, use the overall server default.
+
+ </quote>
+
+ It uses the command line, config file, and default values in the
+ correct order of precedence to determine the default visual value.
+ It is up to the driver to check the result to see that it supports
+ it. If not the &s.code;ChipPreInit()&e.code; function should
+ return &s.code;FALSE&e.code;.
+
+ On success, this function prints a message showing the default visual
+ selected, and returns &s.code;TRUE&e.code;.
+
+ On failure it prints an error message and returns &s.code;FALSE&e.code;.
+
+ </quote>
+
+ &s.code;Bool xf86SetGamma(ScrnInfoPtr scrp, Gamma gamma)&e.code;
+ <quote><p>
+ This function sets the &s.code;gamma&e.code; field of the
+ &s.code;ScrnInfoRec&e.code;. It would normally be called fairly
+ early from the &s.code;ChipPreInit()&e.code; function in cases
+ where the driver supports gamma correction.
+
+ It requires that the &s.code;monitor&e.code; field of the
+ &s.code;ScrnInfoRec&e.code; be initialised prior to calling it.
+
+ The parameters passed are:
+
+ &s.code;gamma&e.code;
+ <quote><p>
+ driver's preferred default gamma if no other is given.
+ If zero (&s.code;< 0.01&e.code;), use the overall server
+ default.
+
+ </quote>
+
+ It uses the command line, config file, and default values in the
+ correct order of precedence to determine the gamma value. It is
+ up to the driver to check the results to see that it supports
+ them. If not the &s.code;ChipPreInit()&e.code; function should
+ return &s.code;FALSE&e.code;.
+
+ On success, this function prints a message showing the gamma
+ value selected, and returns &s.code;TRUE&e.code;.
+
+ On failure it prints an error message and returns &s.code;FALSE&e.code;.
+
+ </quote>
+
+ &s.code;void xf86SetDpi(ScrnInfoPtr pScrn, int x, int y)&e.code;
+ <quote><p>
+ This function sets the &s.code;xDpi&e.code; and &s.code;yDpi&e.code;
+ fields of the &s.code;ScrnInfoRec&e.code;. The driver can specify
+ preferred defaults by setting &s.code;x&e.code; and &s.code;y&e.code;
+ to non-zero values. The &s.cmd;-dpi&e.cmd; command line option
+ overrides all other settings. Otherwise, if the
+ &s.key;DisplaySize&e.key; entry is present in the screen's &k.monitor;
+ config file section, it is used together with the virtual size to
+ calculate the dpi values. This function should be called after
+ all the mode resolution has been done.
+
+ </quote>
+
+ &s.code;void xf86SetBlackWhitePixels(ScrnInfoPtr pScrn)&e.code;
+ <quote><p>
+ This functions sets the &s.code;blackPixel&e.code; and
+ &s.code;whitePixel&e.code; fields of the &s.code;ScrnInfoRec&e.code;
+ according to whether or not the &s.cmd;-flipPixels&e.cmd; command
+ line options is present.
+
+ </quote>
+
+ &s.code;const char *xf86GetVisualName(int visual)&e.code;
+ <quote><p>
+ Returns a printable string with the visual name matching the
+ numerical visual class provided. If the value is outside the
+ range of valid visual classes, &s.code;NULL&e.code; is returned.
+
+ </quote>
+ </quote>
+
+
+<sect1>Primary Mode functions
+<p>
+
+The primary mode helper functions are those which would normally be
+used by a driver, unless it has unusual requirements which cannot
+be catered for the by the helpers.
+
+ <quote><p>
+ &s.code;int xf86ValidateModes(ScrnInfoPtr scrp, DisplayModePtr availModes,
+ &f.indent;char **modeNames, ClockRangePtr clockRanges,
+ &f.indent;int *linePitches, int minPitch, int maxPitch,
+ &f.indent;int pitchInc, int minHeight, int maxHeight,
+ &f.indent;int virtualX, int virtualY,
+ &f.indent;unsigned long apertureSize,
+ &f.indent;LookupModeFlags strategy)&e.code;
+ <quote><p>
+ This function basically selects the set of modes to use based on
+ those available and the various constraints. It also sets some
+ other related parameters. It is normally called near the end of
+ the &s.code;ChipPreInit()&e.code; function.
+
+ The parameters passed to the function are:
+
+ &s.code;availModes&e.code;
+ <quote><p>
+ List of modes available for the monitor.
+
+ </quote>
+ &s.code;modeNames&e.code;
+ <quote><p>
+ List of mode names that the screen is requesting.
+
+ </quote>
+ &s.code;clockRanges&e.code;
+ <quote><p>
+ A list of clock ranges allowed by the driver. Each
+ range includes whether interlaced or multiscan modes
+ are supported for that range. See below for more on
+ &s.code;clockRanges&e.code;.
+
+ </quote>
+ &s.code;linePitches&e.code;
+ <quote><p>
+ List of line pitches supported by the driver.
+ This is optional and should be &s.code;NULL&e.code; when
+ not used.
+
+ </quote>
+ &s.code;minPitch&e.code;
+ <quote><p>
+ Minimum line pitch supported by the driver. This must
+ be supplied when &s.code;linePitches&e.code; is
+ &s.code;NULL&e.code;, and is ignored otherwise.
+
+ </quote>
+ &s.code;maxPitch&e.code;
+ <quote><p>
+ Maximum line pitch supported by the driver. This is
+ required when &s.code;minPitch&e.code; is required.
+
+ </quote>
+ &s.code;pitchInc&e.code;
+ <quote><p>
+ Granularity of horizontal pitch values as supported by
+ the chipset. This is expressed in bits. This must be
+ supplied.
+
+ </quote>
+ &s.code;minHeight&e.code;
+ <quote><p>
+ minimum virtual height allowed. If zero, no limit is
+ imposed.
+
+ </quote>
+ &s.code;maxHeight&e.code;
+ <quote><p>
+ maximum virtual height allowed. If zero, no limit is
+ imposed.
+
+ </quote>
+ &s.code;virtualX&e.code;
+ <quote><p>
+ If greater than zero, this is the virtual width value
+ that will be used. Otherwise, the virtual width is
+ chosen to be the smallest that can accommodate the modes
+ selected.
+
+ </quote>
+ &s.code;virtualY&e.code;
+ <quote><p>
+ If greater than zero, this is the virtual height value
+ that will be used. Otherwise, the virtual height is
+ chosen to be the smallest that can accommodate the modes
+ selected.
+
+ </quote>
+ &s.code;apertureSize&e.code;
+ <quote><p>
+ The size (in bytes) of the aperture used to access video
+ memory.
+
+ </quote>
+ &s.code;strategy&e.code;
+ <quote><p>
+ The strategy to use when choosing from multiple modes
+ with the same name. The options are:
+
+ &s.code;LOOKUP_DEFAULT&e.code;
+ <quote>???</quote>
+ &s.code;LOOKUP_BEST_REFRESH&e.code;
+ <quote>mode with best refresh rate</quote>
+ &s.code;LOOKUP_CLOSEST_CLOCK&e.code;
+ <quote>mode with closest matching clock</quote>
+ &s.code;LOOKUP_LIST_ORDER&e.code;
+ <quote>first usable mode in list</quote>
+
+ The following options can also be combined (OR'ed) with
+ one of the above:
+
+ &s.code;LOOKUP_CLKDIV2&e.code;
+ <quote>Allow halved clocks</quote>
+ &s.code;LOOKUP_OPTIONAL_TOLERANCES&e.code;
+ <quote>Allow missing horizontal sync and/or vertical refresh
+ ranges in the xorg.conf Monitor section</quote>
+
+ &s.code;LOOKUP_OPTIONAL_TOLERANCES&e.code; should only be
+ specified when the driver can ensure all modes it generates
+ can sync on, or at least not damage, the monitor or digital
+ flat panel. Horizontal sync and/or vertical refresh ranges
+ specified by the user will still be honoured (and acted upon).
+
+ </quote>
+
+ This function requires that the following fields of the
+ &s.code;ScrnInfoRec&e.code; are initialised prior to calling it:
+
+ &s.code;clock[]&e.code;
+ <quote>List of discrete clocks (when non-programmable)</quote>
+ &s.code;numClocks&e.code;
+ <quote>Number of discrete clocks (when non-programmable)</quote>
+ &s.code;progClock&e.code;
+ <quote>Whether the clock is programmable or not</quote>
+ &s.code;monitor&e.code;
+ <quote>Pointer to the applicable xorg.conf monitor section</quote>
+ &s.code;fdFormat&e.code;
+ <quote>Format of the screen buffer</quote>
+ &s.code;videoRam&e.code;
+ <quote>total video memory size (in bytes)</quote>
+ &s.code;maxHValue&e.code;
+ <quote>Maximum horizontal timing value allowed</quote>
+ &s.code;maxVValue&e.code;
+ <quote>Maximum vertical timing value allowed</quote>
+ &s.code;xInc&e.code;
+ <quote>Horizontal timing increment in pixels (defaults to 8)</quote>
+
+ This function fills in the following &s.code;ScrnInfoRec&e.code;
+ fields:
+
+ &s.code;modePool&e.code;
+ <quote><p>
+ A subset of the modes available to the monitor which
+ are compatible with the driver.
+
+ </quote>
+ &s.code;modes&e.code;
+ <quote><p>
+ One mode entry for each of the requested modes, with
+ the status field of each filled in to indicate if
+ the mode has been accepted or not. This list of
+ modes is a circular list.
+
+ </quote>
+ &s.code;virtualX&e.code;
+ <quote><p>
+ The resulting virtual width.
+
+ </quote>
+ &s.code;virtualY&e.code;
+ <quote><p>
+ The resulting virtual height.
+
+ </quote>
+ &s.code;displayWidth&e.code;
+ <quote><p>
+ The resulting line pitch.
+
+ </quote>
+ &s.code;virtualFrom&e.code;
+ <quote><p>
+ Where the virtual size was determined from.
+
+ </quote>
+
+ The first stage of this function checks that the
+ &s.code;virtualX&e.code; and &s.code;virtualY&e.code; values
+ supplied (if greater than zero) are consistent with the line pitch
+ and &s.code;maxHeight&e.code; limitations. If not, an error
+ message is printed, and the return value is &s.code;-1&e.code;.
+
+ The second stage sets up the mode pool, eliminating immediately
+ any modes that exceed the driver's line pitch limits, and also
+ the virtual width and height limits (if greater than zero). For
+ each mode removed an informational message is printed at verbosity
+ level &s.code;2&e.code;. If the mode pool ends up being empty,
+ a warning message is printed, and the return value is
+ &s.code;0&e.code;.
+
+ The final stage is to lookup each mode name, and fill in the remaining
+ parameters. If an error condition is encountered, a message is
+ printed, and the return value is &s.code;-1&e.code;. Otherwise,
+ the return value is the number of valid modes found
+ (&s.code;0&e.code; if none are found).
+
+ Even if the supplied mode names include duplicates, no two names will
+ ever match the same mode. Furthermore, if the supplied mode names do not
+ yield a valid mode (including the case where no names are passed at all),
+ the function will continue looking through the mode pool until it finds
+ a mode that survives all checks, or until the mode pool is exhausted.
+
+ A message is only printed by this function when a fundamental
+ problem is found. It is intended that this function may be called
+ more than once if there is more than one set of constraints that
+ the driver can work within.
+
+ If this function returns &s.code;-1&e.code;, the
+ &s.code;ChipPreInit()&e.code; function should return
+ &s.code;FALSE&e.code;.
+
+ &s.code;clockRanges&e.code; is a linked list of clock ranges
+ allowed by the driver. If a mode doesn't fit in any of the defined
+ &s.code;clockRanges&e.code;, it is rejected. The first
+ &s.code;clockRange&e.code; that matches all requirements is used.
+ This structure needs to be initialized to NULL when allocated.
+
+ &s.code;clockRanges&e.code; contains the following fields:
+
+ &s.code;minClock&nl;
+ maxClock&e.code;
+ <quote><p>
+ The lower and upper mode clock bounds for which the rest
+ of the &s.code;clockRange&e.code; parameters apply.
+ Since these are the mode clocks, they are not scaled
+ with the &s.code;ClockMulFactor&e.code; and
+ &s.code;ClockDivFactor&e.code;. It is up to the driver
+ to adjust these values if they depend on the clock
+ scaling factors.
+
+ </quote>
+ &s.code;clockIndex&e.code;
+ <quote><p>
+ (not used yet) &s.code;-1&e.code; for programmable clocks
+
+ </quote>
+ &s.code;interlaceAllowed&e.code;
+ <quote><p>
+ &s.code;TRUE&e.code; if interlacing is allowed for this
+ range
+
+ </quote>
+ &s.code;doubleScanAllowed&e.code;
+ <quote><p>
+ &s.code;TRUE&e.code; if doublescan or multiscan is allowed
+ for this range
+
+ </quote>
+ &s.code;ClockMulFactor&nl;
+ ClockDivFactor&e.code;
+ <quote><p>
+ Scaling factors that are applied to the mode clocks ONLY
+ before selecting a clock index (when there is no
+ programmable clock) or a &s.code;SynthClock&e.code;
+ value. This is useful for drivers that support pixel
+ multiplexing or that need to scale the clocks because
+ of hardware restrictions (like sending 24bpp data to an
+ 8 bit RAMDAC using a tripled clock).
+
+ Note that these parameters describe what must be done
+ to the mode clock to achieve the data transport clock
+ between graphics controller and RAMDAC. For example
+ for &s.code;2:1&e.code; pixel multiplexing, two pixels
+ are sent to the RAMDAC on each clock. This allows the
+ RAMDAC clock to be half of the actual pixel clock.
+ Hence, &s.code;ClockMulFactor=1&e.code; and
+ &s.code;ClockDivFactor=2&e.code;. This means that the
+ clock used for clock selection (ie, determining the
+ correct clock index from the list of discrete clocks)
+ or for the &s.code;SynthClock&e.code; field in case of
+ a programmable clock is: (&s.code;mode-&gt;Clock *
+ ClockMulFactor) / ClockDivFactor&e.code;.
+
+ </quote>
+ &s.code;PrivFlags&e.code;
+ <quote><p>
+ This field is copied into the
+ &s.code;mode-&gt;PrivFlags&e.code; field when this
+ &s.code;clockRange&e.code; is selected by
+ &s.code;xf86ValidateModes()&e.code;. It allows the
+ driver to find out what clock range was selected, so it
+ knows it needs to set up pixel multiplexing or any other
+ range-dependent feature. This field is purely
+ driver-defined: it may contain flag bits, an index or
+ anything else (as long as it is an &s.code;INT&e.code;).
+ </quote>
+
+ Note that the &s.code;mode-&gt;SynthClock&e.code; field is always
+ filled in by &s.code;xf86ValidateModes()&e.code;: it will contain
+ the ``data transport clock'', which is the clock that will have
+ to be programmed in the chip when it has a programmable clock, or
+ the clock that will be picked from the clocks list when it is not
+ a programmable one. Thus:
+
+ &s.code;mode-&gt;SynthClock =
+ &f.indent;(mode-&gt;Clock * ClockMulFactor) / ClockDivFactor&e.code;
+
+ </quote>
+
+ &s.code;void xf86PruneDriverModes(ScrnInfoPtr scrp)&e.code;
+ <quote><p>
+ This function deletes modes in the modes field of the
+ &s.code;ScrnInfoRec&e.code; that have been marked as invalid.
+ This is normally run after having run
+ &s.code;xf86ValidateModes()&e.code; for the last time. For each
+ mode that is deleted, a warning message is printed out indicating
+ the reason for it being deleted.
+
+ </quote>
+
+ &s.code;void xf86SetCrtcForModes(ScrnInfoPtr scrp, int adjustFlags)&e.code;
+ <quote><p>
+ This function fills in the &s.code;Crtc*&e.code; fields for all
+ the modes in the &s.code;modes&e.code; field of the
+ &s.code;ScrnInfoRec&e.code;. The &s.code;adjustFlags&e.code;
+ parameter determines how the vertical CRTC values are scaled for
+ interlaced modes. They are halved if it is
+ &s.code;INTERLACE_HALVE_V&e.code;. The vertical CRTC values are
+ doubled for doublescan modes, and are further multiplied by the
+ &s.code;VScan&e.code; value.
+
+ This function is normally called after calling
+ &s.code;xf86PruneDriverModes()&e.code;.
+
+ </quote>
+
+ &s.code;void xf86PrintModes(ScrnInfoPtr scrp)&e.code;
+ <quote><p>
+ This function prints out the virtual size setting, and the line
+ pitch being used. It also prints out two lines for each mode being
+ used. The first line includes the mode's pixel clock, horizontal sync
+ rate, refresh rate, and whether it is interlaced, doublescanned and/or
+ multi-scanned. The second line is the mode's Modeline.
+
+ This function is normally called after calling
+ &s.code;xf86SetCrtcForModes()&e.code;.
+
+ </quote>
+ </quote>
+
+
+<sect1>Secondary Mode functions
+<p>
+
+The secondary mode helper functions are functions which are normally
+used by the primary mode helper functions, and which are not normally
+called directly by a driver. If a driver has unusual requirements
+and needs to do its own mode validation, it might be able to make
+use of some of these secondary mode helper functions.
+
+ <quote><p>
+ &s.code;int xf86GetNearestClock(ScrnInfoPtr scrp, int freq, Bool allowDiv2,
+ &f.indent;int *divider)&e.code;
+ <quote><p>
+ This function returns the index of the closest clock to the
+ frequency &s.code;freq&e.code; given (in kHz). It assumes that
+ the number of clocks is greater than zero. It requires that the
+ &s.code;numClocks&e.code; and &s.code;clock&e.code; fields of the
+ &s.code;ScrnInfoRec&e.code; are initialised. The
+ &s.code;allowDiv2&e.code; field determines if the clocks can be
+ halved. The &s.code;*divider&e.code; return value indicates
+ whether clock division is used when determining the clock returned.
+
+ This function is only for non-programmable clocks.
+
+ </quote>
+
+ &s.code;const char *xf86ModeStatusToString(ModeStatus status)&e.code;
+ <quote><p>
+ This function converts the &s.code;status&e.code; value to a
+ descriptive printable string.
+
+ </quote>
+
+ &s.code;ModeStatus xf86LookupMode(ScrnInfoPtr scrp, DisplayModePtr modep,
+ &f.indent;ClockRangePtr clockRanges, LookupModeFlags strategy)&e.code;
+ <quote><p>
+ This function takes a pointer to a mode with the name filled in,
+ and looks for a mode in the &s.code;modePool&e.code; list which
+ matches. The parameters of the matching mode are filled in to
+ &s.code;*modep&e.code;. The &s.code;clockRanges&e.code; and
+ &s.code;strategy&e.code; parameters are as for the
+ &s.code;xf86ValidateModes()&e.code; function above.
+
+ This function requires the &s.code;modePool&e.code;,
+ &s.code;clock[]&e.code;, &s.code;numClocks&e.code; and
+ &s.code;progClock&e.code; fields of the &s.code;ScrnInfoRec&e.code;
+ to be initialised before being called.
+
+ The return value is &s.code;MODE_OK&e.code; if a mode was found.
+ Otherwise it indicates why a matching mode could not be found.
+
+ </quote>
+
+ &s.code;ModeStatus xf86InitialCheckModeForDriver(ScrnInfoPtr scrp,
+ &f.indent;DisplayModePtr mode, ClockRangePtr clockRanges,
+ &f.indent;LookupModeFlags strategy, int maxPitch,
+ &f.indent;int virtualX, int virtualY)&e.code;
+ <quote><p>
+ This function checks the passed mode against some basic driver
+ constraints. Apart from the ones passed explicitly, the
+ &s.code;maxHValue&e.code; and &s.code;maxVValue&e.code; fields of
+ the &s.code;ScrnInfoRec&e.code; are also used. If the
+ &s.code;ValidMode&e.code; field of the &s.code;ScrnInfoRec&e.code;
+ is set, that function is also called to check the mode. Next, the
+ mode is checked against the monitor's constraints.
+
+ If the mode is consistent with all constraints, the return value
+ is &s.code;MODE_OK&e.code;. Otherwise the return value indicates
+ which constraint wasn't met.
+
+ </quote>
+
+ &s.code;void xf86DeleteMode(DisplayModePtr *modeList, DisplayModePtr mode)&e.code;
+ <quote><p>
+ This function deletes the &s.code;mode&e.code; given from the
+ &s.code;modeList&e.code;. It never prints any messages, so it is
+ up to the caller to print a message if required.
+
+ </quote>
+ </quote>
+
+<sect1>Functions for handling strings and tokens
+<p>
+
+ Tables associating strings and numerical tokens combined with the
+ following functions provide a compact way of handling strings from
+ the config file, and for converting tokens into printable strings.
+ The table data structure is:
+
+<quote><verb>
+typedef struct {
+ int token;
+ const char * name;
+} SymTabRec, *SymTabPtr;
+</verb></quote>
+
+ A table is an initialised array of &s.code;SymTabRec&e.code;. The
+ tokens must be non-negative integers. Multiple names may be mapped
+ to a single token. The table is terminated with an element with a
+ &s.code;token&e.code; value of &s.code;-1&e.code; and
+ &s.code;NULL&e.code; for the &s.code;name&e.code;.
+
+
+ <quote><p>
+ &s.code;const char *xf86TokenToString(SymTabPtr table, int token)&e.code;
+ <quote><p>
+ This function returns the first string in &s.code;table&e.code;
+ that matches &s.code;token&e.code;. If no match is found,
+ &s.code;NULL&e.code; is returned (NOTE, older versions of this
+ function would return the string "unknown" when no match is found).
+
+ </quote>
+
+ &s.code;int xf86StringToToken(SymTabPtr table, const char *string)&e.code;
+ <quote><p>
+ This function returns the first token in &s.code;table&e.code;
+ that matches &s.code;string&e.code;. The
+ &s.code;xf86NameCmp()&e.code; function is used to determine the
+ match. If no match is found, &s.code;-1&e.code; is returned.
+
+ </quote>
+ </quote>
+
+
+<sect1>Functions for finding which config file entries to use
+<p>
+
+ These functions can be used to select the appropriate config file
+ entries that match the detected hardware. They are described above
+ in the <ref id="probe" name="Probe"> and
+ <ref id="avail" name="Available Functions"> sections.
+
+
+<sect1>Probing discrete clocks on old hardware
+<p>
+
+ The &s.code;xf86GetClocks()&e.code; function may be used to assist
+ in finding the discrete pixel clock values on older hardware.
+
+
+ <quote><p>
+ &s.code;void xf86GetClocks(ScrnInfoPtr pScrn, int num,
+ &f.indent;Bool (*ClockFunc)(ScrnInfoPtr, int),
+ &f.indent;void (*ProtectRegs)(ScrnInfoPtr, Bool),
+ &f.indent;void (*BlankScreen)(ScrnInfoPtr, Bool),
+ &f.indent;int vertsyncreg, int maskval, int knownclkindex,
+ &f.indent;int knownclkvalue)&e.code;
+ <quote><p>
+ This function uses a comparative sampling method to measure the
+ discrete pixel clock values. The number of discrete clocks to
+ measure is given by &s.code;num&e.code;. &s.code;clockFunc&e.code;
+ is a function that selects the &s.code;n&e.code;'th clock. It
+ should also save or restore any state affected by programming the
+ clocks when the index passed is &s.code;CLK_REG_SAVE&e.code; or
+ &s.code;CLK_REG_RESTORE&e.code;. &s.code;ProtectRegs&e.code; is
+ a function that does whatever is required to protect the hardware
+ state while selecting a new clock. &s.code;BlankScreen&e.code;
+ is a function that blanks the screen. &s.code;vertsyncreg&e.code;
+ and &s.code;maskval&e.code; are the register and bitmask to
+ check for the presence of vertical sync pulses.
+ &s.code;knownclkindex&e.code; and &s.code;knownclkvalue&e.code;
+ are the index and value of a known clock. These are the known
+ references on which the comparative measurements are based. The
+ number of clocks probed is set in &s.code;pScrn-&gt;numClocks&e.code;,
+ and the probed clocks are set in the &s.code;pScrn-&gt;clock[]&e.code;
+ array. All of the clock values are in units of kHz.
+
+ </quote>
+
+ &s.code;void xf86ShowClocks(ScrnInfoPtr scrp, MessageType from)&e.code;
+ <quote><p>
+ Print out the pixel clocks &s.code;scrp-&gt;clock[]&e.code;.
+ &s.code;from&e.code; indicates whether the clocks were probed
+ or from the config file.
+
+ </quote>
+ </quote>
+
+<sect1>Other helper functions
+<p>
+ <quote><p>
+ &s.code;Bool xf86IsUnblank(int mode)&e.code;
+ <quote><p>
+ Returns &s.code;TRUE&e.code; when the screen saver mode specified
+ by &s.code;mode&e.code; requires the screen be unblanked,
+ and &s.code;FALSE&e.code; otherwise. The screen saver modes that
+ require blanking are &s.code;SCREEN_SAVER_ON&e.code; and
+ &s.code;SCREEN_SAVER_CYCLE&e.code;, and the screen saver modes that
+ require unblanking are &s.code;SCREEN_SAVER_OFF&e.code; and
+ &s.code;SCREEN_SAVER_FORCER&e.code;. Drivers may call this helper
+ from their &s.code;SaveScreen()&e.code; function to interpret the
+ screen saver modes.
+
+ </quote>
+ </quote>
+
+<sect>The vgahw module
+<p>
+
+The vgahw modules provides an interface for saving, restoring and
+programming the standard VGA registers, and for handling VGA colourmaps.
+
+<sect1>Data Structures
+<p>
+
+ The public data structures used by the vgahw module are
+ &s.code;vgaRegRec&e.code; and &s.code;vgaHWRec&e.code;. They are
+ defined in &s.code;vgaHW.h.&e.code;
+
+
+<sect1>General vgahw Functions
+<p>
+
+ <quote><p>
+ &s.code;Bool vgaHWGetHWRec(ScrnInfoPtr pScrn)&e.code;
+ <quote><p>
+ This function allocates a &s.code;vgaHWRec&e.code; structure, and
+ hooks it into the &s.code;ScrnInfoRec&e.code;'s
+ &s.code;privates&e.code;. Like all information hooked into the
+ &s.code;privates&e.code;, it is persistent, and only needs to be
+ allocated once per screen. This function should normally be called
+ from the driver's &s.code;ChipPreInit()&e.code; function. The
+ &s.code;vgaHWRec&e.code; is zero-allocated, and the following
+ fields are explicitly initialised:
+
+ &s.code;ModeReg.DAC[]&e.code;
+ <quote>initialised with a default colourmap</quote>
+ &s.code;ModeReg.Attribute[0x11]&e.code;
+ <quote>initialised with the default overscan index</quote>
+ &s.code;ShowOverscan&e.code;
+ <quote>initialised according to the "ShowOverscan" option</quote>
+ &s.code;paletteEnabled&e.code;
+ <quote>initialised to FALSE</quote>
+ &s.code;cmapSaved&e.code;
+ <quote>initialised to FALSE</quote>
+ &s.code;pScrn&e.code;
+ <quote>initialised to pScrn</quote>
+
+ In addition to the above, &s.code;vgaHWSetStdFuncs()&e.code; is
+ called to initialise the register access function fields with the
+ standard VGA set of functions.
+
+ Once allocated, a pointer to the &s.code;vgaHWRec&e.code; can be
+ obtained from the &s.code;ScrnInfoPtr&e.code; with the
+ &s.code;VGAHWPTR(pScrn)&e.code; macro.
+
+ </quote>
+
+ &s.code;void vgaHWFreeHWRec(ScrnInfoPtr pScrn)&e.code;
+ <quote><p>
+ This function frees a &s.code;vgaHWRec&e.code; structure. It
+ should be called from a driver's &s.code;ChipFreeScreen()&e.code;
+ function.
+
+ </quote>
+
+ &s.code;Bool vgaHWSetRegCounts(ScrnInfoPtr pScrn, int numCRTC,
+ &f.indent;int numSequencer, int numGraphics, int numAttribute)&e.code;
+ <quote><p>
+ This function allows the number of CRTC, Sequencer, Graphics and
+ Attribute registers to be changed. This makes it possible for
+ extended registers to be saved and restored with
+ &s.code;vgaHWSave()&e.code; and &s.code;vgaHWRestore()&e.code;.
+ This function should be called after a &s.code;vgaHWRec&e.code;
+ has been allocated with &s.code;vgaHWGetHWRec()&e.code;. The
+ default values are defined in &s.code;vgaHW.h&e.code; as follows:
+
+ <quote><verb>
+#define VGA_NUM_CRTC 25
+#define VGA_NUM_SEQ 5
+#define VGA_NUM_GFX 9
+#define VGA_NUM_ATTR 21
+ </verb></quote>
+
+ </quote>
+
+ &s.code;Bool vgaHWCopyReg(vgaRegPtr dst, vgaRegPtr src)&e.code;
+ <quote><p>
+ This function copies the contents of the VGA saved registers in
+ &s.code;src&e.code; to &s.code;dst&e.code;. Note that it isn't
+ possible to simply do this with &s.code;memcpy()&e.code; (or
+ similar). This function returns &s.code;TRUE&e.code; unless there
+ is a problem allocating space for the &s.code;CRTC&e.code and
+ related fields in &s.code;dst&e.code;.
+
+ </quote>
+
+ &s.code;void vgaHWSetStdFuncs(vgaHWPtr hwp)&e.code;
+ <quote><p>
+ This function initialises the register access function fields of
+ &s.code;hwp&e.code; with the standard VGA set of functions. This
+ is called by &s.code;vgaHWGetHWRec()&e.code;, so there is usually
+ no need to call this explicitly. The register access functions
+ are described below. If the registers are shadowed in some other
+ port I/O space (for example a PCI I/O region), these functions
+ can be used to access the shadowed registers if
+ &s.code;hwp-&gt;PIOOffset&e.code; is initialised with
+ &s.code;offset&e.code;, calculated in such a way that when the
+ standard VGA I/O port value is added to it the correct offset into
+ the PIO area results. This value is initialised to zero in
+ &s.code;vgaHWGetHWRec()&e.code;. (Note: the PIOOffset functionality
+ is present in XFree86 4.1.0 and later.)
+
+ </quote>
+
+ &s.code;void vgaHWSetMmioFuncs(vgaHWPtr hwp, CARD8 *base, int offset)&e.code;
+ <quote><p>
+ This function initialised the register access function fields of
+ hwp with a generic MMIO set of functions.
+ &s.code;hwp-&gt;MMIOBase&e.code; is initialised with
+ &s.code;base&e.code;, which must be the virtual address that the
+ start of MMIO area is mapped to. &s.code;hwp-&gt;MMIOOffset&e.code;
+ is initialised with &s.code;offset&e.code;, which must be calculated
+ in such a way that when the standard VGA I/O port value is added
+ to it the correct offset into the MMIO area results. That means
+ that these functions are only suitable when the VGA I/O ports are
+ made available in a direct mapping to the MMIO space. If that is
+ not the case, the driver will need to provide its own register
+ access functions. The register access functions are described
+ below.
+
+ </quote>
+
+ &s.code;Bool vgaHWMapMem(ScrnInfoPtr pScrn)&e.code;
+ <quote><p>
+ This function maps the VGA memory window. It requires that the
+ &s.code;vgaHWRec&e.code; be allocated. If a driver requires
+ non-default &s.code;MapPhys&e.code; or &s.code;MapSize&e.code;
+ settings (the physical location and size of the VGA memory window)
+ then those fields of the &s.code;vgaHWRec&e.code; must be initialised
+ before calling this function. Otherwise, this function initialiases
+ the default values of &s.code;0xA0000&e.code; for
+ &s.code;MapPhys&e.code; and &s.code;(64&nbsp;*&nbsp;1024)&e.code; for
+ &s.code;MapSize&e.code;. This function must be called before
+ attempting to save or restore the VGA state. If the driver doesn't
+ call it explicitly, the &s.code;vgaHWSave()&e.code; and
+ &s.code;vgaHWRestore()&e.code; functions may call it if they need
+ to access the VGA memory (in which case they will also call
+ &s.code;vgaHWUnmapMem()&e.code; to unmap the VGA memory before
+ exiting).
+
+ </quote>
+
+ &s.code;void vgaHWUnmapMem(ScrnInfoPtr pScrn)&e.code;
+ <quote><p>
+ This function unmaps the VGA memory window. It must only be called
+ after the memory has been mapped. The &s.code;Base&e.code; field
+ of the &s.code;vgaHWRec&e.code; field is set to &s.code;NULL&e.code;
+ to indicate that the memory is no longer mapped.
+
+ </quote>
+
+ &s.code;void vgaHWGetIOBase(vgaHWPtr hwp)&e.code;
+ <quote><p>
+ This function initialises the &s.code;IOBase&e.code; field of the
+ &s.code;vgaHWRec&e.code;. This function must be called before
+ using any other functions that access the video hardware.
+
+ A macro &s.code;VGAHW_GET_IOBASE()&e.code; is also available in
+ &s.code;vgaHW.h&e.code; that returns the I/O base, and this may
+ be used when the vgahw module is not loaded (for example, in the
+ &s.code;ChipProbe()&e.code; function).
+
+ </quote>
+
+ &s.code;void vgaHWUnlock(vgaHWPtr hwp)&e.code;
+ <quote><p>
+ This function unlocks the VGA &s.code;CRTC[0-7]&e.code; registers,
+ and must be called before attempting to write to those registers.
+
+ </quote>
+
+ &s.code;void vgaHWLock(vgaHWPtr hwp)&e.code;
+ <quote><p>
+ This function locks the VGA &s.code;CRTC[0-7]&e.code; registers.
+
+ </quote>
+
+ &s.code;void vgaHWEnable(vgaHWPtr hwp)&e.code;
+ <quote><p>
+ This function enables the VGA subsystem. (Note, this function is
+ present in XFree86 4.1.0 and later.).
+
+ </quote>
+
+ &s.code;void vgaHWDisable(vgaHWPtr hwp)&e.code;
+ <quote><p>
+ This function disables the VGA subsystem. (Note, this function is
+ present in XFree86 4.1.0 and later.).
+
+ </quote>
+
+ &s.code;void vgaHWSave(ScrnInfoPtr pScrn, vgaRegPtr save, int flags)&e.code;
+ <quote><p>
+ This function saves the VGA state. The state is written to the
+ &s.code;vgaRegRec&e.code; pointed to by &s.code;save&e.code;.
+ &s.code;flags&e.code; is set to one or more of the following flags
+ ORed together:
+
+ &s.code;VGA_SR_MODE&e.code;
+ <quote>the mode setting registers are saved</quote>
+ &s.code;VGA_SR_FONTS&e.code;
+ <quote>the text mode font/text data is saved</quote>
+ &s.code;VGA_SR_CMAP&e.code;
+ <quote>the colourmap (LUT) is saved</quote>
+ &s.code;VGA_SR_ALL&e.code;
+ <quote>all of the above are saved</quote>
+
+ The &s.code;vgaHWRec&e.code; and its &s.code;IOBase&e.code; fields
+ must be initialised before this function is called. If
+ &s.code;VGA_SR_FONTS&e.code; is set in &s.code;flags&e.code;, the
+ VGA memory window must be mapped. If it isn't then
+ &s.code;vgaHWMapMem()&e.code; will be called to map it, and
+ &s.code;vgaHWUnmapMem()&e.code; will be called to unmap it
+ afterwards. &s.code;vgaHWSave()&e.code; uses the three functions
+ below in the order &s.code;vgaHWSaveColormap()&e.code;,
+ &s.code;vgaHWSaveMode()&e.code;, &s.code;vgaHWSaveFonts()&e.code; to
+ carry out the different save phases. It is undecided at this
+ stage whether they will remain part of the vgahw module's public
+ interface or not.
+
+ </quote>
+
+ &s.code;void vgaHWSaveMode(ScrnInfoPtr pScrn, vgaRegPtr save)&e.code;
+ <quote><p>
+ This function saves the VGA mode registers. They are saved to
+ the &s.code;vgaRegRec&e.code; pointed to by &s.code;save&e.code;.
+ The registers saved are:
+
+ <quote>
+ &s.code;MiscOut&nl;
+ CRTC[0-0x18]&nl;
+ Attribute[0-0x14]&nl;
+ Graphics[0-8]&nl;
+ Sequencer[0-4]&e.code;
+ </quote>
+
+ The number of registers actually saved may be modified by a prior call
+ to &s.code;vgaHWSetRegCounts()&e.code;.
+
+ </quote>
+
+ &s.code;void vgaHWSaveFonts(ScrnInfoPtr pScrn, vgaRegPtr save)&e.code;
+ <quote><p>
+ This function saves the text mode font and text data held in the
+ video memory. If called while in a graphics mode, no save is
+ done. The VGA memory window must be mapped with
+ &s.code;vgaHWMapMem()&e.code; before to calling this function.
+
+ On some platforms, one or more of the font/text plane saves may be
+ no-ops. This is the case when the platform's VC driver already
+ takes care of this.
+
+ </quote>
+
+ &s.code;void vgaHWSaveColormap(ScrnInfoPtr pScrn, vgaRegPtr save)&e.code;
+ <quote><p>
+ This function saves the VGA colourmap (LUT). Before saving it, it
+ attempts to verify that the colourmap is readable. In rare cases
+ where it isn't readable, a default colourmap is saved instead.
+
+ </quote>
+
+ &s.code;void vgaHWRestore(ScrnInfoPtr pScrn, vgaRegPtr restore, int flags)&e.code;
+ <quote><p>
+ This function programs the VGA state. The state programmed is
+ that contained in the &s.code;vgaRegRec&e.code; pointed to by
+ &s.code;restore&e.code;. &s.code;flags&e.code; is the same
+ as described above for the &s.code;vgaHWSave()&e.code; function.
+
+ The &s.code;vgaHWRec&e.code; and its &s.code;IOBase&e.code; fields
+ must be initialised before this function is called. If
+ &s.code;VGA_SR_FONTS&e.code; is set in &s.code;flags&e.code;, the
+ VGA memory window must be mapped. If it isn't then
+ &s.code;vgaHWMapMem()&e.code; will be called to map it, and
+ &s.code;vgaHWUnmapMem()&e.code; will be called to unmap it
+ afterwards. &s.code;vgaHWRestore()&e.code; uses the three functions
+ below in the order &s.code;vgaHWRestoreFonts()&e.code;,
+ &s.code;vgaHWRestoreMode()&e.code;,
+ &s.code;vgaHWRestoreColormap()&e.code; to carry out the different
+ restore phases. It is undecided at this stage whether they will
+ remain part of the vgahw module's public interface or not.
+
+ </quote>
+
+ &s.code;void vgaHWRestoreMode(ScrnInfoPtr pScrn, vgaRegPtr restore)&e.code;
+ <quote><p>
+ This function restores the VGA mode registers. They are restored
+ from the data in the &s.code;vgaRegRec&e.code; pointed to by
+ &s.code;restore&e.code;. The registers restored are:
+
+ <quote>
+ &s.code;MiscOut&nl;
+ CRTC[0-0x18]&nl;
+ Attribute[0-0x14]&nl;
+ Graphics[0-8]&nl;
+ Sequencer[0-4]&e.code;
+ </quote>
+
+ The number of registers actually restored may be modified by a prior call
+ to &s.code;vgaHWSetRegCounts()&e.code;.
+
+ </quote>
+
+ &s.code;void vgaHWRestoreFonts(ScrnInfoPtr pScrn, vgaRegPtr restore)&e.code;
+ <quote><p>
+ This function restores the text mode font and text data to the
+ video memory. The VGA memory window must be mapped with
+ &s.code;vgaHWMapMem()&e.code; before to calling this function.
+
+ On some platforms, one or more of the font/text plane restores
+ may be no-ops. This is the case when the platform's VC driver
+ already takes care of this.
+
+ </quote>
+
+ &s.code;void vgaHWRestoreColormap(ScrnInfoPtr pScrn, vgaRegPtr restore)&e.code;
+ <quote><p>
+ This function restores the VGA colourmap (LUT).
+
+ </quote>
+
+ &s.code;void vgaHWInit(ScrnInfoPtr pScrn, DisplayModePtr mode)&e.code;
+ <quote><p>
+ This function fills in the &s.code;vgaHWRec&e.code;'s
+ &s.code;ModeReg&e.code; field with the values appropriate for
+ programming the given video mode. It requires that the
+ &s.code;ScrnInfoRec&e.code;'s &s.code;depth&e.code; field is
+ initialised, which determines how the registers are programmed.
+
+ </quote>
+
+ &s.code;void vgaHWSeqReset(vgaHWPtr hwp, Bool start)&e.code;
+ <quote><p>
+ Do a VGA sequencer reset. If start is &s.code;TRUE&e.code;, the
+ reset is started. If start is &s.code;FALSE&e.code;, the reset
+ is ended.
+
+ </quote>
+
+ &s.code;void vgaHWProtect(ScrnInfoPtr pScrn, Bool on)&e.code;
+ <quote><p>
+ This function protects VGA registers and memory from corruption
+ during loads. It is typically called with on set to
+ &s.code;TRUE&e.code; before programming, and with on set to
+ &s.code;FALSE&e.code; after programming.
+
+ </quote>
+
+ &s.code;Bool vgaHWSaveScreen(ScreenPtr pScreen, int mode)&e.code;
+ <quote><p>
+ This function blanks and unblanks the screen. It is blanked when
+ &s.code;mode&e.code; is &s.code;SCREEN_SAVER_ON&e.code; or
+ &s.code;SCREEN_SAVER_CYCLE&e.code;, and unblanked when
+ &s.code;mode&e.code; is &s.code;SCREEN_SAVER_OFF&e.code; or
+ &s.code;SCREEN_SAVER_FORCER&e.code;.
+
+ </quote>
+
+ &s.code;void vgaHWBlankScreen(ScrnInfoPtr pScrn, Bool on)&e.code;
+ <quote><p>
+ This function blanks and unblanks the screen. It is blanked when
+ &s.code;on&e.code; is &s.code;FALSE&e.code;, and unblanked when
+ &s.code;on&e.code; is &s.code;TRUE&e.code;. This function is
+ provided for use in cases where the &s.code;ScrnInfoRec&e.code;
+ can't be derived from the &s.code;ScreenRec&e.code; (while probing
+ for clocks, for example).
+
+ </quote>
+ </quote>
+
+<sect1>VGA Colormap Functions
+<p>
+
+ The vgahw module uses the standard colormap support (see the
+ <ref id="cmap" name="Colormap Handling"> section. This is initialised
+ with the following function:
+
+ <quote>
+ &s.code;Bool vgaHWHandleColormaps(ScreenPtr pScreen)&e.code;
+ </quote>
+
+
+<sect1>VGA Register Access Functions
+<p>
+
+ The vgahw module abstracts access to the standard VGA registers by
+ using a set of functions held in the &s.code;vgaHWRec&e.code;. When
+ the &s.code;vgaHWRec&e.code; is created these function pointers are
+ initialised with the set of standard VGA I/O register access functions.
+ In addition to these, the vgahw module includes a basic set of MMIO
+ register access functions, and the &s.code;vgaHWRec&e.code; function
+ pointers can be initialised to these by calling the
+ &s.code;vgaHWSetMmioFuncs()&e.code; function described above. Some
+ drivers/platforms may require a different set of functions for VGA
+ access. The access functions are described here.
+
+
+ <quote><p>
+ &s.code;void writeCrtc(vgaHWPtr hwp, CARD8 index, CARD8 value)&e.code;
+ <quote><p>
+ Write &s.code;value&e.code; to CRTC register &s.code;index&e.code;.
+
+ </quote>
+
+ &s.code;CARD8 readCrtc(vgaHWPtr hwp, CARD8 index)&e.code;
+ <quote><p>
+ Return the value read from CRTC register &s.code;index&e.code;.
+
+ </quote>
+
+ &s.code;void writeGr(vgaHWPtr hwp, CARD8 index, CARD8 value)&e.code;
+ <quote><p>
+ Write &s.code;value&e.code; to Graphics Controller register
+ &s.code;index&e.code;.
+
+ </quote>
+
+ &s.code;CARD8 readGR(vgaHWPtr hwp, CARD8 index)&e.code;
+ <quote><p>
+ Return the value read from Graphics Controller register
+ &s.code;index&e.code;.
+
+ </quote>
+
+ &s.code;void writeSeq(vgaHWPtr hwp, CARD8 index, CARD8, value)&e.code;
+ <quote><p>
+ Write &s.code;value&e.code; to Sequencer register
+ &s.code;index&e.code;.
+
+ </quote>
+
+ &s.code;CARD8 readSeq(vgaHWPtr hwp, CARD8 index)&e.code;
+ <quote><p>
+ Return the value read from Sequencer register &s.code;index&e.code;.
+
+ </quote>
+
+ &s.code;void writeAttr(vgaHWPtr hwp, CARD8 index, CARD8, value)&e.code;
+ <quote><p>
+ Write &s.code;value&e.code; to Attribute Controller register
+ &s.code;index&e.code;. When writing out the index value this
+ function should set bit 5 (&s.code;0x20&e.code;) according to the
+ setting of &s.code;hwp-&gt;paletteEnabled&e.code; in order to
+ preserve the palette access state. It should be cleared when
+ &s.code;hwp-&gt;paletteEnabled&e.code; is &s.code;TRUE&e.code;
+ and set when it is &s.code;FALSE&e.code;.
+
+ </quote>
+
+ &s.code;CARD8 readAttr(vgaHWPtr hwp, CARD8 index)&e.code;
+ <quote><p>
+ Return the value read from Attribute Controller register
+ &s.code;index&e.code;. When writing out the index value this
+ function should set bit 5 (&s.code;0x20&e.code;) according to the
+ setting of &s.code;hwp-&gt;paletteEnabled&e.code; in order to
+ preserve the palette access state. It should be cleared when
+ &s.code;hwp-&gt;paletteEnabled&e.code; is &s.code;TRUE&e.code;
+ and set when it is &s.code;FALSE&e.code;.
+
+ </quote>
+
+ &s.code;void writeMiscOut(vgaHWPtr hwp, CARD8 value)&e.code;
+ <quote><p>
+ Write `&s.code;value&e.code;' to the Miscellaneous Output register.
+
+ </quote>
+
+ &s.code;CARD8 readMiscOut(vgwHWPtr hwp)&e.code;
+ <quote><p>
+ Return the value read from the Miscellaneous Output register.
+
+ </quote>
+
+ &s.code;void enablePalette(vgaHWPtr hwp)&e.code;
+ <quote><p>
+ Clear the palette address source bit in the Attribute Controller
+ index register and set &s.code;hwp-&gt;paletteEnabled&e.code; to
+ &s.code;TRUE&e.code;.
+
+ </quote>
+
+ &s.code;void disablePalette(vgaHWPtr hwp)&e.code;
+ <quote><p>
+ Set the palette address source bit in the Attribute Controller
+ index register and set &s.code;hwp-&gt;paletteEnabled&e.code; to
+ &s.code;FALSE&e.code;.
+
+ </quote>
+
+ &s.code;void writeDacMask(vgaHWPtr hwp, CARD8 value)&e.code;
+ <quote><p>
+ Write &s.code;value&e.code; to the DAC Mask register.
+
+ </quote>
+
+ &s.code;CARD8 readDacMask(vgaHWptr hwp)&e.code;
+ <quote><p>
+ Return the value read from the DAC Mask register.
+
+ </quote>
+
+ &s.code;void writeDacReadAddress(vgaHWPtr hwp, CARD8 value)&e.code;
+ <quote><p>
+ Write &s.code;value&e.code; to the DAC Read Address register.
+
+ </quote>
+
+ &s.code;void writeDacWriteAddress(vgaHWPtr hwp, CARD8 value)&e.code;
+ <quote><p>
+ Write &s.code;value&e.code; to the DAC Write Address register.
+
+ </quote>
+
+ &s.code;void writeDacData(vgaHWPtr hwp, CARD8 value)&e.code;
+ <quote><p>
+ Write &s.code;value&e.code; to the DAC Data register.
+
+ </quote>
+
+ &s.code;CARD8 readDacData(vgaHWptr hwp)&e.code;
+ <quote><p>
+ Return the value read from the DAC Data register.
+
+ </quote>
+
+ &s.code;CARD8 readEnable(vgaHWptr hwp)&e.code;
+ <quote><p>
+ Return the value read from the VGA Enable register. (Note: This
+ function is present in XFree86 4.1.0 and later.)
+
+ </quote>
+
+ &s.code;void writeEnable(vgaHWPtr hwp, CARD8 value)&e.code;
+ <quote><p>
+ Write &s.code;value&e.code; to the VGA Enable register. (Note: This
+ function is present in XFree86 4.1.0 and later.)
+
+ </quote>
+ </quote>
+
+<sect>Some notes about writing a driver<label id="sample">
+<p>
+
+<em>NOTE: some parts of this are not up to date</em>
+
+The following is an outline for writing a basic unaccelerated driver
+for a PCI video card with a linear mapped framebuffer, and which has a
+VGA core. It is includes some general information that is relevant to
+most drivers (even those which don't fit that basic description).
+
+The information here is based on the initial conversion of the Matrox
+Millennium driver to the ``new design''. For a fleshing out and sample
+implementation of some of the bits outlined here, refer to that driver.
+Note that this is an example only. The approach used here will not be
+appropriate for all drivers.
+
+Each driver must reserve a unique driver name, and a string that is used
+to prefix all of its externally visible symbols. This is to avoid name
+space clashes when loading multiple drivers. The examples here are for
+the ``ZZZ'' driver, which uses the ``ZZZ'' or ``zzz'' prefix for its externally
+visible symbols.
+
+
+<sect1>Include files
+<p>
+
+ All drivers normally include the following headers:
+ <quote>
+ &s.code;"xf86.h"&nl;
+ "xf86_OSproc.h"&nl;
+ "xf86_ansic.h"&nl;
+ "xf86Resources.h"&e.code;
+ </quote>
+ Wherever inb/outb (and related things) are used the following should be
+ included:
+ <quote>
+ &s.code;"compiler.h"&e.code;
+ </quote>
+ Note: in drivers, this must be included after &s.code;"xf86_ansic.h"&e.code;.
+
+ Drivers that need to access PCI vendor/device definitions need this:
+ <quote>
+ &s.code;"xf86PciInfo.h"&e.code;
+ </quote>
+
+ Drivers that need to access the PCI config space need this:
+ <quote>
+ &s.code;"xf86Pci.h"&e.code;
+ </quote>
+
+ Drivers using the mi banking wrapper need:
+
+ <quote>
+ &s.code;"mibank.h"&e.code;
+ </quote>
+
+ Drivers that initialise a SW cursor need this:
+ <quote>
+ &s.code;"mipointer.h"&e.code;
+ </quote>
+
+ All drivers implementing backing store need this:
+ <quote>
+ &s.code;"mibstore.h"&e.code;
+ </quote>
+
+ All drivers using the mi colourmap code need this:
+ <quote>
+ &s.code;"micmap.h"&e.code;
+ </quote>
+
+ If a driver uses the vgahw module, it needs this:
+ <quote>
+ &s.code;"vgaHW.h"&e.code;
+ </quote>
+
+ Drivers supporting VGA or Hercules monochrome screens need:
+ <quote>
+ &s.code;"xf1bpp.h"&e.code;
+ </quote>
+
+ Drivers supporting VGA or EGC 16-colour screens need:
+ <quote>
+ &s.code;"xf4bpp.h"&e.code;
+ </quote>
+
+ Drivers using cfb need:
+ <quote>
+ &s.code;#define PSZ 8&nl;
+ #include "cfb.h"&nl;
+ #undef PSZ&e.code;
+ </quote>
+
+ Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:
+ <quote>
+ &s.code;"cfb16.h"&nl;
+ "cfb24.h"&nl;
+ "cfb32.h"&e.code;
+ </quote>
+
+ The driver's own header file:
+ <quote>
+ &s.code;"zzz.h"&e.code;
+ </quote>
+
+ Drivers must NOT include the following:
+
+ <quote>
+ &s.code;"xf86Priv.h"&nl;
+ "xf86Privstr.h"&nl;
+ "xf86_libc.h"&nl;
+ "xf86_OSlib.h"&nl;
+ "Xos.h"&e.code;&nl;
+ any OS header
+ </quote>
+
+
+<sect1>Data structures and initialisation
+<p>
+
+<itemize>
+ <item>The following macros should be defined:
+ <code>
+#define VERSION <version-as-an-int>
+#define ZZZ_NAME "ZZZ" /* the name used to prefix messages */
+#define ZZZ_DRIVER_NAME "zzz" /* the driver name as used in config file */
+#define ZZZ_MAJOR_VERSION <int>
+#define ZZZ_MINOR_VERSION <int>
+#define ZZZ_PATCHLEVEL <int>
+ </code>
+<p>
+ NOTE: &s.code;ZZZ_DRIVER_NAME&e.code; should match the name of the
+ driver module without things like the "lib" prefix, the "_drv" suffix
+ or filename extensions.
+<p>
+
+ <item>A DriverRec must be defined, which includes the functions required
+ at the pre-probe phase. The name of this DriverRec must be an
+ upper-case version of ZZZ_DRIVER_NAME (for the purposes of static
+ linking).
+<p>
+ <code>
+DriverRec ZZZ = {
+ VERSION,
+ ZZZ_DRIVER_NAME,
+ ZZZIdentify,
+ ZZZProbe,
+ ZZZAvailableOptions,
+ NULL,
+ 0
+};
+ </code>
+
+ <item>Define list of supported chips and their matching ID:
+<p>
+ <code>
+static SymTabRec ZZZChipsets[] = {
+ { PCI_CHIP_ZZZ1234, "zzz1234a" },
+ { PCI_CHIP_ZZZ5678, "zzz5678a" },
+ { -1, NULL }
+};
+ </code>
+<p>
+ The token field may be any integer value that the driver may use to
+ uniquely identify the supported chipsets. For drivers that support
+ only PCI devices using the PCI device IDs might be a natural choice,
+ but this isn't mandatory. For drivers that support both PCI and other
+ devices (like ISA), some other ID should probably used. When other
+ IDs are used as the tokens it is recommended that the names be
+ defined as an &s.code;enum&e.code; type.
+<p>
+ <item>If the driver uses the &s.code;xf86MatchPciInstances(&e.code;)
+ helper (recommended for drivers that support PCI cards) a list that
+ maps PCI IDs to chip IDs and fixed resources must be defined:
+<p>
+ <code>
+static PciChipsets ZZZPciChipsets[] = {
+ { PCI_CHIP_ZZZ1234, PCI_CHIP_ZZZ1234, RES_SHARED_VGA },
+ { PCI_CHIP_ZZZ5678, PCI_CHIP_ZZZ5678, RES_SHARED_VGA },
+ { -1, -1, RES_UNDEFINED }
+}
+ </code>
+<p>
+ <item>Define the &s.code;XF86ModuleVersionInfo&e.code; struct for the
+ driver. This is required for the dynamically loaded version:
+<p>
+ <code>
+static XF86ModuleVersionInfo zzzVersRec =
+{
+ "zzz",
+ MODULEVENDORSTRING,
+ MODINFOSTRING1,
+ MODINFOSTRING2,
+ XF86_VERSION_CURRENT,
+ ZZZ_MAJOR_VERSION, ZZZ_MINOR_VERSION, ZZZ_PATCHLEVEL,
+ ABI_CLASS_VIDEODRV,
+ ABI_VIDEODRV_VERSION,
+ MOD_CLASS_VIDEODRV,
+ {0,0,0,0}
+};
+ </code>
+<p>
+ <item>Define a data structure to hold the driver's screen-specific data.
+ This must be used instead of global variables. This would be defined
+ in the &s.code;"zzz.h"&e.code; file, something like:
+<p>
+ <code>
+typedef struct {
+ type1 field1;
+ type2 field2;
+ int fooHack;
+ Bool pciRetry;
+ Bool noAccel;
+ Bool hwCursor;
+ CloseScreenProcPtr CloseScreen;
+ OptionInfoPtr Options;
+ ...
+} ZZZRec, *ZZZPtr;
+ </code>
+<p>
+ <item>Define the list of config file Options that the driver accepts. For
+ consistency between drivers those in the list of ``standard'' options
+ should be used where appropriate before inventing new options.
+<p>
+ <code>
+typedef enum {
+ OPTION_FOO_HACK,
+ OPTION_PCI_RETRY,
+ OPTION_HW_CURSOR,
+ OPTION_NOACCEL
+} ZZZOpts;
+
+static const OptionInfoRec ZZZOptions[] = {
+ { OPTION_FOO_HACK, "FooHack", OPTV_INTEGER, {0}, FALSE },
+ { OPTION_PCI_RETRY, "PciRetry", OPTV_BOOLEAN, {0}, FALSE },
+ { OPTION_HW_CURSOR, "HWcursor", OPTV_BOOLEAN, {0}, FALSE },
+ { OPTION_NOACCEL, "NoAccel", OPTV_BOOLEAN, {0}, FALSE },
+ { -1, NULL, OPTV_NONE, {0}, FALSE }
+};
+ </code>
+<p>
+</itemize>
+
+<sect1>Functions
+<p>
+
+
+<sect2>SetupProc
+<p>
+
+ For dynamically loaded modules, a &s.code;ModuleData&e.code;
+ variable is required. It is should be the name of the driver
+ prepended to "ModuleData". A &s.code;Setup()&e.code; function is
+ also required, which calls &s.code;xf86AddDriver()&e.code; to add
+ the driver to the main list of drivers.
+
+ <code>
+static MODULESETUPPROTO(zzzSetup);
+
+XF86ModuleData zzzModuleData = { &amp;zzzVersRec, zzzSetup, NULL };
+
+static pointer
+zzzSetup(pointer module, pointer opts, int *errmaj, int *errmin)
+{
+ static Bool setupDone = FALSE;
+
+ /* This module should be loaded only once, but check to be sure. */
+
+ if (!setupDone) {
+ /*
+ * Modules that this driver always requires may be loaded
+ * here by calling LoadSubModule().
+ */
+
+ setupDone = TRUE;
+ xf86AddDriver(&amp;MGA, module, 0);
+
+ /*
+ * The return value must be non-NULL on success even though
+ * there is no TearDownProc.
+ */
+ return (pointer)1;
+ } else {
+ if (errmaj) *errmaj = LDR_ONCEONLY;
+ return NULL;
+ }
+}
+ </code>
+
+<sect2>GetRec, FreeRec
+<p>
+
+ A function is usually required to allocate the driver's
+ screen-specific data structure and hook it into the
+ &s.code;ScrnInfoRec&e.code;'s &s.code;driverPrivate&e.code; field.
+ The &s.code;ScrnInfoRec&e.code;'s &s.code;driverPrivate&e.code; is
+ initialised to &s.code;NULL&e.code;, so it is easy to check if the
+ initialisation has already been done. After allocating it, initialise
+ the fields. By using &s.code;xnfcalloc()&e.code; to do the allocation
+ it is zeroed, and if the allocation fails the server exits.
+<p>
+ NOTE:
+ When allocating structures from inside the driver which are defined
+ on the common level it is important to initialize the structure to
+ zero.
+ Only this guarantees that the server remains source compatible to
+ future changes in common level structures.
+
+ <code>
+static Bool
+ZZZGetRec(ScrnInfoPtr pScrn)
+{
+ if (pScrn->driverPrivate != NULL)
+ return TRUE;
+ pScrn->driverPrivate = xnfcalloc(sizeof(ZZZRec), 1);
+ /* Initialise as required */
+ ...
+ return TRUE;
+}
+ </code>
+
+ Define a macro in &s.code;"zzz.h"&e.code; which gets a pointer to
+ the &s.code;ZZZRec&e.code; when given &s.code;pScrn&e.code;:
+
+ <code>
+#define ZZZPTR(p) ((ZZZPtr)((p)->driverPrivate))
+ </code>
+
+ Define a function to free the above, setting it to &s.code;NULL&e.code;
+ once it has been freed:
+
+ <code>
+static void
+ZZZFreeRec(ScrnInfoPtr pScrn)
+{
+ if (pScrn->driverPrivate == NULL)
+ return;
+ xfree(pScrn->driverPrivate);
+ pScrn->driverPrivate = NULL;
+}
+ </code>
+
+<sect2>Identify
+<p>
+
+ Define the &s.code;Identify()&e.code; function. It is run before
+ the Probe, and typically prints out an identifying message, which
+ might include the chipsets it supports. This function is mandatory:
+
+ <code>
+static void
+ZZZIdentify(int flags)
+{
+ xf86PrintChipsets(ZZZ_NAME, "driver for ZZZ Tech chipsets",
+ ZZZChipsets);
+}
+ </code>
+
+<sect2>Probe
+<p>
+
+ Define the &s.code;Probe()&e.code; function. The purpose of this
+ is to find all instances of the hardware that the driver supports,
+ and for the ones not already claimed by another driver, claim the
+ slot, and allocate a &s.code;ScrnInfoRec&e.code;. This should be
+ a minimal probe, and it should under no circumstances leave the
+ state of the hardware changed. Because a device is found, don't
+ assume that it will be used. Don't do any initialisations other
+ than the required &s.code;ScrnInfoRec&e.code; initialisations.
+ Don't allocate any new data structures.
+
+ This function is mandatory.
+
+ NOTE: The &s.code;xf86DrvMsg()&e.code; functions cannot be used from
+ the Probe.
+
+ <code>
+static Bool
+ZZZProbe(DriverPtr drv, int flags)
+{
+ Bool foundScreen = FALSE;
+ int numDevSections, numUsed;
+ GDevPtr *devSections;
+ int *usedChips;
+ int i;
+
+ /*
+ * Find the config file Device sections that match this
+ * driver, and return if there are none.
+ */
+ if ((numDevSections = xf86MatchDevice(ZZZ_DRIVER_NAME,
+ &amp;devSections)) <= 0) {
+ return FALSE;
+ }
+
+ /*
+ * Since this is a PCI card, "probing" just amounts to checking
+ * the PCI data that the server has already collected. If there
+ * is none, return.
+ *
+ * Although the config file is allowed to override things, it
+ * is reasonable to not allow it to override the detection
+ * of no PCI video cards.
+ *
+ * The provided xf86MatchPciInstances() helper takes care of
+ * the details.
+ */
+ /* test if PCI bus present */
+ if (xf86GetPciVideoInfo()) {
+
+ numUsed = xf86MatchPciInstances(ZZZ_NAME, PCI_VENDOR_ZZZ,
+ ZZZChipsets, ZZZPciChipsets, devSections,
+ numDevSections, drv, &amp;usedChips);
+
+ for (i = 0; i < numUsed; i++) {
+ ScrnInfoPtr pScrn = NULL;
+ if ((pScrn = xf86ConfigPciEntity(pScrn, flags, usedChips[i],
+ ZZZPciChipsets, NULL, NULL,
+ NULL, NULL, NULL))) {
+ /* Allocate a ScrnInfoRec */
+ pScrn->driverVersion = VERSION;
+ pScrn->driverName = ZZZ_DRIVER_NAME;
+ pScrn->name = ZZZ_NAME;
+ pScrn->Probe = ZZZProbe;
+ pScrn->PreInit = ZZZPreInit;
+ pScrn->ScreenInit = ZZZScreenInit;
+ pScrn->SwitchMode = ZZZSwitchMode;
+ pScrn->AdjustFrame = ZZZAdjustFrame;
+ pScrn->EnterVT = ZZZEnterVT;
+ pScrn->LeaveVT = ZZZLeaveVT;
+ pScrn->FreeScreen = ZZZFreeScreen;
+ pScrn->ValidMode = ZZZValidMode;
+ foundScreen = TRUE;
+ /* add screen to entity */
+ }
+ }
+ xfree(usedChips);
+ }
+
+#ifdef HAS_ISA_DEVS
+ /*
+ * If the driver supports ISA hardware, the following block
+ * can be included too.
+ */
+ numUsed = xf86MatchIsaInstances(ZZZ_NAME, ZZZChipsets,
+ ZZZIsaChipsets, drv, ZZZFindIsaDevice,
+ devSections, numDevSections, &amp;usedChips);
+ for (i = 0; i < numUsed; i++) {
+ ScrnInfoPtr pScrn = NULL;
+ if ((pScrn = xf86ConfigIsaEntity(pScrn, flags, usedChips[i],
+ ZZZIsaChipsets, NULL, NULL, NULL,
+ NULL, NULL))) {
+ pScrn->driverVersion = VERSION;
+ pScrn->driverName = ZZZ_DRIVER_NAME;
+ pScrn->name = ZZZ_NAME;
+ pScrn->Probe = ZZZProbe;
+ pScrn->PreInit = ZZZPreInit;
+ pScrn->ScreenInit = ZZZScreenInit;
+ pScrn->SwitchMode = ZZZSwitchMode;
+ pScrn->AdjustFrame = ZZZAdjustFrame;
+ pScrn->EnterVT = ZZZEnterVT;
+ pScrn->LeaveVT = ZZZLeaveVT;
+ pScrn->FreeScreen = ZZZFreeScreen;
+ pScrn->ValidMode = ZZZValidMode;
+ foundScreen = TRUE;
+ }
+ }
+ xfree(usedChips);
+#endif /* HAS_ISA_DEVS */
+
+ xfree(devSections);
+ return foundScreen;
+ </code>
+
+<sect2>AvailableOptions
+<p>
+
+ Define the &s.code;AvailableOptions()&e.code; function. The purpose
+ of this is to return the available driver options back to the
+ -configure option, so that an xorg.conf file can be built and the
+ user can see which options are available for them to use.
+
+<sect2>PreInit
+<p>
+
+ Define the &s.code;PreInit()&e.code; function. The purpose of
+ this is to find all the information required to determine if the
+ configuration is usable, and to initialise those parts of the
+ &s.code;ScrnInfoRec&e.code; that can be set once at the beginning
+ of the first server generation. The information should be found in
+ the least intrusive way possible.
+
+ This function is mandatory.
+
+ NOTES:
+ <enum>
+ <item>The &s.code;PreInit()&e.code; function is only called once
+ during the life of the X server (at the start of the first
+ generation).
+
+ <item>Data allocated here must be of the type that persists for
+ the life of the X server. This means that data that hooks into
+ the &s.code;ScrnInfoRec&e.code;'s &s.code;privates&e.code;
+ field should be allocated here, but data that hooks into the
+ &s.code;ScreenRec&e.code;'s &s.code;devPrivates&e.code; field
+ should not be allocated here. The &s.code;driverPrivate&e.code;
+ field should also be allocated here.
+
+ <item>Although the &s.code;ScrnInfoRec&e.code; has been allocated
+ before this function is called, the &s.code;ScreenRec&e.code;
+ has not been allocated. That means that things requiring it
+ cannot be used in this function.
+
+ <item>Very little of the &s.code;ScrnInfoRec&e.code; has been
+ initialised when this function is called. It is important to
+ get the order of doing things right in this function.
+
+ </enum>
+
+ <code>
+static Bool
+ZZZPreInit(ScrnInfoPtr pScrn, int flags)
+{
+ /* Fill in the monitor field */
+ pScrn->monitor = pScrn->confScreen->monitor;
+
+ /*
+ * If using the vgahw module, it will typically be loaded
+ * here by calling xf86LoadSubModule(pScrn, "vgahw");
+ */
+
+ /*
+ * Set the depth/bpp. Use the globally preferred depth/bpp. If the
+ * driver has special default depth/bpp requirements, the defaults should
+ * be specified here explicitly.
+ * We support both 24bpp and 32bpp framebuffer layouts.
+ * This sets pScrn->display also.
+ */
+ if (!xf86SetDepthBpp(pScrn, 0, 0, 0,
+ Support24bppFb | Support32bppFb)) {
+ return FALSE;
+ } else {
+ if (depth/bpp isn't one we support) {
+ print error message;
+ return FALSE;
+ }
+ }
+ /* Print out the depth/bpp that was set */
+ xf86PrintDepthBpp(pScrn);
+
+ /* Set bits per RGB for 8bpp */
+ if (pScrn->depth <= 8) {
+ /* Take into account a dac_6_bit option here */
+ pScrn->rgbBits = 6 or 8;
+ }
+
+ /*
+ * xf86SetWeight() and xf86SetDefaultVisual() must be called
+ * after pScrn->display is initialised.
+ */
+
+ /* Set weight/mask/offset for depth > 8 */
+ if (pScrn->depth > 8) {
+ if (!xf86SetWeight(pScrn, defaultWeight, defaultMask)) {
+ return FALSE;
+ } else {
+ if (weight isn't one we support) {
+ print error message;
+ return FALSE;
+ }
+ }
+ }
+
+ /* Set the default visual. */
+ if (!xf86SetDefaultVisual(pScrn, -1)) {
+ return FALSE;
+ } else {
+ if (visual isn't one we support) {
+ print error message;
+ return FALSE;
+ }
+ }
+
+ /* If the driver supports gamma correction, set the gamma. */
+ if (!xf86SetGamma(pScrn, default_gamma)) {
+ return FALSE;
+ }
+
+ /* This driver uses a programmable clock */
+ pScrn->progClock = TRUE;
+
+ /* Allocate the ZZZRec driverPrivate */
+ if (!ZZZGetRec(pScrn)) {
+ return FALSE;
+ }
+
+ pZzz = ZZZPTR(pScrn);
+
+ /* Collect all of the option flags (fill in pScrn->options) */
+ xf86CollectOptions(pScrn, NULL);
+
+ /*
+ * Process the options based on the information in ZZZOptions.
+ * The results are written to pZzz->Options. If all of the options
+ * processing is done within this function a local variable "options"
+ * can be used instead of pZzz->Options.
+ */
+ if (!(pZzz->Options = xalloc(sizeof(ZZZOptions))))
+ return FALSE;
+ (void)memcpy(pZzz->Options, ZZZOptions, sizeof(ZZZOptions));
+ xf86ProcessOptions(pScrn->scrnIndex, pScrn->options, pZzz->Options);
+
+ /*
+ * Set various fields of ScrnInfoRec and/or ZZZRec based on
+ * the options found.
+ */
+ from = X_DEFAULT;
+ pZzz->hwCursor = FALSE;
+ if (xf86IsOptionSet(pZzz->Options, OPTION_HW_CURSOR)) {
+ from = X_CONFIG;
+ pZzz->hwCursor = TRUE;
+ }
+ xf86DrvMsg(pScrn->scrnIndex, from, "Using %s cursor\n",
+ pZzz->hwCursor ? "HW" : "SW");
+ if (xf86IsOptionSet(pZzz->Options, OPTION_NOACCEL)) {
+ pZzz->noAccel = TRUE;
+ xf86DrvMsg(pScrn->scrnIndex, X_CONFIG,
+ "Acceleration disabled\n");
+ } else {
+ pZzz->noAccel = FALSE;
+ }
+ if (xf86IsOptionSet(pZzz->Options, OPTION_PCI_RETRY)) {
+ pZzz->UsePCIRetry = TRUE;
+ xf86DrvMsg(pScrn->scrnIndex, X_CONFIG, "PCI retry enabled\n");
+ }
+ pZzz->fooHack = 0;
+ if (xf86GetOptValInteger(pZzz->Options, OPTION_FOO_HACK,
+ &amp;pZzz->fooHack)) {
+ xf86DrvMsg(pScrn->scrnIndex, X_CONFIG, "Foo Hack set to %d\n",
+ pZzz->fooHack);
+ }
+
+ /*
+ * Find the PCI slot(s) that this screen claimed in the probe.
+ * In this case, exactly one is expected, so complain otherwise.
+ * Note in this case we're not interested in the card types so
+ * that parameter is set to NULL.
+ */
+ if ((i = xf86GetPciInfoForScreen(pScrn->scrnIndex, &amp;pciList, NULL))
+ != 1) {
+ print error message;
+ ZZZFreeRec(pScrn);
+ if (i > 0)
+ xfree(pciList);
+ return FALSE;
+ }
+ /* Note that pciList should be freed below when no longer needed */
+
+ /*
+ * Determine the chipset, allowing config file chipset and
+ * chipid values to override the probed information. The config
+ * chipset value has precedence over its chipid value if both
+ * are present.
+ *
+ * It isn't necessary to fill in pScrn->chipset if the driver
+ * keeps track of the chipset in its ZZZRec.
+ */
+
+ ...
+
+ /*
+ * Determine video memory, fb base address, I/O addresses, etc,
+ * allowing the config file to override probed values.
+ *
+ * Set the appropriate pScrn fields (videoRam is probably the
+ * most important one that other code might require), and
+ * print out the settings.
+ */
+
+ ...
+
+ /* Initialise a clockRanges list. */
+
+ ...
+
+ /* Set any other chipset specific things in the ZZZRec */
+
+ ...
+
+ /* Select valid modes from those available */
+
+ i = xf86ValidateModes(pScrn, pScrn->monitor->Modes,
+ pScrn->display->modes, clockRanges,
+ NULL, minPitch, maxPitch, rounding,
+ minHeight, maxHeight,
+ pScrn->display->virtualX,
+ pScrn->display->virtualY,
+ pScrn->videoRam * 1024,
+ LOOKUP_BEST_REFRESH);
+ if (i == -1) {
+ ZZZFreeRec(pScrn);
+ return FALSE;
+ }
+
+ /* Prune the modes marked as invalid */
+
+ xf86PruneDriverModes(pScrn);
+
+ /* If no valid modes, return */
+
+ if (i == 0 || pScrn->modes == NULL) {
+ print error message;
+ ZZZFreeRec(pScrn);
+ return FALSE;
+ }
+
+ /*
+ * Initialise the CRTC fields for the modes. This driver expects
+ * vertical values to be halved for interlaced modes.
+ */
+ xf86SetCrtcForModes(pScrn, INTERLACE_HALVE_V);
+
+ /* Set the current mode to the first in the list. */
+ pScrn->currentMode = pScrn->modes;
+
+ /* Print the list of modes being used. */
+ xf86PrintModes(pScrn);
+
+ /* Set the DPI */
+ xf86SetDpi(pScrn, 0, 0);
+
+ /* Load bpp-specific modules */
+ switch (pScrn->bitsPerPixel) {
+ case 1:
+ mod = "xf1bpp";
+ break;
+ case 4:
+ mod = "xf4bpp";
+ break;
+ case 8:
+ mod = "cfb";
+ break;
+ case 16:
+ mod = "cfb16";
+ break;
+ case 24:
+ mod = "cfb24";
+ break;
+ case 32:
+ mod = "cfb32";
+ break;
+ }
+ if (mod && !xf86LoadSubModule(pScrn, mod))
+ ZZZFreeRec(pScrn);
+ return FALSE;
+
+ /* Load XAA if needed */
+ if (!pZzz->noAccel || pZzz->hwCursor)
+ if (!xf86LoadSubModule(pScrn, "xaa")) {
+ ZZZFreeRec(pScrn);
+ return FALSE;
+ }
+
+ /* Done */
+ return TRUE;
+}
+ </code>
+
+<sect2>MapMem, UnmapMem
+<p>
+
+ Define functions to map and unmap the video memory and any other
+ memory apertures required. These functions are not mandatory, but
+ it is often useful to have such functions.
+
+ <code>
+static Bool
+ZZZMapMem(ScrnInfoPtr pScrn)
+{
+ /* Call xf86MapPciMem() to map each PCI memory area */
+ ...
+ return TRUE or FALSE;
+}
+
+static Bool
+ZZZUnmapMem(ScrnInfoPtr pScrn)
+{
+ /* Call xf86UnMapVidMem() to unmap each memory area */
+ ...
+ return TRUE or FALSE;
+}
+ </code>
+
+<sect2>Save, Restore
+<p>
+
+ Define functions to save and restore the original video state. These
+ functions are not mandatory, but are often useful.
+
+ <code>
+static void
+ZZZSave(ScrnInfoPtr pScrn)
+{
+ /*
+ * Save state into per-screen data structures.
+ * If using the vgahw module, vgaHWSave will typically be
+ * called here.
+ */
+ ...
+}
+
+static void
+ZZZRestore(ScrnInfoPtr pScrn)
+{
+ /*
+ * Restore state from per-screen data structures.
+ * If using the vgahw module, vgaHWRestore will typically be
+ * called here.
+ */
+ ...
+}
+ </code>
+
+<sect2>ModeInit
+<p>
+
+ Define a function to initialise a new video mode. This function isn't
+ mandatory, but is often useful.
+
+ <code>
+static Bool
+ZZZModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode)
+{
+ /*
+ * Program a video mode. If using the vgahw module,
+ * vgaHWInit and vgaRestore will typically be called here.
+ * Once up to the point where there can't be a failure
+ * set pScrn->vtSema to TRUE.
+ */
+ ...
+}
+ </code>
+
+<sect2>ScreenInit
+<p>
+
+ Define the &s.code;ScreenInit()&e.code; function. This is called
+ at the start of each server generation, and should fill in as much
+ of the &s.code;ScreenRec&e.code; as possible as well as any other
+ data that is initialised once per generation. It should initialise
+ the framebuffer layers it is using, and initialise the initial video
+ mode.
+
+ This function is mandatory.
+
+ NOTE: The &s.code;ScreenRec&e.code; (&s.code;pScreen&e.code;) is
+ passed to this driver, but it and the
+ &s.code;ScrnInfoRecs&e.code; are not yet hooked into each
+ other. This means that in this function, and functions it
+ calls, one cannot be found from the other.
+
+ <code>
+static Bool
+ZZZScreenInit(int scrnIndex, ScreenPtr pScreen, int argc, char **argv)
+{
+ /* Get the ScrnInfoRec */
+ pScrn = xf86Screens[pScreen->myNum];
+
+ /*
+ * If using the vgahw module, its data structures and related
+ * things are typically initialised/mapped here.
+ */
+
+ /* Save the current video state */
+ ZZZSave(pScrn);
+
+ /* Initialise the first mode */
+ ZZZModeInit(pScrn, pScrn->currentMode);
+
+ /* Set the viewport if supported */
+
+ ZZZAdjustFrame(scrnIndex, pScrn->frameX0, pScrn->frameY0, 0);
+
+ /*
+ * Setup the screen's visuals, and initialise the framebuffer
+ * code.
+ */
+
+ /* Reset the visual list */
+ miClearVisualTypes();
+
+ /*
+ * Setup the visuals supported. This driver only supports
+ * TrueColor for bpp > 8, so the default set of visuals isn't
+ * acceptable. To deal with this, call miSetVisualTypes with
+ * the appropriate visual mask.
+ */
+
+ if (pScrn->bitsPerPixel > 8) {
+ if (!miSetVisualTypes(pScrn->depth, TrueColorMask,
+ pScrn->rgbBits, pScrn->defaultVisual))
+ return FALSE;
+ } else {
+ if (!miSetVisualTypes(pScrn->depth,
+ miGetDefaultVisualMask(pScrn->depth),
+ pScrn->rgbBits, pScrn->defaultVisual))
+ return FALSE;
+ }
+
+ /*
+ * Initialise the framebuffer.
+ */
+
+ switch (pScrn->bitsPerPixel) {
+ case 1:
+ ret = xf1bppScreenInit(pScreen, FbBase,
+ pScrn->virtualX, pScrn->virtualY,
+ pScrn->xDpi, pScrn->yDpi,
+ pScrn->displayWidth);
+ break;
+ case 4:
+ ret = xf4bppScreenInit(pScreen, FbBase,
+ pScrn->virtualX, pScrn->virtualY,
+ pScrn->xDpi, pScrn->yDpi,
+ pScrn->displayWidth);
+ break;
+ case 8:
+ ret = cfbScreenInit(pScreen, FbBase,
+ pScrn->virtualX, pScrn->virtualY,
+ pScrn->xDpi, pScrn->yDpi,
+ pScrn->displayWidth);
+ break;
+ case 16:
+ ret = cfb16ScreenInit(pScreen, FbBase,
+ pScrn->virtualX, pScrn->virtualY,
+ pScrn->xDpi, pScrn->yDpi,
+ pScrn->displayWidth);
+ break;
+ case 24:
+ ret = cfb24ScreenInit(pScreen, FbBase,
+ pScrn->virtualX, pScrn->virtualY,
+ pScrn->xDpi, pScrn->yDpi,
+ pScrn->displayWidth);
+ break;
+ case 32:
+ ret = cfb32ScreenInit(pScreen, FbBase,
+ pScrn->virtualX, pScrn->virtualY,
+ pScrn->xDpi, pScrn->yDpi,
+ pScrn->displayWidth);
+ break;
+ default:
+ print a message about an internal error;
+ ret = FALSE;
+ break;
+ }
+
+ if (!ret)
+ return FALSE;
+
+ /* Override the default mask/offset settings */
+ if (pScrn->bitsPerPixel > 8) {
+ for (i = 0, visual = pScreen->visuals;
+ i < pScreen->numVisuals; i++, visual++) {
+ if ((visual->class | DynamicClass) == DirectColor) {
+ visual->offsetRed = pScrn->offset.red;
+ visual->offsetGreen = pScrn->offset.green;
+ visual->offsetBlue = pScrn->offset.blue;
+ visual->redMask = pScrn->mask.red;
+ visual->greenMask = pScrn->mask.green;
+ visual->blueMask = pScrn->mask.blue;
+ }
+ }
+ }
+
+ /*
+ * If banking is needed, initialise an miBankInfoRec (defined in
+ * "mibank.h"), and call miInitializeBanking().
+ */
+ if (!miInitializeBanking(pScreen, pScrn->virtualX, pScrn->virtualY,
+ pScrn->displayWidth, pBankInfo))
+ return FALSE;
+
+ /*
+ * If backing store is to be supported (as is usually the case),
+ * initialise it.
+ */
+ miInitializeBackingStore(pScreen);
+
+ /*
+ * Set initial black & white colourmap indices.
+ */
+ xf86SetBlackWhitePixels(pScreen);
+
+ /*
+ * Install colourmap functions. If using the vgahw module,
+ * vgaHandleColormaps would usually be called here.
+ */
+
+ ...
+
+ /*
+ * Initialise cursor functions. This example is for the mi
+ * software cursor.
+ */
+ miDCInitialize(pScreen, xf86GetPointerScreenFuncs());
+
+ /* Initialise the default colourmap */
+ switch (pScrn->depth) {
+ case 1:
+ if (!xf1bppCreateDefColormap(pScreen))
+ return FALSE;
+ break;
+ case 4:
+ if (!xf4bppCreateDefColormap(pScreen))
+ return FALSE;
+ break;
+ default:
+ if (!cfbCreateDefColormap(pScreen))
+ return FALSE;
+ break;
+ }
+
+ /*
+ * Wrap the CloseScreen vector and set SaveScreen.
+ */
+ ZZZPTR(pScrn)->CloseScreen = pScreen->CloseScreen;
+ pScreen->CloseScreen = ZZZCloseScreen;
+ pScreen->SaveScreen = ZZZSaveScreen;
+
+ /* Report any unused options (only for the first generation) */
+ if (serverGeneration == 1) {
+ xf86ShowUnusedOptions(pScrn->scrnIndex, pScrn->options);
+ }
+
+ /* Done */
+ return TRUE;
+}
+ </code>
+
+
+<sect2>SwitchMode
+<p>
+
+ Define the &s.code;SwitchMode()&e.code; function if mode switching
+ is supported by the driver.
+
+ <code>
+static Bool
+ZZZSwitchMode(int scrnIndex, DisplayModePtr mode, int flags)
+{
+ return ZZZModeInit(xf86Screens[scrnIndex], mode);
+}
+ </code>
+
+
+<sect2>AdjustFrame
+<p>
+
+ Define the &s.code;AdjustFrame()&e.code; function if the driver
+ supports this.
+
+ <code>
+static void
+ZZZAdjustFrame(int scrnIndex, int x, int y, int flags)
+{
+ /* Adjust the viewport */
+}
+ </code>
+
+
+<sect2>EnterVT, LeaveVT
+<p>
+
+ Define the &s.code;EnterVT()&e.code; and &s.code;LeaveVT()&e.code;
+ functions.
+
+ These functions are mandatory.
+
+ <code>
+static Bool
+ZZZEnterVT(int scrnIndex, int flags)
+{
+ ScrnInfoPtr pScrn = xf86Screens[scrnIndex];
+ return ZZZModeInit(pScrn, pScrn->currentMode);
+}
+
+static void
+ZZZLeaveVT(int scrnIndex, int flags)
+{
+ ScrnInfoPtr pScrn = xf86Screens[scrnIndex];
+ ZZZRestore(pScrn);
+}
+ </code>
+
+<sect2>CloseScreen
+<p>
+
+ Define the &s.code;CloseScreen()&e.code; function:
+
+ This function is mandatory. Note that it unwraps the previously
+ wrapped &s.code;pScreen-&gt;CloseScreen&e.code;, and finishes by
+ calling it.
+
+ <code>
+static Bool
+ZZZCloseScreen(int scrnIndex, ScreenPtr pScreen)
+{
+ ScrnInfoPtr pScrn = xf86Screens[scrnIndex];
+ if (pScrn->vtSema) {
+ ZZZRestore(pScrn);
+ ZZZUnmapMem(pScrn);
+ }
+ pScrn->vtSema = FALSE;
+ pScreen->CloseScreen = ZZZPTR(pScrn)->CloseScreen;
+ return (*pScreen->CloseScreen)(scrnIndex, pScreen);
+}
+ </code>
+
+<sect2>SaveScreen
+<p>
+
+ Define the &s.code;SaveScreen()&e.code; function (the screen
+ blanking function). When using the vgahw module, this will typically
+ be:
+
+ <code>
+static Bool
+ZZZSaveScreen(ScreenPtr pScreen, int mode)
+{
+ return vgaHWSaveScreen(pScreen, mode);
+}
+ </code>
+
+ This function is mandatory. Before modifying any hardware register
+ directly this function needs to make sure that the Xserver is active
+ by checking if &s.code;pScrn&e.code; is non-NULL and for
+ &s.code;pScrn->vtSema == TRUE&e.code;.
+
+<sect2>FreeScreen
+<p>
+
+ Define the &s.code;FreeScreen()&e.code; function. This function
+ is optional. It should be defined if the &s.code;ScrnInfoRec&e.code;
+ &s.code;driverPrivate&e.code; field is used so that it can be freed
+ when a screen is deleted by the common layer for reasons possibly
+ beyond the driver's control. This function is not used in during
+ normal (error free) operation. The per-generation data is freed by
+ the &s.code;CloseScreen()&e.code; function.
+
+ <code>
+static void
+ZZZFreeScreen(int scrnIndex, int flags)
+{
+ /*
+ * If the vgahw module is used vgaHWFreeHWRec() would be called
+ * here.
+ */
+ ZZZFreeRec(xf86Screens[scrnIndex]);
+}
+ </code>
+
+
+</article>
diff --git a/xorg-server/hw/xfree86/doc/sgml/Makefile.am b/xorg-server/hw/xfree86/doc/sgml/Makefile.am
new file mode 100644
index 000000000..d2c821c03
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/sgml/Makefile.am
@@ -0,0 +1,54 @@
+# Copyright 2005 Red Hat, Inc.
+#
+# Permission to use, copy, modify, distribute, and sell this software
+# and its documentation for any purpose is hereby granted without
+# fee, provided that the above copyright notice appear in all copies
+# and that both that copyright notice and this permission notice
+# appear in supporting documentation, and that the name of Red Hat
+# not be used in advertising or publicity pertaining to distribution
+# of the software without specific, written prior permission. Red
+# Hat makes no representations about the suitability of this software
+# for any purpose. It is provided "as is" without express or implied
+# warranty.
+#
+# RED HAT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
+# NO EVENT SHALL RED HAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+# NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+SGML_FILES = DESIGN.sgml
+
+if BUILD_LINUXDOC
+TXT_FILES = $(SGML_FILES:%.sgml=%.txt)
+PS_FILES = $(SGML_FILES:%.sgml=%.ps)
+if BUILD_PDFDOC
+PDF_FILES = $(SGML_FILES:%.sgml=%.pdf)
+endif
+HTML_FILES = $(SGML_FILES:%.sgml=%.html)
+
+SUFFIXES = .sgml .txt .html .ps .pdf
+
+.sgml.txt:
+ @rm -f $@
+ $(MAKE_TEXT) $<
+
+.sgml.ps:
+ @rm -f $@
+ $(MAKE_PS) $<
+
+.ps.pdf:
+ @rm -f $@
+ $(MAKE_PDF) $<
+
+.sgml.html:
+ @rm -f $@
+ $(MAKE_HTML) $<
+
+noinst_DATA = $(TXT_FILES) $(PS_FILES) $(PDF_FILES) $(HTML_FILES)
+CLEANFILES = $(TXT_FILES) $(PS_FILES) $(PDF_FILES) $(HTML_FILES)
+endif
+
+EXTRA_DIST = $(SGML_FILES)
diff --git a/xorg-server/hw/xfree86/doc/sgml/Makefile.in b/xorg-server/hw/xfree86/doc/sgml/Makefile.in
new file mode 100644
index 000000000..3ee4d8cdd
--- /dev/null
+++ b/xorg-server/hw/xfree86/doc/sgml/Makefile.in
@@ -0,0 +1,581 @@
+# Makefile.in generated by automake 1.10.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+# Copyright 2005 Red Hat, Inc.
+#
+# Permission to use, copy, modify, distribute, and sell this software
+# and its documentation for any purpose is hereby granted without
+# fee, provided that the above copyright notice appear in all copies
+# and that both that copyright notice and this permission notice
+# appear in supporting documentation, and that the name of Red Hat
+# not be used in advertising or publicity pertaining to distribution
+# of the software without specific, written prior permission. Red
+# Hat makes no representations about the suitability of this software
+# for any purpose. It is provided "as is" without express or implied
+# warranty.
+#
+# RED HAT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
+# NO EVENT SHALL RED HAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+# NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+VPATH = @srcdir@
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = hw/xfree86/doc/sgml
+DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \
+ $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+ $(ACLOCAL_M4)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/include/do-not-use-config.h \
+ $(top_builddir)/include/xorg-server.h \
+ $(top_builddir)/include/dix-config.h \
+ $(top_builddir)/include/xgl-config.h \
+ $(top_builddir)/include/xorg-config.h \
+ $(top_builddir)/include/xkb-config.h \
+ $(top_builddir)/include/xwin-config.h \
+ $(top_builddir)/include/kdrive-config.h
+CONFIG_CLEAN_FILES =
+SOURCES =
+DIST_SOURCES =
+DATA = $(noinst_DATA)
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+ACLOCAL = @ACLOCAL@
+ADMIN_MAN_DIR = @ADMIN_MAN_DIR@
+ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@
+ALLOCA = @ALLOCA@
+AMTAR = @AMTAR@
+APPDEFAULTDIR = @APPDEFAULTDIR@
+APPLE_APPLICATIONS_DIR = @APPLE_APPLICATIONS_DIR@
+APP_MAN_DIR = @APP_MAN_DIR@
+APP_MAN_SUFFIX = @APP_MAN_SUFFIX@
+AR = @AR@
+AS = @AS@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BASE_FONT_PATH = @BASE_FONT_PATH@
+BUILD_DATE = @BUILD_DATE@
+BUILD_TIME = @BUILD_TIME@
+CC = @CC@
+CCAS = @CCAS@
+CCASDEPMODE = @CCASDEPMODE@
+CCASFLAGS = @CCASFLAGS@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+COMPILEDDEFAULTFONTPATH = @COMPILEDDEFAULTFONTPATH@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CXX = @CXX@
+CXXCPP = @CXXCPP@
+CXXDEPMODE = @CXXDEPMODE@
+CXXFLAGS = @CXXFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DARWIN_LIBS = @DARWIN_LIBS@
+DBUS_CFLAGS = @DBUS_CFLAGS@
+DBUS_LIBS = @DBUS_LIBS@
+DEFAULT_LIBRARY_PATH = @DEFAULT_LIBRARY_PATH@
+DEFAULT_LOGPREFIX = @DEFAULT_LOGPREFIX@
+DEFAULT_MODULE_PATH = @DEFAULT_MODULE_PATH@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DGA_CFLAGS = @DGA_CFLAGS@
+DGA_LIBS = @DGA_LIBS@
+DIX_CFLAGS = @DIX_CFLAGS@
+DLLTOOL = @DLLTOOL@
+DMXEXAMPLES_DEP_CFLAGS = @DMXEXAMPLES_DEP_CFLAGS@
+DMXEXAMPLES_DEP_LIBS = @DMXEXAMPLES_DEP_LIBS@
+DMXMODULES_CFLAGS = @DMXMODULES_CFLAGS@
+DMXMODULES_LIBS = @DMXMODULES_LIBS@
+DMXXIEXAMPLES_DEP_CFLAGS = @DMXXIEXAMPLES_DEP_CFLAGS@
+DMXXIEXAMPLES_DEP_LIBS = @DMXXIEXAMPLES_DEP_LIBS@
+DMXXMUEXAMPLES_DEP_CFLAGS = @DMXXMUEXAMPLES_DEP_CFLAGS@
+DMXXMUEXAMPLES_DEP_LIBS = @DMXXMUEXAMPLES_DEP_LIBS@
+DRI2PROTO_CFLAGS = @DRI2PROTO_CFLAGS@
+DRI2PROTO_LIBS = @DRI2PROTO_LIBS@
+DRIPROTO_CFLAGS = @DRIPROTO_CFLAGS@
+DRIPROTO_LIBS = @DRIPROTO_LIBS@
+DRIVER_MAN_DIR = @DRIVER_MAN_DIR@
+DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@
+DRI_DRIVER_PATH = @DRI_DRIVER_PATH@
+DSYMUTIL = @DSYMUTIL@
+DTRACE = @DTRACE@
+ECHO = @ECHO@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+EXEEXT = @EXEEXT@
+F77 = @F77@
+FFLAGS = @FFLAGS@
+FILE_MAN_DIR = @FILE_MAN_DIR@
+FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@
+FREETYPE_CFLAGS = @FREETYPE_CFLAGS@
+FREETYPE_LIBS = @FREETYPE_LIBS@
+GLX_ARCH_DEFINES = @GLX_ARCH_DEFINES@
+GLX_DEFINES = @GLX_DEFINES@
+GL_CFLAGS = @GL_CFLAGS@
+GL_LIBS = @GL_LIBS@
+GREP = @GREP@
+HAL_CFLAGS = @HAL_CFLAGS@
+HAL_LIBS = @HAL_LIBS@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+KDRIVE_CFLAGS = @KDRIVE_CFLAGS@
+KDRIVE_INCS = @KDRIVE_INCS@
+KDRIVE_LIBS = @KDRIVE_LIBS@
+KDRIVE_LOCAL_LIBS = @KDRIVE_LOCAL_LIBS@
+KDRIVE_PURE_INCS = @KDRIVE_PURE_INCS@
+KDRIVE_PURE_LIBS = @KDRIVE_PURE_LIBS@
+LAUNCHD = @LAUNCHD@
+LDFLAGS = @LDFLAGS@
+LD_EXPORT_SYMBOLS_FLAG = @LD_EXPORT_SYMBOLS_FLAG@
+LEX = @LEX@
+LEXLIB = @LEXLIB@
+LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@
+LIBDRM_CFLAGS = @LIBDRM_CFLAGS@
+LIBDRM_LIBS = @LIBDRM_LIBS@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIB_MAN_DIR = @LIB_MAN_DIR@
+LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@
+LINUXDOC = @LINUXDOC@
+LN_S = @LN_S@
+LTLIBOBJS = @LTLIBOBJS@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+MAKE_HTML = @MAKE_HTML@
+MAKE_PDF = @MAKE_PDF@
+MAKE_PS = @MAKE_PS@
+MAKE_TEXT = @MAKE_TEXT@
+MESA_SOURCE = @MESA_SOURCE@
+MISC_MAN_DIR = @MISC_MAN_DIR@
+MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@
+MKDIR_P = @MKDIR_P@
+MKFONTDIR = @MKFONTDIR@
+MKFONTSCALE = @MKFONTSCALE@
+NMEDIT = @NMEDIT@
+OBJC = @OBJC@
+OBJCCLD = @OBJCCLD@
+OBJCDEPMODE = @OBJCDEPMODE@
+OBJCFLAGS = @OBJCFLAGS@
+OBJCLINK = @OBJCLINK@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OPENSSL_CFLAGS = @OPENSSL_CFLAGS@
+OPENSSL_LIBS = @OPENSSL_LIBS@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PCIACCESS_CFLAGS = @PCIACCESS_CFLAGS@
+PCIACCESS_LIBS = @PCIACCESS_LIBS@
+PCI_TXT_IDS_PATH = @PCI_TXT_IDS_PATH@
+PERL = @PERL@
+PKG_CONFIG = @PKG_CONFIG@
+PROJECTROOT = @PROJECTROOT@
+PS2PDF = @PS2PDF@
+RANLIB = @RANLIB@
+RAWCPP = @RAWCPP@
+RAWCPPFLAGS = @RAWCPPFLAGS@
+SED = @SED@
+SERVER_MISC_CONFIG_PATH = @SERVER_MISC_CONFIG_PATH@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+SOLARIS_ASM_CFLAGS = @SOLARIS_ASM_CFLAGS@
+SOLARIS_INOUT_ARCH = @SOLARIS_INOUT_ARCH@
+STRIP = @STRIP@
+TSLIB_CFLAGS = @TSLIB_CFLAGS@
+TSLIB_LIBS = @TSLIB_LIBS@
+UTILS_SYS_LIBS = @UTILS_SYS_LIBS@
+VENDOR_MAN_VERSION = @VENDOR_MAN_VERSION@
+VENDOR_NAME = @VENDOR_NAME@
+VENDOR_NAME_SHORT = @VENDOR_NAME_SHORT@
+VENDOR_RELEASE = @VENDOR_RELEASE@
+VERSION = @VERSION@
+X11APP_ARCHS = @X11APP_ARCHS@
+X11EXAMPLES_DEP_CFLAGS = @X11EXAMPLES_DEP_CFLAGS@
+X11EXAMPLES_DEP_LIBS = @X11EXAMPLES_DEP_LIBS@
+XDMCP_CFLAGS = @XDMCP_CFLAGS@
+XDMCP_LIBS = @XDMCP_LIBS@
+XDMXCONFIG_DEP_CFLAGS = @XDMXCONFIG_DEP_CFLAGS@
+XDMXCONFIG_DEP_LIBS = @XDMXCONFIG_DEP_LIBS@
+XDMX_CFLAGS = @XDMX_CFLAGS@
+XDMX_LIBS = @XDMX_LIBS@
+XDMX_SYS_LIBS = @XDMX_SYS_LIBS@
+XEGLMODULES_CFLAGS = @XEGLMODULES_CFLAGS@
+XEGL_LIBS = @XEGL_LIBS@
+XEGL_SYS_LIBS = @XEGL_SYS_LIBS@
+XEPHYR_CFLAGS = @XEPHYR_CFLAGS@
+XEPHYR_DRI_LIBS = @XEPHYR_DRI_LIBS@
+XEPHYR_INCS = @XEPHYR_INCS@
+XEPHYR_LIBS = @XEPHYR_LIBS@
+XF86CONFIGFILE = @XF86CONFIGFILE@
+XF86MISC_CFLAGS = @XF86MISC_CFLAGS@
+XF86MISC_LIBS = @XF86MISC_LIBS@
+XF86VIDMODE_CFLAGS = @XF86VIDMODE_CFLAGS@
+XF86VIDMODE_LIBS = @XF86VIDMODE_LIBS@
+XGLMODULES_CFLAGS = @XGLMODULES_CFLAGS@
+XGLMODULES_LIBS = @XGLMODULES_LIBS@
+XGLXMODULES_CFLAGS = @XGLXMODULES_CFLAGS@
+XGLXMODULES_LIBS = @XGLXMODULES_LIBS@
+XGLX_LIBS = @XGLX_LIBS@
+XGLX_SYS_LIBS = @XGLX_SYS_LIBS@
+XGL_LIBS = @XGL_LIBS@
+XGL_MODULE_PATH = @XGL_MODULE_PATH@
+XGL_SYS_LIBS = @XGL_SYS_LIBS@
+XKB_BASE_DIRECTORY = @XKB_BASE_DIRECTORY@
+XKB_BIN_DIRECTORY = @XKB_BIN_DIRECTORY@
+XKB_COMPILED_DIR = @XKB_COMPILED_DIR@
+XKM_OUTPUT_DIR = @XKM_OUTPUT_DIR@
+XLIB_CFLAGS = @XLIB_CFLAGS@
+XLIB_LIBS = @XLIB_LIBS@
+XNESTMODULES_CFLAGS = @XNESTMODULES_CFLAGS@
+XNESTMODULES_LIBS = @XNESTMODULES_LIBS@
+XNEST_LIBS = @XNEST_LIBS@
+XNEST_SYS_LIBS = @XNEST_SYS_LIBS@
+XORGCFG_DEP_CFLAGS = @XORGCFG_DEP_CFLAGS@
+XORGCFG_DEP_LIBS = @XORGCFG_DEP_LIBS@
+XORGCONFIG_DEP_CFLAGS = @XORGCONFIG_DEP_CFLAGS@
+XORGCONFIG_DEP_LIBS = @XORGCONFIG_DEP_LIBS@
+XORG_CFLAGS = @XORG_CFLAGS@
+XORG_INCS = @XORG_INCS@
+XORG_LIBS = @XORG_LIBS@
+XORG_MODULES_CFLAGS = @XORG_MODULES_CFLAGS@
+XORG_MODULES_LIBS = @XORG_MODULES_LIBS@
+XORG_OS = @XORG_OS@
+XORG_OS_SUBDIR = @XORG_OS_SUBDIR@
+XORG_SYS_LIBS = @XORG_SYS_LIBS@
+XPRINTMODULES_CFLAGS = @XPRINTMODULES_CFLAGS@
+XPRINTMODULES_LIBS = @XPRINTMODULES_LIBS@
+XPRINTPROTO_CFLAGS = @XPRINTPROTO_CFLAGS@
+XPRINTPROTO_LIBS = @XPRINTPROTO_LIBS@
+XPRINT_CFLAGS = @XPRINT_CFLAGS@
+XPRINT_LIBS = @XPRINT_LIBS@
+XPRINT_SYS_LIBS = @XPRINT_SYS_LIBS@
+XRESEXAMPLES_DEP_CFLAGS = @XRESEXAMPLES_DEP_CFLAGS@
+XRESEXAMPLES_DEP_LIBS = @XRESEXAMPLES_DEP_LIBS@
+XSDL_INCS = @XSDL_INCS@
+XSDL_LIBS = @XSDL_LIBS@
+XSERVERCFLAGS_CFLAGS = @XSERVERCFLAGS_CFLAGS@
+XSERVERCFLAGS_LIBS = @XSERVERCFLAGS_LIBS@
+XSERVERLIBS_CFLAGS = @XSERVERLIBS_CFLAGS@
+XSERVERLIBS_LIBS = @XSERVERLIBS_LIBS@
+XSERVER_LIBS = @XSERVER_LIBS@
+XSERVER_SYS_LIBS = @XSERVER_SYS_LIBS@
+XTSTEXAMPLES_DEP_CFLAGS = @XTSTEXAMPLES_DEP_CFLAGS@
+XTSTEXAMPLES_DEP_LIBS = @XTSTEXAMPLES_DEP_LIBS@
+XVFB_LIBS = @XVFB_LIBS@
+XVFB_SYS_LIBS = @XVFB_SYS_LIBS@
+XWINMODULES_CFLAGS = @XWINMODULES_CFLAGS@
+XWINMODULES_LIBS = @XWINMODULES_LIBS@
+XWIN_LIBS = @XWIN_LIBS@
+XWIN_SERVER_NAME = @XWIN_SERVER_NAME@
+XWIN_SYS_LIBS = @XWIN_SYS_LIBS@
+YACC = @YACC@
+YFLAGS = @YFLAGS@
+__XCONFIGFILE__ = @__XCONFIGFILE__@
+abi_ansic = @abi_ansic@
+abi_extension = @abi_extension@
+abi_font = @abi_font@
+abi_videodrv = @abi_videodrv@
+abi_xinput = @abi_xinput@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_CXX = @ac_ct_CXX@
+ac_ct_F77 = @ac_ct_F77@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+driverdir = @driverdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+extdir = @extdir@
+ft_config = @ft_config@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+launchagentsdir = @launchagentsdir@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+logdir = @logdir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+moduledir = @moduledir@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sbindir = @sbindir@
+sdkdir = @sdkdir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+xglmoduledir = @xglmoduledir@
+xpconfigdir = @xpconfigdir@
+SGML_FILES = DESIGN.sgml
+@BUILD_LINUXDOC_TRUE@TXT_FILES = $(SGML_FILES:%.sgml=%.txt)
+@BUILD_LINUXDOC_TRUE@PS_FILES = $(SGML_FILES:%.sgml=%.ps)
+@BUILD_LINUXDOC_TRUE@@BUILD_PDFDOC_TRUE@PDF_FILES = $(SGML_FILES:%.sgml=%.pdf)
+@BUILD_LINUXDOC_TRUE@HTML_FILES = $(SGML_FILES:%.sgml=%.html)
+@BUILD_LINUXDOC_TRUE@SUFFIXES = .sgml .txt .html .ps .pdf
+@BUILD_LINUXDOC_TRUE@noinst_DATA = $(TXT_FILES) $(PS_FILES) $(PDF_FILES) $(HTML_FILES)
+@BUILD_LINUXDOC_TRUE@CLEANFILES = $(TXT_FILES) $(PS_FILES) $(PDF_FILES) $(HTML_FILES)
+EXTRA_DIST = $(SGML_FILES)
+all: all-am
+
+.SUFFIXES:
+.SUFFIXES: .sgml .txt .html .ps .pdf
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps)
+ @for dep in $?; do \
+ case '$(am__configure_deps)' in \
+ *$$dep*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \
+ && exit 0; \
+ exit 1;; \
+ esac; \
+ done; \
+ echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign hw/xfree86/doc/sgml/Makefile'; \
+ cd $(top_srcdir) && \
+ $(AUTOMAKE) --foreign hw/xfree86/doc/sgml/Makefile
+.PRECIOUS: Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ @case '$?' in \
+ *config.status*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+ *) \
+ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+ esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+tags: TAGS
+TAGS:
+
+ctags: CTAGS
+CTAGS:
+
+
+distdir: $(DISTFILES)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ list='$(DISTFILES)'; \
+ dist_files=`for file in $$list; do echo $$file; done | \
+ sed -e "s|^$$srcdirstrip/||;t" \
+ -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+ case $$dist_files in \
+ */*) $(MKDIR_P) `echo "$$dist_files" | \
+ sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+ sort -u` ;; \
+ esac; \
+ for file in $$dist_files; do \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+ cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
+ fi; \
+ cp -pR $$d/$$file $(distdir)$$dir || exit 1; \
+ else \
+ test -f $(distdir)/$$file \
+ || cp -p $$d/$$file $(distdir)/$$file \
+ || exit 1; \
+ fi; \
+ done
+check-am: all-am
+check: check-am
+all-am: Makefile $(DATA)
+installdirs:
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ `test -z '$(STRIP)' || \
+ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+ -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+ -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-am
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am:
+
+html: html-am
+
+info: info-am
+
+info-am:
+
+install-data-am:
+
+install-dvi: install-dvi-am
+
+install-exec-am:
+
+install-html: install-html-am
+
+install-info: install-info-am
+
+install-man:
+
+install-pdf: install-pdf-am
+
+install-ps: install-ps-am
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am:
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-generic clean-libtool \
+ distclean distclean-generic distclean-libtool distdir dvi \
+ dvi-am html html-am info info-am install install-am \
+ install-data install-data-am install-dvi install-dvi-am \
+ install-exec install-exec-am install-html install-html-am \
+ install-info install-info-am install-man install-pdf \
+ install-pdf-am install-ps install-ps-am install-strip \
+ installcheck installcheck-am installdirs maintainer-clean \
+ maintainer-clean-generic mostlyclean mostlyclean-generic \
+ mostlyclean-libtool pdf pdf-am ps ps-am uninstall uninstall-am
+
+
+@BUILD_LINUXDOC_TRUE@.sgml.txt:
+@BUILD_LINUXDOC_TRUE@ @rm -f $@
+@BUILD_LINUXDOC_TRUE@ $(MAKE_TEXT) $<
+
+@BUILD_LINUXDOC_TRUE@.sgml.ps:
+@BUILD_LINUXDOC_TRUE@ @rm -f $@
+@BUILD_LINUXDOC_TRUE@ $(MAKE_PS) $<
+
+@BUILD_LINUXDOC_TRUE@.ps.pdf:
+@BUILD_LINUXDOC_TRUE@ @rm -f $@
+@BUILD_LINUXDOC_TRUE@ $(MAKE_PDF) $<
+
+@BUILD_LINUXDOC_TRUE@.sgml.html:
+@BUILD_LINUXDOC_TRUE@ @rm -f $@
+@BUILD_LINUXDOC_TRUE@ $(MAKE_HTML) $<
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT: