diff options
Diffstat (limited to 'xorg-server/hw/xfree86/doc')
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          "> +] > + +<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->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->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 -> config file -> 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 ID << 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 < C < 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->options&e.code;. This function requires that + &s.code;pScrn->confScreen&e.code;, &s.code;pScrn->display&e.code;, + &s.code;pScrn->monitor&e.code;, + &s.code;pScrn->numEntities&e.code;, and + &s.code;pScrn->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 == 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->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->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 > 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->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->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->HDisplay&e.code; and + &s.code;mode->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 × 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 × 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->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 > 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->Clock * + ClockMulFactor) / ClockDivFactor&e.code;. + + </quote> + &s.code;PrivFlags&e.code; + <quote><p> + This field is copied into the + &s.code;mode->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->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->SynthClock = + &f.indent;(mode->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->numClocks&e.code;, + and the probed clocks are set in the &s.code;pScrn->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->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->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->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->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 * 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->paletteEnabled&e.code; in order to + preserve the palette access state. It should be cleared when + &s.code;hwp->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->paletteEnabled&e.code; in order to + preserve the palette access state. It should be cleared when + &s.code;hwp->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->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->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 = { &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(&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, + &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, &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, &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, + &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, &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->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: |